CLI & Developer Experience
This document defines Zakardo’s command-line interface, developer experience tooling, and the local development workflow. It covers the
zakardoCLI binary, every command and subcommand, project scaffolding viacreate-zakardo, the development server, the build and validation pipeline, code generators, and Zakardo Studio integration.
Prerequisites: This document assumes familiarity with Full-Stack Framework, Data Layer, Capability System, Policy and Governance, Plan Library, Training and Validation, Execution Engine, and Runtime API.
1. Design Goals
Section titled “1. Design Goals”- Zero-to-running in one command.
npx create-zakardoscaffolds a complete project.zakardo devstarts everything. No manual wiring. - Convention over configuration. The CLI discovers capabilities, policies, plans, and training datasets from well-known directories. Explicit registration is unnecessary.
- Fast feedback loops. Hot-reloading for capabilities, policies, and plans. Instant Vite HMR for frontend. No full restart unless config changes.
- Validate before shipping.
zakardo validatecatches schema mismatches, missing effect declarations, broken policy references, and invalid plan bindings — all before runtime. - One CLI for everything. Developers never shell out to separate tools.
zakardo migratedelegates to Prisma/Drizzle.zakardo training runruns datasets.zakardo trace inspectopens traces. One binary. - Consistent across adapters. CLI commands behave the same regardless of the data adapter (Prisma vs. Drizzle). Adapter-specific behavior is transparent.
- Scriptable. Every command supports
--jsonoutput for CI/CD pipelines. Exit codes are well-defined. No interactive prompts when--yesorCI=true.
2. CLI Architecture
Section titled “2. CLI Architecture”2.1 Binary
Section titled “2.1 Binary”The CLI is distributed as @zakardo/cli and installed as a devDependency. The binary is zakardo:
// package.json (root){ "devDependencies": { "@zakardo/cli": "^1.0.0" }}The CLI resolves the closest @zakardo/core in the project’s node_modules and uses it to access capabilities, config, and adapter interfaces. It does not embed its own runtime — it delegates to the locally installed packages.
2.2 Command Structure
Section titled “2.2 Command Structure”zakardo <command> [subcommand] [options]
Commands: dev Start the development server build Build for production validate Validate all Zakardo artifacts migrate Run database migrations (via adapter) seed Seed the database training Run training datasets trace Inspect and manage traces plan Validate and manage plans policy Manage policies metadata Schema metadata operations studio Launch Zakardo Studio worker Start the execution worker <type>:new Generate scaffolds (capability, route, policy, plan, service, component)
Global options: --help Show help for command --version Show CLI version --json Output as JSON (for scripting) --verbose Show debug-level output --cwd <dir> Override working directory2.3 Execution Context
Section titled “2.3 Execution Context”Every command reads the project’s configuration from well-known locations:
config/zakardo.ts → Composed Zakardo configconfig/data.ts → Data adapter configconfig/auth.ts → Auth adapter configconfig/execution.ts → Execution configconfig/trace.ts → Trace configenv/schema.ts → Environment variable schemaThe CLI validates the environment and config before executing any command. If environment variables are missing, the CLI fails fast with a clear message:
$ zakardo validate
✗ Missing environment variables: DATABASE_URL (required by config/data.ts) OPENAI_API_KEY (required by config/zakardo.ts)
Copy env/.env.example to .env and fill in the values.3. Project Scaffolding
Section titled “3. Project Scaffolding”3.1 create-zakardo
Section titled “3.1 create-zakardo”A standalone package (create-zakardo) for bootstrapping new projects. Not part of the @zakardo/cli binary — invoked via npx:
$ npx create-zakardo my-crmInteractive prompts:
| Prompt | Options | Default |
|---|---|---|
| Database ORM | Prisma, Drizzle | Prisma |
| Authentication | Better Auth, None | Better Auth |
| Frontend framework | React (Vite), Vue (Vite), Angular, None | React |
| Include examples? | Yes (customer CRUD), No (empty) | Yes |
Non-interactive mode (CI):
npx create-zakardo my-crm \ --orm prisma \ --auth better-auth \ --frontend react \ --examples yes3.2 Generated Project Structure
Section titled “3.2 Generated Project Structure”my-crm/├── apps/│ ├── api/ # Hono backend│ │ ├── src/│ │ │ ├── server.ts # Entry point (Foundation + Zakardo mount)│ │ │ ├── foundation/ # Auth, billing, admin, API, webhooks, jobs│ │ │ └── zakardo/ # mountZakardo() + runtime glue│ │ └── tsconfig.json│ └── web/ # Frontend (React/Vue/Angular)│ ├── src/│ └── tsconfig.json├── packages/│ ├── shared/ # Shared types and utilities│ ├── db/ # Database schema + client│ ├── core/ # Zakardo core types (re-export from @zakardo/core)│ ├── capabilities/ # Business capability implementations│ └── catalog/ # A2UI component catalog├── config/ # Atomic config files│ ├── zakardo.ts│ ├── data.ts│ ├── auth.ts│ ├── execution.ts│ ├── trace.ts│ └── services.ts├── env/│ ├── schema.ts # Typed environment schema│ └── .env.example├── policies/ # Policy JSON files├── plans/ # Plan IR JSON files├── training/ # Training datasets├── infra/│ ├── docker-compose.yml # Local infrastructure (Postgres, Redis)│ ├── Dockerfile.api│ └── Dockerfile.web├── turbo.json # Turborepo config├── pnpm-workspace.yaml├── package.json└── tsconfig.json # Root TypeScript config3.3 Post-Scaffold Steps
Section titled “3.3 Post-Scaffold Steps”After scaffolding, create-zakardo automatically:
- Runs
pnpm install. - Starts Docker Compose (Postgres + Redis).
- Runs the initial database migration (
prisma migrate devordrizzle-kit push). - Applies Zakardo’s internal migrations (
zakardo_*tables). - Prints next steps:
Done! Next steps:cd my-crmzakardo dev
4. Development Server
Section titled “4. Development Server”4.1 zakardo dev
Section titled “4.1 zakardo dev”The primary development command. Starts all components with hot-reloading:
$ zakardo dev
Starting infrastructure... ✓ Docker Compose (postgres, redis)
Starting backend... ✓ Hono server on http://localhost:3000 ├── Foundation routes: /auth, /billing, /admin, /api/v1, /webhooks └── Zakardo Runtime: /zakardo/* ✓ 14 capabilities loaded ✓ 3 policies loaded ✓ 2 plans loaded
Starting frontend... ✓ Vite dev server on http://localhost:5173
Starting Zakardo Studio... ✓ Studio on http://localhost:3000/zakardo/studio
Watching for changes... ├── packages/capabilities/** → auto-reload capabilities ├── policies/** → auto-reload policies ├── plans/** → auto-reload plans ├── config/** → restart runtime └── packages/db/prisma/** → prompt migration4.2 Startup Sequence
Section titled “4.2 Startup Sequence”- Check prerequisites. Docker running? Node.js version ≥ 20? pnpm installed?
- Start infrastructure.
docker compose up -dfrominfra/docker-compose.yml(if not already running). - Run migrations. Check for pending database migrations. If found, prompt to apply.
- Validate environment. Load
env/schema.ts. Fail fast if required variables are missing. - Start backend. Launch Hono server with hot-reload (via
tsx watch). - Load Zakardo Runtime. Auto-discover and register capabilities, policies, plans. Extract schema metadata.
- Start frontend. Launch Vite dev server with HMR.
- Mount Studio. Serve
@zakardo/studioat/zakardo/studio. - Start watchers. File watchers on all Zakardo artifact directories.
4.3 File Watch Behavior
Section titled “4.3 File Watch Behavior”| Change | Action | Restart Required? |
|---|---|---|
| Capability source code | Re-register capability, hot-reload | No |
| Policy JSON file | Re-load policy set | No |
| Plan JSON file | Re-load plan library | No |
Config file (config/*) | Restart Zakardo Runtime | Yes (automatic) |
Database schema (prisma/schema.prisma) | Prompt developer to run migration | Developer action |
| Foundation route source | Standard Hono/tsx hot-reload | No |
| Frontend source code | Vite HMR | No (instant) |
4.4 Selective Start
Section titled “4.4 Selective Start”zakardo dev api # Backend only (no frontend, no Studio)zakardo dev web # Frontend only (expects backend running)zakardo dev studio # Studio only (opens in browser)zakardo dev --no-infra # Skip Docker Composezakardo dev --port 4000 # Custom backend port4.5 Port Configuration
Section titled “4.5 Port Configuration”| Component | Default Port | Environment Variable |
|---|---|---|
| Backend (Hono) | 3000 | PORT |
| Frontend (Vite) | 5173 | VITE_PORT |
| Studio | Same as backend (/zakardo/studio) | N/A |
| PostgreSQL | 5432 | PGPORT |
| Redis | 6379 | REDIS_PORT |
5. Build and Validation
Section titled “5. Build and Validation”5.1 zakardo build
Section titled “5.1 zakardo build”Builds the application for production deployment:
$ zakardo build
Validating environment... ✓ env/schema.ts valid
Type-checking... ✓ packages/shared ✓ packages/db ✓ packages/core ✓ packages/capabilities ✓ packages/catalog ✓ apps/api ✓ apps/web
Validating Zakardo artifacts... ✓ 14 capabilities: schemas valid, effects declared ✓ 3 policies: syntax valid, referenced capabilities exist ✓ 2 plans: IR valid, capabilities available, policies satisfied ✓ 5 training datasets: intent payloads parse, expected responses valid
Building... ✓ apps/api → apps/api/dist/ ✓ apps/web → apps/web/dist/
Build complete.Build pipeline:
- Validate environment variables (production mode).
- Type-check all packages in dependency order (via Turborepo).
- Run
zakardo validate(see §5.2). - Bundle backend with
tsuporesbuild. - Bundle frontend with Vite production build.
Options:
zakardo build --skip-validate # Skip artifact validationzakardo build --skip-types # Skip type-checkingzakardo build api # Build backend onlyzakardo build web # Build frontend only5.2 zakardo validate
Section titled “5.2 zakardo validate”Validates all Zakardo artifacts without building. Runs as part of zakardo build but can be invoked standalone for fast feedback:
$ zakardo validate
Capabilities... ✓ 14 capabilities: schemas valid ✓ Effect classes declared ✓ Idempotency patterns verified for WRITE/DESTRUCTIVE capabilities ✓ Interaction Specs have valid response schemas
Policies... ✓ 3 policies: syntax valid ✓ Referenced capabilities and tags exist ✓ Gate approver roles exist in auth config
Plans... ✓ 2 plans: IR valid ✓ Capability references resolve ✓ Data bindings valid ✓ Policy compliance verified
Training datasets... ✓ 5 datasets: format valid ✓ Intent payloads parseable ✓ Expected responses match output schemas
Config... ✓ config/zakardo.ts composes successfully ✓ Data adapter connects (dry-run) ✓ Auth provider initializes ✓ LLM providers reachable
All artifacts valid. ✓5.3 Validation Checks
Section titled “5.3 Validation Checks”| Category | Check | Severity |
|---|---|---|
| Capabilities | Input/output schemas are valid JSON Schema | Error |
effectClass is declared | Error | |
| Effect class matches actual behavior (heuristic) | Warning | |
| WRITE/DESTRUCTIVE capabilities have idempotency patterns | Warning | |
| Interaction Spec response schema is valid | Error | |
| Anchored View config references valid catalog components | Warning | |
| Policies | JSON syntax valid | Error |
| Referenced capabilities exist | Error | |
| Referenced tags exist on at least one capability | Warning | |
| Gate approver roles exist in auth config | Warning | |
| No contradictory rules (DENY + ALLOW on same capability) | Error | |
| Plans | Plan IR structure valid | Error |
| All capability references resolve | Error | |
| Data bindings reference valid step outputs | Error | |
| Step order respects dependencies | Error | |
| Policy compliance satisfied | Error | |
| Training | Dataset format valid | Error |
| Intent payloads are parseable | Error | |
| Expected outputs match capability output schemas | Warning | |
| Config | Config composition succeeds | Error |
| Data adapter can connect (dry-run) | Error | |
| Auth provider initializes | Warning | |
| LLM providers are reachable | Warning |
Exit codes:
| Code | Meaning |
|---|---|
0 | All checks passed |
1 | Errors found (at least one Error-severity check failed) |
2 | Warnings only (all Error checks passed) |
Selective validation:
zakardo validate capabilities # Capabilities onlyzakardo validate policies # Policies onlyzakardo validate plans # Plans onlyzakardo validate training # Training datasets onlyzakardo validate config # Configuration only5.4 zakardo plan validate
Section titled “5.4 zakardo plan validate”Validates a specific plan against the current capability set and policies. This is the CLI equivalent of what the Validator does at runtime (see Validator Specification):
$ zakardo plan validate plans/onboard-customer.json
Parsing Plan IR... ✓ Valid structure
Resolving capabilities... Step 0: create_customer → ✓ found (v1.0.0) Step 1: send_welcome_email → ✓ found (v1.0.0) Step 2: create_subscription → ✓ found (v1.0.0)
Checking data bindings... Step 1 input 'email' ← $steps[0].output.email → ✓ path valid Step 2 input 'customer_id' ← $steps[0].output.id → ✓ path valid
Policy compliance... Step 0 (create_customer, WRITE_INTERNAL): ✓ allowed Step 1 (send_welcome_email, WRITE_EXTERNAL): ✓ gate required → gate defined Step 2 (create_subscription, WRITE_EXTERNAL): ✓ gate required → gate defined
Plan valid. ✓6. Database Commands
Section titled “6. Database Commands”6.1 zakardo migrate
Section titled “6.1 zakardo migrate”Delegates to the project’s data adapter’s migration tool. The CLI does not implement migration logic — it calls the adapter’s runMigrations() method:
# Generate + apply migration (development)zakardo migrate dev
# Apply pending migrations (production)zakardo migrate deploy
# Check migration statuszakardo migrate status
# Reset database (development only)zakardo migrate resetAdapter delegation:
| Command | Prisma Adapter | Drizzle Adapter |
|---|---|---|
migrate dev | npx prisma migrate dev | npx drizzle-kit push |
migrate deploy | npx prisma migrate deploy | npx drizzle-kit migrate |
migrate status | npx prisma migrate status | npx drizzle-kit status |
migrate reset | npx prisma migrate reset | Drop + recreate via driver |
After any successful migration, Zakardo automatically:
- Re-runs its own internal migrations (
zakardo_*tables). - Refreshes schema metadata.
- Re-validates capabilities against the new schema.
6.2 zakardo seed
Section titled “6.2 zakardo seed”Seeds the database with initial or fixture data:
# Run the default seed scriptzakardo seed
# Seed the fixtures database (for TRAINING mode)zakardo seed --fixtures
# Seed from a specific scriptzakardo seed --script seeds/demo-data.tsSeed file convention:
import { defineSeed } from '@zakardo/core';import { PrismaClient } from '@my-app/db';
export default defineSeed(async (db: PrismaClient) => { await db.customer.createMany({ data: [ ], });});| Option | Description |
|---|---|
--fixtures | Target the fixtures database (FIXTURES_DB_URL). Used for training data. |
--script <path> | Run a specific seed file instead of seeds/default.ts. |
--reset | Truncate all business tables before seeding (does not touch zakardo_* tables). |
6.3 zakardo metadata
Section titled “6.3 zakardo metadata”Schema metadata operations:
# Refresh schema metadata from the databasezakardo metadata refresh
# Print extracted schema metadatazakardo metadata show
# Print schema metadata as JSONzakardo metadata show --jsonmetadata refresh is automatically called after zakardo migrate. The standalone command is useful for debugging or after manual schema changes.
7. Training Commands
Section titled “7. Training Commands”7.1 zakardo training run
Section titled “7.1 zakardo training run”Runs training datasets against the current capability set and Planner configuration:
# Run all training datasetszakardo training run
# Run a specific datasetzakardo training run customer-management
# Run with verbose outputzakardo training run --verboseOutput:
$ zakardo training run customer-management
Running: customer-management (12 cases)
Case 1: "Show me all active customers" Classification: ✓ GENERATE (expected: GENERATE) Plan generation: ✓ 1 step (list_customers) Capability match: ✓ list_customers Output match: ✓ matches expected schema
Case 2: "Create a new customer named Alice" Classification: ✓ GENERATE (expected: GENERATE) Plan generation: ✓ 1 step (create_customer) Capability match: ✓ create_customer Output match: ✓ matches expected schema
... (8 more cases)
Case 11: "What's your favorite color?" Classification: ✓ CONVERSE (expected: CONVERSE)
Case 12: "Delete all customers" (should be blocked) Policy block: ✓ DENY (bulk_delete_policy)
Results: 12/12 passed (100%)Duration: 8.4s7.2 zakardo training list
Section titled “7.2 zakardo training list”List all available training datasets:
zakardo training list
Datasets: customer-management 12 cases last run: 2026-02-10 20:30 order-processing 8 cases last run: 2026-02-09 14:15 email-workflows 5 cases never run7.3 Execution Mode
Section titled “7.3 Execution Mode”Training runs use the TRAINING execution mode. Capabilities execute against the fixtures database (seeded via zakardo seed --fixtures). No real data is touched.
8. Trace and Debugging Commands
Section titled “8. Trace and Debugging Commands”8.1 zakardo trace inspect
Section titled “8.1 zakardo trace inspect”Inspect execution traces from the CLI:
# List recent traceszakardo trace list
# Inspect a specific tracezakardo trace inspect trace_abc123
# Filter by statuszakardo trace list --status failed
# Show traces for a specific executionzakardo trace list --execution exec_9d4b3f2aOutput:
$ zakardo trace inspect trace_abc123
Trace: trace_abc123Execution: exec_9d4b3f2aIntent: "Show me all churned customers and send them a recovery email"Status: completedDuration: 3.2sStarted: 2026-02-10T20:00:00ZCompleted: 2026-02-10T20:00:03Z
Timeline: 0ms INTENT_RECEIVED 120ms PLANNER_CLASSIFICATION → GENERATE (0.92) 450ms STEP_GENERATED → list_customers 680ms STEP_GENERATED → send_email_batch 900ms PLAN_VALIDATED 950ms GATE_TRIGGERED → requires approval (send_email_batch is WRITE_EXTERNAL) 1200ms GATE_RESOLVED → approved 1250ms STEP_STARTED → list_customers 1590ms STEP_COMPLETED → list_customers (340ms, 2 results) 1600ms STEP_STARTED → send_email_batch 2800ms STEP_COMPLETED → send_email_batch (1200ms, 2 sent) 2850ms OUTBOX_COMMITTED 3200ms EXECUTION_COMPLETED
Step Details: [0] list_customers (READ) Input: { filter: { status: "churned" } } Output: { customers: [...], total: 2 } DB Queries: 1 (SELECT on customers, 12ms)
[1] send_email_batch (WRITE_EXTERNAL) Input: { recipients: [...], template_name: "recovery_promo" } Output: { sent_count: 2, failed: [] } Gate: approved by [email protected]8.2 zakardo trace export
Section titled “8.2 zakardo trace export”Export traces for offline analysis:
# Export as JSONzakardo trace export trace_abc123 --format json > trace.json
# Export recent traceszakardo trace export --last 10 --format json > recent-traces.json9. Policy Commands
Section titled “9. Policy Commands”9.1 zakardo policy
Section titled “9.1 zakardo policy”Manage policy files:
# List loaded policieszakardo policy list
# Create a new policy scaffoldzakardo policy create high-value-approval
# Enable/disable a policyzakardo policy enable high-value-approvalzakardo policy disable high-value-approval
# Validate all policieszakardo policy validate
# Test a policy against mock datazakardo policy test high-value-approval --capability create_order --inputs '{"amount": 15000}'Policy list output:
$ zakardo policy list
Policies: Name Status Rules Capabilities bulk-operations enabled 2 send_email_batch, delete_customers high-value-approval enabled 1 create_order (amount > 10000) destructive-gate enabled 1 * (effectClass: DESTRUCTIVE)9.2 zakardo policy test
Section titled “9.2 zakardo policy test”Test whether a policy would trigger for a given capability invocation:
$ zakardo policy test high-value-approval \ --capability create_order \ --inputs '{"amount": 15000}'
Policy: high-value-approvalCapability: create_orderInputs: { amount: 15000 }
Result: GATE Reason: Order amount ($15,000) exceeds high-value threshold ($10,000) Gate type: approval Approver roles: ["manager", "admin"]10. Code Generators
Section titled “10. Code Generators”10.1 Scaffold Commands
Section titled “10.1 Scaffold Commands”The CLI provides generators for all Zakardo artifact types:
| Command | Creates | Location |
|---|---|---|
zakardo capability:new <domain>/<name> | Capability scaffold | packages/capabilities/src/<domain>/<name>.ts |
zakardo route:new <path> | Foundation route scaffold | apps/api/src/foundation/<path>.ts |
zakardo policy:new <name> | Policy JSON scaffold | policies/<name>.json |
zakardo plan:new <name> | Plan IR scaffold | plans/<name>.json |
zakardo service:new <name> | Service provider scaffold | packages/core/src/services/<name>.ts + config update |
zakardo component:new <name> | A2UI component scaffold | packages/catalog/src/components/<name>.ts |
10.2 Capability Generator
Section titled “10.2 Capability Generator”$ zakardo capability:new customers/upgrade_plan
Created: packages/capabilities/src/customers/upgrade_plan.ts packages/capabilities/src/customers/upgrade_plan.test.ts
Updated: packages/capabilities/src/customers/index.ts (added export)Generated scaffold:
import { defineCapability } from '@zakardo/core';import { z } from 'zod';
export default defineCapability({ name: 'upgrade_plan', version: '1.0.0', description: 'TODO: Describe what this capability does',
effectClass: 'WRITE_INTERNAL', boundary: 'LOCAL', tags: ['customers'],
inputSchema: z.object({ // TODO: Define input schema }),
outputSchema: z.object({ // TODO: Define output schema }),
execute: async (input, context) => { // TODO: Implement capability logic throw new Error('Not implemented'); },});10.3 Generator Options
Section titled “10.3 Generator Options”All generators support common options:
zakardo capability:new customers/upgrade_plan --effect WRITE_EXTERNALzakardo capability:new customers/upgrade_plan --with-interactionzakardo capability:new customers/upgrade_plan --with-anchored-viewzakardo policy:new high-value --from-template approval-gatezakardo plan:new onboard-customer --steps 3Each generator:
- Creates the file with a working scaffold (imports, types, stub implementation).
- Updates the relevant index file to export the new artifact.
- Runs the TypeScript compiler to verify no errors.
11. Worker Command
Section titled “11. Worker Command”11.1 zakardo worker
Section titled “11.1 zakardo worker”Starts the execution worker process for worker dispatch mode (see Execution Engine Specification §4.7):
# Start the workerzakardo worker
# Start with custom concurrencyzakardo worker --concurrency 10
# Start with specific queuezakardo worker --queue execution:advanceOutput:
$ zakardo worker
Starting Zakardo Worker... ✓ Connected to Redis (localhost:6379) ✓ 14 capabilities loaded ✓ Queue: execution:advance ✓ Concurrency: 5
Worker ready. Waiting for jobs...The worker process:
- Connects to Redis (reads config from
config/execution.ts). - Loads all capabilities and configuration (same as the API process).
- Consumes jobs from the BullMQ queue.
- Executes
advanceExecution()for each job. - Publishes events via
RedisEventChannel.
Worker is only needed in worker dispatch mode. In in-process mode, execution runs on the API event loop and no worker is required.
12. Studio Integration
Section titled “12. Studio Integration”12.1 zakardo studio
Section titled “12.1 zakardo studio”Opens Zakardo Studio in the default browser. Studio is automatically mounted during zakardo dev, but this command can be used standalone:
# Open Studio (expects backend running)zakardo studio
# Open Studio at custom URLzakardo studio --url http://localhost:4000/zakardo/studio12.2 Studio Features (CLI Perspective)
Section titled “12.2 Studio Features (CLI Perspective)”Studio provides a GUI for many CLI commands. The CLI and Studio are complementary — not exclusive:
| Task | CLI | Studio |
|---|---|---|
| View capabilities | zakardo validate capabilities | Capability Browser |
| Test an intent | SDK or curl | Intent Playground |
| Run a plan (simulated) | zakardo training run | Plan Tester |
| Inspect a trace | zakardo trace inspect | Trace Viewer |
| View policies | zakardo policy list | Policy Inspector |
| Run training | zakardo training run | Training Dashboard |
| View config | cat config/* | Config Viewer |
| Preview A2UI | Frontend testing | A2UI Preview |
13. CI/CD Integration
Section titled “13. CI/CD Integration”13.1 CI Pipeline
Section titled “13.1 CI Pipeline”Recommended CI workflow:
name: CIon: [push, pull_request]
jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - uses: actions/setup-node@v4 with: { node-version: 20 } - run: pnpm install --frozen-lockfile - run: pnpm exec zakardo validate --json - run: pnpm exec zakardo build - run: pnpm exec zakardo training run --json13.2 JSON Output
Section titled “13.2 JSON Output”Every command supports --json for machine-readable output:
$ zakardo validate --json
{ "status": "pass", "categories": { "capabilities": { "checked": 14, "errors": 0, "warnings": 0 }, "policies": { "checked": 3, "errors": 0, "warnings": 0 }, "plans": { "checked": 2, "errors": 0, "warnings": 0 }, "training": { "checked": 5, "errors": 0, "warnings": 0 }, "config": { "checked": 1, "errors": 0, "warnings": 0 } }, "total_errors": 0, "total_warnings": 0}13.3 Environment Detection
Section titled “13.3 Environment Detection”The CLI automatically adjusts behavior when running in CI:
- No interactive prompts. All prompts auto-accept defaults (same as
--yes). - No color output when stdout is not a TTY (unless
--coloris specified). - Exit codes are strict — warnings in CI produce exit code 2 (configurable via
--strict).
14. Configuration Reference
Section titled “14. Configuration Reference”14.1 config/zakardo.ts
Section titled “14.1 config/zakardo.ts”The composed configuration file that merges all individual configs:
import { defineZakardoConfig } from '@zakardo/core';import { data } from './data';import { auth } from './auth';import { execution } from './execution';import { trace } from './trace';import { services } from './services';
export default defineZakardoConfig({ data, auth, execution, trace, services,
planner: { provider: 'openai', model: 'gpt-4o', temperature: 0.1, maxRetries: 3, },
studio: { enabled: process.env.NODE_ENV !== 'production', },});14.2 Config Validation
Section titled “14.2 Config Validation”The CLI validates config at startup and on every config change:
| Validation | When | Severity |
|---|---|---|
All define*Config calls produce valid objects | Startup | Error |
| Data adapter connects successfully | zakardo dev, zakardo validate | Error |
| LLM providers are reachable | zakardo validate | Warning |
| Auth provider initializes | zakardo validate | Warning |
| Execution dispatch mode matches infrastructure | zakardo validate | Warning |
15. Error Messages and Diagnostics
Section titled “15. Error Messages and Diagnostics”15.1 Error Philosophy
Section titled “15.1 Error Philosophy”CLI errors are designed to be:
- Descriptive. State what went wrong.
- Actionable. Tell the user what to do about it.
- Contextual. Include file paths, line numbers, and relevant values.
Example:
$ zakardo validate
✗ Capability "list_customers" (packages/capabilities/src/customers/list_customers.ts) Error: Input schema references non-existent type "CustomerFilter" Fix: Define CustomerFilter in packages/shared/src/types.ts or update the schema
✗ Policy "high-value-approval" (policies/high-value-approval.json) Error: References capability "create_invoice" which is not registered Registered capabilities: create_customer, list_customers, send_email, ...
✗ Plan "onboard-customer" (plans/onboard-customer.json) Error: Step 2 data binding "$steps[1].output.invoice_id" — step 1 output schema does not contain "invoice_id" Step 1 output schema: { id: string, name: string, email: string }
Validation failed: 3 errors, 0 warnings15.2 Common Error Codes
Section titled “15.2 Common Error Codes”| Code | Meaning |
|---|---|
ZAKARDO_E001 | Missing environment variable |
ZAKARDO_E002 | Config composition failure |
ZAKARDO_E003 | Data adapter connection failure |
ZAKARDO_E004 | Capability schema validation failure |
ZAKARDO_E005 | Policy syntax error |
ZAKARDO_E006 | Plan IR validation failure |
ZAKARDO_E007 | Unresolved capability reference |
ZAKARDO_E008 | Invalid data binding |
ZAKARDO_E009 | Training dataset format error |
ZAKARDO_E010 | Migration pending |
16. Summary of Decisions
Section titled “16. Summary of Decisions”| Decision | Resolution |
|---|---|
| Single CLI binary | One zakardo binary for all operations. No separate tools for migration, validation, or training. |
| Adapter delegation for migrations | zakardo migrate delegates to Prisma Migrate or Drizzle Kit. CLI never generates SQL itself. |
| Convention-based discovery | Capabilities from packages/capabilities/, policies from policies/, plans from plans/, training from training/. No manual registration. |
| Validate-before-build | zakardo build runs full validation before building. Catches errors at dev time, not runtime. |
| JSON output for CI | Every command supports --json for scriptable pipelines. Exit codes are well-defined. |
| create-zakardo is standalone | Project scaffolding is a separate npx package, not a subcommand of the CLI. Avoids chicken-and-egg dependency. |
| Studio is development-only | Not included in production builds. Mounted alongside the dev server. |
| Worker as CLI command | zakardo worker starts the execution worker. Same binary, same config. No separate installation. |
| Generators update index files | Scaffolding is not just file creation — generators also wire up exports and verify TypeScript compilation. |
17. Questions Deferred
Section titled “17. Questions Deferred”| Question | Deferred To |
|---|---|
| What is the exact A2UI component scaffold template? | Frontend Architecture Specification |
| How does Studio authenticate in development? | Security Specification |
| What is the deployment pipeline for Zakardo Cloud managed instances? | PRD — Zakardo Cloud |
| How does the CLI handle monorepo vs. single-package projects? | Future planning (v2 scope) |
| What is the plugin system for custom CLI commands? | Registry and Marketplace Specification |