CLI

Run commands through npx orcha or package scripts.

orcha initCopy Anchor Link

npx orcha init

Adds a minimal orcha/ registry, an example agent, AGENTS.md, and the .orcha/ gitignore entry. Existing files are skipped, not overwritten.

orcha devCopy Anchor Link

npx orcha dev

Validates the registry and watches orcha/**. This is offline and does not call a model.

orcha playgroundCopy Anchor Link

npx orcha playground
npx orcha playground --host localhost --port 4310 --no-open

Starts the local development UI. Defaults to localhost:4310 and opens the browser.

orcha runCopy Anchor Link

Start a session:

npx orcha run orderSupport --input "Where is ord_1001?"

Use structured or multimodal input from a file:

npx orcha run orderSupport --input-file request.json

Continue a session:

npx orcha run orderSupport \
  --session ses_123 \
  --input "What should I do next?"

Submit client-action results:

npx orcha run orderSupport \
  --session ses_123 \
  --tool-results tool-results.json

tool-results.json:

[
  {
    "callId": "call_123",
    "output": {
      "approved": true,
      "note": "Approved by support lead"
    }
  }
]

Add --json for machine-readable { result, evaluations } output.

orcha testCopy Anchor Link

npx orcha test
npx orcha test orderSupport
npx orcha test orderSupport/delayedOrder
npx orcha test orderSupport/delayedOrder --json

Tests call real providers and may consume tokens. Unmocked local actions execute live.

orcha buildCopy Anchor Link

npx orcha build

Performs offline production compilation and writes .orcha/dist/bundle.js. It does not call a provider.

Suggested scriptsCopy Anchor Link

{
  "scripts": {
    "dev": "orcha playground",
    "build": "orcha build",
    "test": "orcha test",
    "orcha:dev": "orcha dev",
    "orcha:test": "orcha test"
  }
}