Automation
Headless CLI
Run the same workspace from the terminal with vortex run and vortex review, including detached jobs, CI gates, and review rules from AGENTS.md.
The desktop app is one front end for the same workspace. The vortex command line runs the same loop — understand, plan, implement, verify — from a terminal, so the work can happen in a script, a CI job, or an SSH session.
A first run
vortex run --prompt "…" --workspace . --model openai/gpt-4o-mini--workspace sets the directory the agent works in. --model names the model to use. Omit the model to use the default from your configuration.
Run flags
| Flag | Effect |
|---|---|
--prompt "…" | The job to run |
--workspace <path> | Directory the agent edits and runs commands in |
--model <provider/model> | Model for this run |
--provider <id> | Built-in provider, or any OpenAI-compatible provider you have saved |
--base-url <url> | OpenAI-compatible root, when that provider is not already saved |
--job-dir <path> | Where job state and traces are written |
--verbose | More detail in the terminal output |
--detach | Start the job and return immediately |
--list | List known jobs and their status |
--automation-id <id> | Load that automation's prompt, workspace, and model |
API keys
Provide a key in one of these ways:
--api-keyon the command line.VORTEX_RUN_API_KEYforvortex run.VORTEX_REVIEW_API_KEYforvortex review.- The provider's own environment variable, such as
GEMINI_API_KEYorDASHSCOPE_API_KEY. ~/.vortex/provider-keys.json, the same file Settings writes, when none of the above is set.
OPENROUTER_API_KEY is also read when you route through OpenRouter. Do not commit keys to the repo. An environment variable or --api-key wins over the file.
Detached jobs
--detach starts the run and returns control to your shell. Status and traces are written under:
~/.vortex/detached/<id>/You can close the terminal and collect the result later. List the jobs you have started with:
vortex run --listA detached job only survives a closed laptop if it was started over SSH and kept alive on the remote with nohup. A job on a sleeping local machine stops when the machine sleeps.
Run health
vortex stats --since 7dvortex stats is a read-only summary of local foreground runs: how they finished, how many steps they took, and phase timing (model time, time to first token, tool time, cache hit rate, and edit misses). Phase timing says how many runs it covers. Quality counters come from the trace for every run in the window: tool failures, edit misses, completion-gate rejections by reason, and the top tool-failure messages, with paths and numbers masked. It also prints why a run never finished, and groups backend request failures the same way. It prints recovery attempts and how often each one got the run moving again. The stop check line includes how often a text reply was treated as finished or still going, and the mean continue score. Runs with no model are labeled as backfill and stay in the counts. It also prints sub-agent runs in the same window: how many, prompt size, tools per step, and time to first token. It prints how tool arguments were shaped: repaired, rejected, or left as sent. It prints counts and durations only. --since accepts 7d or 12h and defaults to 30d. --format json prints the same report as JSON.
Reviewing a branch
vortex review diffs HEAD against a base branch, sends the diff to a cloud model, and returns findings:
vortex review --json --base main --fail-on error| Flag | Effect |
|---|---|
--base <branch> | Branch to diff against |
--provider <id> | Built-in provider, or any OpenAI-compatible provider you have saved |
--base-url <url> | OpenAI-compatible root, when that provider is not already saved |
--max-tokens <n> | Cap on the review response |
--format text or --format json | Output format |
--fail-on never, warning, or error | Lowest severity that fails the command |
Repo rules as review rubric
vortex review reads the Code Review Rules section of your AGENTS.md and treats it as extra rubric on top of the default. A repository can therefore enforce its own rules — ban unwrap() on library paths, require Result-returning helpers, flag a new Tauri command that is not registered — without changing the CLI.
CI examples
A pull-request gate that fails the build on any error-severity finding:
vortex review --json --base main --fail-on errorA nightly job that runs detached and leaves its traces behind:
vortex run --detach --prompt "Update the lockfile and run the test suite" --workspace .Exit codes matter for CI. --fail-on sets the threshold, but you can also read the JSON output and apply your own gate — fail only on findings that touch files you own, or post the JSON as a review comment. Combine both rather than relying on a single threshold.
Beta surface
The CLI is a beta surface and changes between builds. Check the flags with the built-in help before you wire it into a pipeline, and pin a version in CI if the job must be stable.
Related
- GitHub pull requests — the same review in a PR tab, plus Fix with agent.
- SSH remote workspaces — run the same jobs against a remote directory.
- MCP integrations — the tools a headless run can call.
- Review mode — the same pending-patch model in the GUI.
Vortex is in a closed beta on macOS. Add your email to the waitlist to get an invite.