> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Every roark command, generated from the same spec as the API

`roark` calls the Roark Analytics API from the command line. Commands read noun before verb, so the resource is what you type first and the verb is one of list, get, create, update or delete unless the operation is genuinely something else.

```bash Usage theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark <resource> [<sub-resource>...] <verb> [arguments] [options]
```

Installing the CLI, storing a credential and using it in CI are covered in the
[CLI guide](/documentation/sdks/cli.md). This tab is the per-command reference.

## Global options

Every command accepts these in addition to its own options.

**--base-url** `url`

API base URL.

**--token** `token`

Bearer token. Prefer `ROARK_API_BEARER_TOKEN` or the stored credential.

**--timeout** `ms`

Request timeout in milliseconds.

**--max-retries** `count`

Retries for retryable failures.

**--format** `format`

Output format: auto, json, jsonl, plain.

**--json** `switch`

Shorthand for `--format` json.

**--no-color** `switch`

Disable colour.

**-q, --quiet** `switch`

Suppress non-essential output.

**--allow-project-base-url** `switch`

Send the stored credential to a base URL set by a project `.roark.json`. Refused by default.

### Sending a body

Commands that send a request body accept these as well.

**--data** `json`

Request body as JSON, or @file to read one (@- for stdin).

**-y, --yes** `switch`

Skip confirmation prompts.

**--no-input** `switch`

Never prompt; fail instead.

## Configuration

Settings are resolved highest precedence first: command line flag, environment variable, project `.roark.json` found by walking up from the working directory, then the user config file. The stored credential is written with mode 0600.

## Environment

| Variable | Description |
| - | - |
| `ROARK_API_BEARER_TOKEN` | Bearer token used when `--token` is not given. |
| `ROARK_BASE_URL` | API base URL. |
| `XDG_CONFIG_HOME` | Overrides the location of the user config file. |
| `ROARK_ALLOW_PROJECT_BASE_URL` | Trusts a base URL set by a project `.roark.json`, like `--allow-project-base-url`. |
| `NO_COLOR` | Disables colour when set to any value. |

## Exit codes

Distinct per failure mode, so a CI job can tell a rejected request from a missing credential without reading stderr.

| Code | Meaning |
| - | - |
| `0` | The command succeeded. |
| `1` | The API rejected the request. |
| `2` | The command line was wrong. |
| `3` | No credential, or the credential was refused. |
| `4` | The addressed resource does not exist. |
| `5` | The request never completed: connection, timeout, or abort. |

## Commands

`roark <command> --help` prints the same options any of these pages lists.

### `agent`

| Command | Description |
| - | - |
| [`roark agent build`](/cli-reference/commands/agent-build) | Build a Roark-hosted agent |
| [`roark agent create`](/cli-reference/commands/agent-create) | Create a new agent |
| [`roark agent endpoint create`](/cli-reference/commands/agent-endpoint-create) | Create a new agent endpoint |
| [`roark agent endpoint get`](/cli-reference/commands/agent-endpoint-get) | Get agent endpoint by ID |
| [`roark agent endpoint list`](/cli-reference/commands/agent-endpoint-list) | List agent endpoints |
| [`roark agent endpoint update`](/cli-reference/commands/agent-endpoint-update) | Update an agent endpoint |
| [`roark agent get`](/cli-reference/commands/agent-get) | Get agent by ID |
| [`roark agent list`](/cli-reference/commands/agent-list) | List agents |
| [`roark agent prompt list`](/cli-reference/commands/agent-prompt-list) | List an agent's prompts |
| [`roark agent prompt update`](/cli-reference/commands/agent-prompt-update) | Set an agent's prompt |
| [`roark agent prompt version list`](/cli-reference/commands/agent-prompt-version-list) | List a prompt's versions |
| [`roark agent update`](/cli-reference/commands/agent-update) | Update an agent |

### `agent-config`

| Command | Description |
| - | - |
| [`roark agent-config get`](/cli-reference/commands/agent-config-get) | Get a managed config |
| [`roark agent-config list`](/cli-reference/commands/agent-config-list) | List managed configs |
| [`roark agent-config promote`](/cli-reference/commands/agent-config-promote) | Promote staging to production |
| [`roark agent-config resolve`](/cli-reference/commands/agent-config-resolve) | Resolve config for a session |
| [`roark agent-config staging delete`](/cli-reference/commands/agent-config-staging-delete) | Discard the staging revision |
| [`roark agent-config update`](/cli-reference/commands/agent-config-update) | Write a config revision |

### `analytics`

| Command | Description |
| - | - |
| [`roark analytics query`](/cli-reference/commands/analytics-query) | Run an analytics query |
| [`roark analytics schema get`](/cli-reference/commands/analytics-schema-get) | Get the analytics schema |

