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 <name>`	Provider to route through
`--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

API keys

Provide a key in one of these ways:

--api-key on the command line.
VORTEX_RUN_API_KEY for vortex run.
VORTEX_REVIEW_API_KEY for vortex review.

OPENROUTER_API_KEY is also read when you route through OpenRouter. Do not commit keys to the repo and do not write them into app preferences; pass them through the environment or the flag.

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 --list

A 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.

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 <name>`	Provider to route through
`--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 error

A 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.

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.