Skip to main content

​
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

macOS, Linux, WSL:
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:
Re-run the install command to upgrade. It replaces the installed version in place and prunes the old one.
Confirm the install worked:
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

Generate the token from API Keys. In CI, set the same environment variable the SDKs read instead of logging in:
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:
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.

​
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:

​
Any endpoint

Endpoints without a generated command are still reachable:

​
Shell completion

​
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:
1

Preview the changes

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

Apply

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.

​
Exit codes

Distinct codes so a CI job can branch on the failure rather than grepping stderr.

​
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