### `autoimprove`

| Command | Description |
| - | - |
| [`roark autoimprove job answer`](/cli-reference/commands/autoimprove-job-answer) | Answer Roark's question |
| [`roark autoimprove job cancel`](/cli-reference/commands/autoimprove-job-cancel) | Cancel a job |
| [`roark autoimprove job create`](/cli-reference/commands/autoimprove-job-create) | Start an Autoimprove job |
| [`roark autoimprove job dismiss`](/cli-reference/commands/autoimprove-job-dismiss) | Dismiss a verified job |
| [`roark autoimprove job get`](/cli-reference/commands/autoimprove-job-get) | Get an Autoimprove job |
| [`roark autoimprove job guidance send`](/cli-reference/commands/autoimprove-job-guidance-send) | Send guidance to a running job |
| [`roark autoimprove job list`](/cli-reference/commands/autoimprove-job-list) | List Autoimprove jobs |
| [`roark autoimprove job promote`](/cli-reference/commands/autoimprove-job-promote) | Promote a verified job to production |

### `benchmark`

| Command | Description |
| - | - |
| [`roark benchmark leaderboard get`](/cli-reference/commands/benchmark-leaderboard-get) | Get the benchmark leaderboard |
| [`roark benchmark metric list`](/cli-reference/commands/benchmark-metric-list) | List benchmark metrics |
| [`roark benchmark suite list`](/cli-reference/commands/benchmark-suite-list) | List benchmark suites |
| [`roark benchmark target get`](/cli-reference/commands/benchmark-target-get) | Get a benchmark target |
| [`roark benchmark target history list`](/cli-reference/commands/benchmark-target-history-list) | List a target’s published generations |
| [`roark benchmark target score-sample list`](/cli-reference/commands/benchmark-target-score-sample-list) | List score samples for a target |

### `call`

| Command | Description |
| - | - |
| [`roark call batch delete`](/cli-reference/commands/call-batch-delete) | Delete calls in batch |
| [`roark call cost get`](/cli-reference/commands/call-cost-get) | Get call cost |
| [`roark call create`](/cli-reference/commands/call-create) | Create a call |
| [`roark call delete`](/cli-reference/commands/call-delete) | Delete a call |
| [`roark call get`](/cli-reference/commands/call-get) | Get a call by ID |
| [`roark call list`](/cli-reference/commands/call-list) | List calls |
| [`roark call metric list`](/cli-reference/commands/call-metric-list) | List call metrics |
| [`roark call property update`](/cli-reference/commands/call-property-update) | Update the properties of a call |
| [`roark call sentiment-run list`](/cli-reference/commands/call-sentiment-run-list) | List call sentiment runs |
| [`roark call tool-invocation append`](/cli-reference/commands/call-tool-invocation-append) | Append tool invocations to a call |
| [`roark call transcript get`](/cli-reference/commands/call-transcript-get) | Get call transcript |

### `config`

| Command | Description |
| - | - |
| [`roark config apply`](/cli-reference/commands/config-apply) | Reconcile the project to a config directory (or bundle). Previews and confirms first. |
| [`roark config diff`](/cli-reference/commands/config-diff) | Preview the changes a config directory (or bundle) would make. No writes. |

### `credential`

| Command | Description |
| - | - |
| [`roark credential create`](/cli-reference/commands/credential-create) | Create a personal credential |
| [`roark credential list`](/cli-reference/commands/credential-list) | List your personal credentials |
| [`roark credential revoke`](/cli-reference/commands/credential-revoke) | Revoke one of your personal credentials |

### `customer-flow`

| Command | Description |
| - | - |
| [`roark customer-flow create`](/cli-reference/commands/customer-flow-create) | Create a customer flow |
| [`roark customer-flow delete`](/cli-reference/commands/customer-flow-delete) | Delete a customer flow |
| [`roark customer-flow duplicate`](/cli-reference/commands/customer-flow-duplicate) | Duplicate a customer flow |
| [`roark customer-flow edge-case create`](/cli-reference/commands/customer-flow-edge-case-create) | Add an edge case |
| [`roark customer-flow edge-case delete`](/cli-reference/commands/customer-flow-edge-case-delete) | Remove an edge case |
| [`roark customer-flow edge-case promote`](/cli-reference/commands/customer-flow-edge-case-promote) | Promote an edge case to the happy path |
| [`roark customer-flow edge-case update`](/cli-reference/commands/customer-flow-edge-case-update) | Update an edge case |
| [`roark customer-flow get`](/cli-reference/commands/customer-flow-get) | Get customer flow by ID |
| [`roark customer-flow graph replace`](/cli-reference/commands/customer-flow-graph-replace) | Replace a scripted flow's steps |
| [`roark customer-flow happy-path update`](/cli-reference/commands/customer-flow-happy-path-update) | Update a flow's happy path |
| [`roark customer-flow list`](/cli-reference/commands/customer-flow-list) | List customer flows |
| [`roark customer-flow update`](/cli-reference/commands/customer-flow-update) | Update a customer flow |

