CLI

Overview

roark is the official command line interface for the Roark API. It covers the same surface as the Node.js and Python SDKs (calls, metrics, personas, customer flows, simulations, webhooks) and adds the two commands that make Config as Code 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, so a CI job can tell a rejected request apart from a missing credential.

Install

Install script (recommended)
Homebrew
npm

macOS, Linux, WSL:

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:

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.

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:

tap "roarkhq/tap"
brew "roark"

Homebrew installs do not auto-update. Run brew upgrade roark to move to the latest version.

npm install -g @roarkanalytics/cli

Or run it without installing anything, which is often what you want in CI:

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:

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

Interactively, roark auth login opens your browser to approve access, then stores the credential it mints (mode 0600), with the permissions you approve:

roark auth login          # opens the browser to approve, stores the minted credential
roark auth login --paste  # skip the browser: paste or pipe a token instead
roark auth status         # what credential is in effect, where it came from, and whether it still works
roark auth logout         # deletes the stored credential
roark whoami              # asks the API what the credential is and what it can reach

auth status asks the API rather than reading the file, so a credential revoked in the browser is reported as rejected here too, and exits 3:

$ roark auth status
Authenticated as you@example.com via ~/.config/roark/config.json (roar...2644)
Acting on project 0b2b1f9e-5f1a-4c7e-9c3d-1f2e3a4b5c6d, the default stored on this credential.
Override it with `roark config set project <id>`.

What the browser mints depends on your organization: a key bound to the project you pick, or a credential scoped to you across the organization, which reaches every project you are a member of and names one per request. Either way roark whoami tells you which you are holding (tokenScope), and both are revocable in the dashboard: project keys under Settings → API keys, user credentials under Settings → Account → Connected apps. See API Keys for the difference. In CI there is no browser, so authenticate with a token instead. Use a project key here rather than a user credential: a project key belongs to the project and keeps working when people join and leave, while a user credential is tied to a person and is revoked when their account is deactivated. Generate one from API Keys and set the environment variable the CLI and SDKs both read, no login step needed:

export ROARK_API_BEARER_TOKEN="your-api-key"

You can also pass --token <value> on any command, or pipe a token into login (echo "$ROARK_API_BEARER_TOKEN" | roark auth login). See Using the CLI in CI for a full GitHub Actions example. 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.

Choosing a project

A project key names its own project and ignores everything in this section. A user credential reaches every project you are a member of, so each command acts on one:

roark project list                     # the projects this credential can reach
roark config set project <project-id>  # remember one for every later command
roark agent list --project <other-id>  # or name one for a single command

Resolution is the same precedence as every other setting, with one extra layer at the bottom:

--project <id> on the command
ROARK_PROJECT_ID in the environment
project in a .roark.json beside your code
project in the user config file (roark config set project)
the project you chose on the consent screen, stored on the credential itself

Step 5 is why a freshly pasted credential works with nothing configured: the API falls back to it when a request names no project. roark auth status prints which of these is in effect.

Unlike baseURL, a project in a checked-in .roark.json is safe and needs no opt-in. It selects which of your own projects a command acts on, and it cannot send your credential anywhere new. That is the distinction the warning above is drawing: one steers permissions you already have, the other steers where your secret goes.

If a command returns 403 That project is not available to this credential, the project is outside your credential’s organization or you are not an active member of it. roark project list shows the ones that are.

Usage

Commands read noun before verb, and the verb is list, get, create, update or delete unless the operation is genuinely something else:

roark call list --limit 5
roark call get <call-id>
roark simulation plan job start <plan-id>

roark <command> --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.

roark call list --limit 5 | jq '.data[].id'
roark call get <call-id> --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:

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:

roark api get /v1/call --query limit=5
roark api post /v1/webhook --data '{"url":"https://example.com","events":["CALL_ANALYSIS_COMPLETED"]}'

Shell completion

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. Point it at a directory of YAML resources. It bundles them, resolves any file:// prompt references, and submits the result:

Preview the changes

roark config diff ./roark

Prints the create, update and delete operations that would run. Nothing is written.

Apply

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 for the resource kinds and apply semantics.

Using the CLI in CI

CI runs headless, so skip auth login and authenticate with a token in the environment. Store an API key as a secret (ROARK_API_KEY) and export it as ROARK_API_BEARER_TOKEN; every command picks it up with no interactive step. The common setup is a two-stage GitHub Actions workflow: diff on every pull request so a reviewer sees what would change, and apply on merge to main.

GitHub Actions

name: roark-config
on:
  pull_request:
    paths: ['roark/**']
  push:
    branches: [main]
    paths: ['roark/**']

jobs:
  config:
    runs-on: ubuntu-latest
    env:
      # An API key with the config:apply permission, stored as a repo secret.
      ROARK_API_BEARER_TOKEN: ${{ secrets.ROARK_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      # Preview on PRs: no writes, and the log shows exactly what would change.
      - name: Diff
        if: github.event_name == 'pull_request'
        run: npx @roarkanalytics/cli config diff ./roark

      # Reconcile on merge. -y skips the confirmation prompt.
      - name: Apply
        if: github.ref == 'refs/heads/main'
        run: npx @roarkanalytics/cli config apply ./roark -y

config diff exits non-zero if the request is rejected (see exit codes below), so a broken bundle fails the PR check rather than slipping through. Use --no-prune on apply if you want additive-only syncs that never delete resources removed from the repo.

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

NPM Package

View package details on npm

Homebrew Tap

Formula source and release notes

Config as Code

Define agents, personas, flows and metrics as YAML

API Reference

Explore the full API documentation

Getting Started

Simulations

Observability

Metrics

Config as Code

Autoimprove

Recipes

Integrations

Enterprise

SDKs & Developer Tools

Resources

Overview

Install

Authenticate

Choosing a project

Usage

Output

Request bodies

Any endpoint

Shell completion

Config as Code

Using the CLI in CI

Exit codes

Additional Resources

NPM Package

Homebrew Tap

Config as Code

API Reference

​Overview

​Install

​Authenticate

​Choosing a project

​Usage

​Output

​Request bodies

​Any endpoint

​Shell completion

​Config as Code

​Using the CLI in CI

​Exit codes

​Additional Resources

NPM Package

Homebrew Tap

Config as Code

API Reference

Overview

Install

Authenticate

Choosing a project

Usage

Output

Request bodies

Any endpoint

Shell completion

Config as Code

Using the CLI in CI

Exit codes

Additional Resources