# CLI

OrchaJS CLI reference for init, playground, run, test, and production builds.

Source: https://orcha.sh/docs/cli
Markdown: https://orcha.sh/docs/cli.mdx

Run commands through `npx orcha` or package scripts.

## `orcha init`

```bash
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 dev`

```bash
npx orcha dev
```

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

## `orcha playground`

```bash
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 run`

Start a session:

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

Use structured or multimodal input from a file:

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

Continue a session:

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

Submit client-action results:

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

`tool-results.json`:

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

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

## `orcha test`

```bash
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 build`

```bash
npx orcha build
```

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

## Suggested scripts

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