### `dashboard`

| Command | Description |
| - | - |
| [`roark dashboard create`](/cli-reference/commands/dashboard-create) | Create a dashboard |
| [`roark dashboard data get`](/cli-reference/commands/dashboard-data-get) | Get dashboard data |
| [`roark dashboard delete`](/cli-reference/commands/dashboard-delete) | Delete a dashboard |
| [`roark dashboard get`](/cli-reference/commands/dashboard-get) | Get a dashboard |
| [`roark dashboard list`](/cli-reference/commands/dashboard-list) | List dashboards |
| [`roark dashboard update`](/cli-reference/commands/dashboard-update) | Update a dashboard |
| [`roark dashboard widget create`](/cli-reference/commands/dashboard-widget-create) | Add a widget |
| [`roark dashboard widget delete`](/cli-reference/commands/dashboard-widget-delete) | Remove a widget |
| [`roark dashboard widget update`](/cli-reference/commands/dashboard-widget-update) | Replace a widget |
| [`roark dashboard widget-data get`](/cli-reference/commands/dashboard-widget-data-get) | Get widget data |

### `health`

| Command | Description |
| - | - |
| [`roark health`](/cli-reference/commands/health) | Get API health status |

### `http-request-definition`

| Command | Description |
| - | - |
| [`roark http-request-definition create`](/cli-reference/commands/http-request-definition-create) | Create HTTP request definition |
| [`roark http-request-definition get`](/cli-reference/commands/http-request-definition-get) | Get HTTP request definition by ID |
| [`roark http-request-definition list`](/cli-reference/commands/http-request-definition-list) | List HTTP request definitions |
| [`roark http-request-definition update`](/cli-reference/commands/http-request-definition-update) | Update HTTP request definition |

### `metric`

| Command | Description |
| - | - |
| [`roark metric collection-job cancel`](/cli-reference/commands/metric-collection-job-cancel) | Cancel a metric collection job |
| [`roark metric collection-job create`](/cli-reference/commands/metric-collection-job-create) | Create and run a metric collection job |
| [`roark metric collection-job get`](/cli-reference/commands/metric-collection-job-get) | Get metric collection job by ID |
| [`roark metric collection-job list`](/cli-reference/commands/metric-collection-job-list) | List metric collection jobs |
| [`roark metric definition create`](/cli-reference/commands/metric-definition-create) | Create custom metric definition |
| [`roark metric definition list`](/cli-reference/commands/metric-definition-list) | List metric definitions |
| [`roark metric definition update`](/cli-reference/commands/metric-definition-update) | Update a metric definition |
| [`roark metric policy create`](/cli-reference/commands/metric-policy-create) | Create a metric policy |
| [`roark metric policy delete`](/cli-reference/commands/metric-policy-delete) | Delete a metric policy |
| [`roark metric policy get`](/cli-reference/commands/metric-policy-get) | Get metric policy by ID |
| [`roark metric policy list`](/cli-reference/commands/metric-policy-list) | List metric policies |
| [`roark metric policy update`](/cli-reference/commands/metric-policy-update) | Update a metric policy |
| [`roark metric variant create`](/cli-reference/commands/metric-variant-create) | Create a metric variant |
| [`roark metric variant delete`](/cli-reference/commands/metric-variant-delete) | Delete a metric variant |
| [`roark metric variant get`](/cli-reference/commands/metric-variant-get) | Get a metric variant |
| [`roark metric variant list`](/cli-reference/commands/metric-variant-list) | List a metric’s variants |
| [`roark metric variant update`](/cli-reference/commands/metric-variant-update) | Update a metric variant |

### `project`

| Command | Description |
| - | - |
| [`roark project list`](/cli-reference/commands/project-list) | List projects available to this credential |

### `simulation`

