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 blueprint-driven and guides you through runtime, event bridge, server, linting, and module-format 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.

The same generator is also available through the main CLI:

bash
purista init my-app

Both entry points use the same underlying engine, so npm create purista@latest and purista init generate the same project shape.

For non-interactive scripts and CI:

bash
purista init my-app --defaults --non-interactive --no-install

Non-interactive mode never prompts. It applies only declared defaults and fails fast when required values are still missing.

PURISTA CLI ​

PURISTA provides a command line interface (CLI) that supports three usage modes:

  • interactive usage for humans
  • non-interactive usage for scripts and CI
  • programmatic usage for tools and agents

The CLI allows you to create new projects and add services, 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]

Programmatic callers can use the same command engine through createPuristaCliEngine(...), resolvePuristaCommand(...), and runPuristaCommand(...).

Common commands ​

bash
purista init my-app
purista add service user --description "User service"
purista add command sign-up --service user --service-version 1 --description "Register a user"
purista add queue process-jobs --service user --service-version 1 --description "Background jobs"
purista add queue-worker process-jobs --service user --service-version 1 --queue processJobs
purista add agent triage --service user --service-version 1 --description "Review tickets"

Non-interactive behavior ​

  • --non-interactive disables prompts and fails on unresolved required input
  • --defaults and --yes apply only explicit defaults
  • interactive mode may ask only for unresolved values, but command validation stays the same across modes

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"
}