> ## 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
> Drive Roark from your terminal and your CI pipeline
### Overview
`roark` is the official command line interface for the Roark API. It covers the same surface as the [Node.js](/documentation/sdks/node-sdk) and [Python](/documentation/sdks/python-sdk) SDKs — calls, metrics, personas, customer flows, simulations, webhooks — and adds the two commands that make [Config as Code](/documentation/config-as-code/overview) practical: `roark config diff` and `roark config apply`.
It prints JSON, so it composes with `jq` and with everything else in a pipeline, and it uses distinct [exit codes](#exit-codes), so a CI job can tell a rejected request apart from a missing credential.
***
### Install
**macOS, Linux, WSL:**
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -fsSL https://roark.ai/install.sh | sh
```
This installs into `~/.roark` and links `roark` into `~/.local/bin`. Nothing is written outside your home directory, and no step needs `sudo`.
Pin a version, or remove the CLI entirely:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -fsSL https://roark.ai/install.sh | sh -s -- --version 0.1.1
curl -fsSL https://roark.ai/install.sh | sh -s -- --uninstall
```
Re-run the install command to upgrade. It replaces the installed version in place and prunes the old one.
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
brew tap roarkhq/tap
brew trust roarkhq/tap
brew install roark
```
The `brew trust` step is not optional. Homebrew refuses to load a formula from a third-party tap until it is trusted, and without it `brew install` stops with `Refusing to load formula roarkhq/tap/roark from untrusted tap`. To trust just this formula rather than the whole tap, use `brew trust --formula roarkhq/tap/roark`.
In a `Brewfile`:
```ruby theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
tap "roarkhq/tap"
brew "roark"
```
Homebrew installs do not auto-update. Run `brew upgrade roark` to move to the latest version.
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npm install -g @roarkanalytics/cli
```
Or run it without installing anything, which is often what you want in CI:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
npx -y @roarkanalytics/cli@latest --help
```
A global npm install writes into npm's configured prefix, which on many systems is root-owned and fails with `EACCES`. If you hit that, use the install script instead of reaching for `sudo`.
Confirm the install worked:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark --version
```
The CLI needs **Node.js 20 or newer**. Every install method above uses your existing Node; none of them bundle a runtime.
If `~/.local/bin` is not on your `PATH`, the install script tells you the line to add. Man pages ship with the CLI — add `~/.roark/share/man` to `MANPATH` and `man roark` works.
***
### Authenticate
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark auth login # prompts for a token, stores it with mode 0600
roark auth status # shows which credential is in effect, and where it came from
roark auth logout # deletes the stored credential
```
Generate the token from [API Keys](/documentation/getting-started/api-keys). In CI, set the same environment variable the SDKs read instead of logging in:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
export ROARK_API_BEARER_TOKEN="your-api-key"
```
Settings resolve highest precedence first: a flag, then the environment variable, then a project `.roark.json` found by walking up from the working directory, then the user config file. `roark config path` prints where each of those lives.
A `.roark.json` arrives with a clone rather than being something you wrote, so if a project file sets `baseURL`, the CLI refuses to send a stored or environment credential to it. Read the file, then pass `--allow-project-base-url` (or set `ROARK_ALLOW_PROJECT_BASE_URL`) to opt in — or pass `--token` to send a different credential.
***
### Usage
Commands read noun before verb, and the verb is `list`, `get`, `create`, `update` or `delete` unless the operation is genuinely something else:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark call list --limit 5
roark call get
roark simulation plan job start
```
`roark --help` prints the flags for any command, and `roark --help` lists the command tree.
#### Output
JSON on stdout — indented and coloured for a terminal, compact when piped — so the same command works in both places. Errors go to stderr, so `> out.json` captures only real output.
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark call list --limit 5 | jq '.data[].id'
roark call get --format plain
```
#### Request bodies
Flags cover the common case, and nested objects go one level deep with dots. A whole payload can be supplied as JSON, with flags overriding what it contains:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark webhook create --url https://example.com/hook --events CALL_ANALYSIS_COMPLETED
roark customer-flow create --data @flow.json
cat flow.json | roark customer-flow create
```
#### Any endpoint
Endpoints without a generated command are still reachable:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark api get /v1/call --query limit=5
roark api post /v1/webhook --data '{"url":"https://example.com","events":["CALL_ANALYSIS_COMPLETED"]}'
```
#### Shell completion
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
eval "$(roark completion bash)"
eval "$(roark completion zsh)"
roark completion fish | source
```
***
### Config as Code
The CLI is the intended way to run [Config as Code](/documentation/config-as-code/overview). Point it at a directory of YAML resources — it bundles them, resolves any `file://` prompt references, and submits the result:
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark config diff ./roark
```
Prints the `create`, `update` and `delete` operations that would run. Nothing is written.
```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark config apply ./roark
```
Shows the same preview, then asks for confirmation before reconciling. Pass `-y` to skip the prompt in CI, and `--no-prune` for an additive-only apply that leaves removed resources alone.
These commands need an API key carrying the **`config:apply`** permission. See [Config as Code](/documentation/config-as-code/overview) for the resource kinds and apply semantics.
***
### Exit codes
Distinct codes so a CI job can branch on the failure rather than grepping stderr.
| Code | Meaning |
| :--- | :--------------------------------------------------------- |
| 0 | Success |
| 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 |
***
### Additional Resources
View package details on npm
Formula source and release notes
Define agents, personas, flows and metrics as YAML
Explore the full API documentation