| Command | Description |
| - | - |
| [`roark simulation environment create`](/cli-reference/commands/simulation-environment-create) | Create an environment |
| [`roark simulation environment delete`](/cli-reference/commands/simulation-environment-delete) | Delete an environment |
| [`roark simulation environment get`](/cli-reference/commands/simulation-environment-get) | Get environment by ID |
| [`roark simulation environment list`](/cli-reference/commands/simulation-environment-list) | List environments |
| [`roark simulation environment update`](/cli-reference/commands/simulation-environment-update) | Update an environment |
| [`roark simulation group create`](/cli-reference/commands/simulation-group-create) | Create a simulation group |
| [`roark simulation group delete`](/cli-reference/commands/simulation-group-delete) | Delete a simulation group |
| [`roark simulation group get`](/cli-reference/commands/simulation-group-get) | Get a simulation group |
| [`roark simulation group list`](/cli-reference/commands/simulation-group-list) | List simulation groups |
| [`roark simulation group run`](/cli-reference/commands/simulation-group-run) | Run a simulation group |
| [`roark simulation group update`](/cli-reference/commands/simulation-group-update) | Update a simulation group |
| [`roark simulation job get`](/cli-reference/commands/simulation-job-get) | Get simulation by ID |
| [`roark simulation job lookup`](/cli-reference/commands/simulation-job-lookup) | Lookup by phone number |
| [`roark simulation job tool-mock list`](/cli-reference/commands/simulation-job-tool-mock-list) | List mocked tool invocations |
| [`roark simulation persona create`](/cli-reference/commands/simulation-persona-create) | Create a new persona |
| [`roark simulation persona get`](/cli-reference/commands/simulation-persona-get) | Get persona by ID |
| [`roark simulation persona list`](/cli-reference/commands/simulation-persona-list) | List personas |
| [`roark simulation persona update`](/cli-reference/commands/simulation-persona-update) | Update a persona |
| [`roark simulation plan create`](/cli-reference/commands/simulation-plan-create) | Create a run plan |
| [`roark simulation plan delete`](/cli-reference/commands/simulation-plan-delete) | Delete a run plan |
| [`roark simulation plan get`](/cli-reference/commands/simulation-plan-get) | Get run plan by ID |
| [`roark simulation plan job cancel`](/cli-reference/commands/simulation-plan-job-cancel) | Cancel a simulation plan job |
| [`roark simulation plan job cost get`](/cli-reference/commands/simulation-plan-job-cost-get) | Get simulation run cost |
| [`roark simulation plan job debrief create`](/cli-reference/commands/simulation-plan-job-debrief-create) | Generate simulation run debrief |
| [`roark simulation plan job get`](/cli-reference/commands/simulation-plan-job-get) | Get simulation plan job |
| [`roark simulation plan job list`](/cli-reference/commands/simulation-plan-job-list) | List simulation plan jobs |
| [`roark simulation plan job result get`](/cli-reference/commands/simulation-plan-job-result-get) | Get simulation run results |
| [`roark simulation plan job start`](/cli-reference/commands/simulation-plan-job-start) | Run a simulation plan |
| [`roark simulation plan list`](/cli-reference/commands/simulation-plan-list) | List run plans |
| [`roark simulation plan update`](/cli-reference/commands/simulation-plan-update) | Update a run plan |
| [`roark simulation run`](/cli-reference/commands/simulation-run) | Run a simulation |
| [`roark simulation run-group create`](/cli-reference/commands/simulation-run-group-create) | Create a run group |
| [`roark simulation run-group delete`](/cli-reference/commands/simulation-run-group-delete) | Delete a run group |
| [`roark simulation run-group get`](/cli-reference/commands/simulation-run-group-get) | Get a run group |
| [`roark simulation run-group list`](/cli-reference/commands/simulation-run-group-list) | List run groups |
| [`roark simulation run-group report regenerate`](/cli-reference/commands/simulation-run-group-report-regenerate) | Regenerate a run group report |
| [`roark simulation template list`](/cli-reference/commands/simulation-template-list) | List simulation templates |
| [`roark simulation tool mock`](/cli-reference/commands/simulation-tool-mock) | Mock a tool call during a test call |
| [`roark simulation tool-fixture create`](/cli-reference/commands/simulation-tool-fixture-create) | Set a tool fixture |
| [`roark simulation tool-fixture delete`](/cli-reference/commands/simulation-tool-fixture-delete) | Delete a tool fixture |
| [`roark simulation tool-fixture list`](/cli-reference/commands/simulation-tool-fixture-list) | List tool fixtures |
| [`roark simulation tool-fixture update`](/cli-reference/commands/simulation-tool-fixture-update) | Update a tool fixture |

### `usage`

| Command | Description |
| - | - |
| [`roark usage get`](/cli-reference/commands/usage-get) | Get usage & cost |

### `webhook`

| Command | Description |
| - | - |
| [`roark webhook create`](/cli-reference/commands/webhook-create) | Create webhook |
| [`roark webhook delete`](/cli-reference/commands/webhook-delete) | Delete webhook |
| [`roark webhook get`](/cli-reference/commands/webhook-get) | Get webhook by ID |
| [`roark webhook list`](/cli-reference/commands/webhook-list) | List webhooks |

### `whoami`

| Command | Description |
| - | - |
| [`roark whoami`](/cli-reference/commands/whoami) | Describe the current credential |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.