CLI Reference

Commands

`zebric dev`

Start a development server with hot reload:

zebric dev --blueprint blueprint.toml --port 3000 --seed

Flag	Default	Description
`-b, --blueprint <path>`	`blueprint.json`	Path to blueprint file
`-p, --port <number>`	`3000`	Port to listen on
`-h, --host <host>`	`localhost`	Host to bind to
`--seed`	—	Seed database with sample data

`zebric validate`

Validate a blueprint without starting the engine:

zebric validate --blueprint blueprint.toml

Returns validation errors and warnings without starting a server. Useful for CI checks.

Environment Variables

Variable	Description
`SLACK_BOT_TOKEN`	Slack bot token (for Slack notification adapter)
`SLACK_SIGNING_SECRET`	Slack webhook signing secret

API key environment variables are defined per key in [[auth.apiKeys]] using the keyEnv field.

zebric dev takes its host, port, and Blueprint path from command-line flags; it does not read HOST or PORT.

The lower-level zebric-engine binary additionally reads:

Variable	Description
`DATABASE_URL`	SQLite or PostgreSQL connection URL
`ZEBRIC_RATE_LIMIT_MAX`	Maximum requests in one rate-limit window
`ZEBRIC_RATE_LIMIT_WINDOW_MS`	Rate-limit window length in milliseconds

zebric-engine defaults to --host 0.0.0.0, while zebric dev defaults to localhost.

`zebric benchmark`

Run the repository’s internal Big Zebra benchmark harness. This command forwards remaining arguments to benchmark/cli.mjs in the current workspace and is intended for Zebric contributors rather than application deployment.

Story Runner

Run integration tests for example blueprints:

pnpm --filter @zebric/framework-stories test

Stories validate that blueprint parsing, page routing, form configuration, workflow wiring, and notification setup all remain correct.

Zebric Agent CLI

`zebric-agent validate`

Parse and validate a Blueprint without a model or running application:

zebric-agent validate [blueprint] [--workspace <root>] [--json]

The Blueprint defaults to blueprint.toml, and the workspace defaults to the current directory. The resolved path must remain inside the workspace.

`zebric-agent run`

Run one non-interactive agent task:

zebric-agent run \
  --prompt <text> \
  --model <provider:model> \
  [--connect <url>] \
  [--credential-env <name>] \
  [--workspace <root>] \
  [--approve-operation <operation-id>] \
  [--run-id <id>] \
  [--json]

--approve-operation may be repeated and requires --connect. Mutations whose exact operation ID is absent are rejected locally. --run-id requires an approved operation and contributes to deterministic idempotency keys. --credential-env names an environment variable; it never accepts the credential value directly.

With --json, success and failure are written as one JSON object. Configured application credentials are redacted from both output paths.

Exit codes

Code	Category
`0`	Success
`1`	Internal error
`2`	Invalid CLI or agent configuration
`3`	Blueprint validation failure
`4`	Mutation approval rejected
`5`	Authentication or authorization failure
`6`	State or idempotency conflict
`7`	Incomplete execution, such as job observation timeout

See Get Started with Zebric Agent for a complete read-only invocation.