CLI reference
Drive an engagement from your terminal or your pipeline.
The CLI runs the same engine the console runs. It takes a target, runs the engagement in a sandbox, and writes the findings and their evidence to the run.
Install
bashcurl --proto '=https' --tlsv1.2 -fsSL https://rokkhe.com/install.sh | shThe installer needs curl, Python 3.12 or newer, and sha256sum or shasum. It downloads the rokkhe-agent wheel, checks it against a separately fetched SHA-256 list, refuses to install on a mismatch, and installs it with uv, pipx or pip --user, in that order. It never runs as root. Download it and read it first if you prefer: it is served at rokkhe.com/install.sh.
From a source checkout, cd engine && uv sync and then uv run rokkhe --help.
A container runtime (Docker or Podman) for the sandbox, and a model: set ROKKHE_LLM to a provider/model and LLM_API_KEY to its key. Platform commands such as rokkhe runs need neither.
Connect to a deployment
bashrokkhe login --host https://your.rokkhe
rokkhe whoami
rokkhe doctorrokkhe login uses the device authorization grant, so it works the same over SSH, in a container and on a laptop. It prints a link and a one-time code; approve the code on the deployment's /device page while signed in. The code expires after 15 minutes. Without --host it signs in to rokkhe.com.
| Command | What it does |
|---|---|
| rokkhe login | Signs this machine in. --no-browser only prints the link; --profile names the credential set, so one machine can hold several deployments. |
| rokkhe whoami | The host, account, scopes and credential store of the current profile. |
| rokkhe doctor | Read-only checks: Python runtime, credential store, platform session, platform reachability, model provider, container runtime and outbound TCP/443. Exits 1 only when a check fails; warnings do not fail it. |
| rokkhe logout | Revokes the server session, then forgets local credentials. --local-only forgets them without verified revocation. |
| rokkhe scan <target> | Queues a scan on the deployment instead of running one locally. |
| rokkhe runs, rokkhe findings list | Reads the deployment's runs and findings. |
Credentials are kept in the OS keychain when one is available and in an encrypted file otherwise; doctor says which. rokkhe auth is separate: it signs in to a model provider, not to a Rokkhe deployment.
Usage
bashrokkhe (--target <target> | --target-list <path> | --mount <path>) [options]One of the three target forms is required. Everything else is optional.
Targets
| Flag | Type | Meaning |
|---|---|---|
| --target, -t | string | URL, repository, local directory, domain, or IP. Repeatable. |
| --target-list | string | File of targets, one per line. Blank lines and # comments are ignored. Repeatable. |
| --mount | string | Bind-mount a local directory into the sandbox read-only instead of copying it in file by file. |
A local --target directory is copied into the sandbox one file at a time, which stalls on very large repositories. --mount attaches it instead. The mount is read-only to protect your source from accidental modification — treat that as a guardrail, not a security boundary.
Scope and instructions
| Flag | Type | Meaning |
|---|---|---|
| --instruction | string | Custom instructions: credentials, focus areas, or a specific approach. |
| --instruction-file | string | Path to a file containing the same, for anything longer than a shell argument. |
| --diff-base | string | Branch or commit to compare against, for example origin/main. Scopes the engagement to what changed. |
Running it
| Flag | Type | Meaning |
|---|---|---|
| --non-interactive, -n | boolean | Headless, no TUI. This is the CI form. |
| --config | string | Custom JSON config instead of ~/.rokkhe/cli-config.json. |
| --max-budget-usd | number | Ceiling on LLM spend for the whole scan, counted cumulatively across the run. |
An engagement’s cost scales with how much surface it finds. --max-budget-usd is the only thing that bounds it, and it is counted across the whole run rather than per step.
In a pipeline
bashrokkhe \
--target . \
--diff-base origin/main \
--non-interactive \
--max-budget-usd 5Scoping to --diff-base keeps a per-pull-request run proportional to the change rather than re-testing the whole repository each time. Diff scope needs full Git history, so check out with fetch-depth: 0. In a CI job that is building a pull request, --scope-mode auto (the default) turns diff scope on by itself; --scope-mode full turns it off.
| Exit code | Meaning |
|---|---|
| 0 | The run completed and reported no vulnerabilities. |
| 1 | Setup or the engagement failed: Docker, the sandbox image, the environment, or diff scope. |
| 2 | With --non-interactive, the run reported at least one vulnerability. Also returned for an invalid command line. |
| 3 | Another process already holds this run name. |
A pipeline that should fail on findings can rely on exit code 2. See /learn/ai-pentesting-on-every-pull-request for the whole pattern.