PURISTA

Appearance

CLI ​

Create a new project ​

The easiest and fastest way to start with PURISTA is using your package manager's create command.
The scaffold is based on blueprint templates and guides you through runtime/event bridge/server choices.

In the project folder, simply execute:

bash
npm create purista@latest
bash
bun create purista@latest
bash
yarn create purista@latest
bash
pnpm create purista@latest

The CLI tool will guide you through all the necessary steps.

PURISTA CLI ​

PURISTA provides a command line interface (CLI) that allows you to create new services and add commands, subscriptions, streams, queues, queue workers, and AI agents to existing services.

You can either install the CLI globally, or run it with npx.

Global install:

bash
npm install -g @purista/cli
bash
bun add --global @purista/cli
bash
yarn global add @purista/cli
bash
pnpm add -g @purista/cli

In your project root run:

bash
purista add [service|command|subscription|stream|queue|queue-worker|agent]

Or without global install:

bash
npx @purista/cli add [service|command|subscription|stream|queue|queue-worker|agent]

Generated command, subscription, and queue schema stubs default to z.unknown() for payloads. This keeps generated code type-safe by default and avoids accidental any propagation. The queue wizard also inserts .canEnqueue() declarations plus optional producer commands so you can expose HTTP 202 Accepted endpoints immediately.

Keep CLI-Managed Definition Lists

When the CLI generates or updates service files, keep commandDefinitions and subscriptionDefinitions as typed constants. Renaming or untyping these lists can break follow-up CLI updates and weaken inferred types.

PURISTA config file ​

Since version 1.12.0, the PURISTA CLI expects to find a purista.json file in the root of your project. This file contains basic information about your project. Especially the settings for file and event casing conventions are important.

Schema ​

This configuration file follows the JSON Schema specification.

json
{
  "$schema": "https://purista.dev/schemas/1.12.0/schema.json",
  "type": "object",
  "properties": { ... }
}

Configuration Options ​

$schema ​

  • Type: string
  • Description: A field for the JSON schema specification.
  • Default: https://purista.dev/schemas/1.12.0/schema.json

runtime ​

  • Type: string
  • Allowed Values: node, bun
  • Default: node
  • Description: Specifies the runtime environment for the project.

eventBridge ​

  • Type: string
  • Allowed Values: default, amqp, nats, mqtt, dapr
  • Default: default
  • Description: Defines the event bridge used in the project.

fileConvention ​

  • Type: string
  • Allowed Values: camel, snake, kebab, pascal, pascalSnake
  • Default: camel
  • Description: Determines the file naming convention used in the project.

eventConvention ​

  • Type: string
  • Allowed Values: camel, snake, kebab, pascal, pascalSnake, constantCase, dotCase, pathCase, trainCase
  • Default: camel
  • Description: Determines the naming convention for events in the project.

linter ​

  • Type: string
  • Allowed Values: biome, eslint, none
  • Default: none
  • Description: Specifies the linter used in the project.

formatter ​

  • Type: string
  • Allowed Values: biome, prettier, none
  • Default: none
  • Description: Specifies the formatter used in the project.

servicePath ​

  • Type: string
  • Default: src/service
  • Description: Defines the relative path where services are located in the project.

agentPath ​

  • Type: string
  • Default: src/agents
  • Description: Defines the relative path where agents are located in the project.

Example purista.json Configuration ​

json
{
  "$schema": "https://purista.dev/schemas/1.12.0/schema.json",
  "runtime": "node",
  "eventBridge": "nats",
  "fileConvention": "kebab",
  "eventConvention": "dotCase",
  "linter": "eslint",
  "formatter": "prettier",
  "servicePath": "src/services"
}

Use purista add agent to scaffold an AI workload manifest powered by @purista/ai. The generator creates an AgentBuilder under src/agents/<name>/v<version>/ plus a prepared Vitest spec that already boots an in-memory event bridge, injects a deterministic provider, executes one agent run, and checks protocol frames. Agents run beside services—no helper command is required. After filling in the handler, call <yourAgent>.getInstance(eventBridge, options) inside your bootstrap and invoke from commands/subscriptions via .canInvokeAgent(...)/context.invokeAgent (or use invokeAgent for scripts/tests outside a Purista context).