CLI reference

The styre binary has six commands: run, ls, clean, setup, migrate and notify.

Two flags work before any command:

Flag	Effect
--version	Print the version and exit. Must be the first argument.
--help, -h	Print usage and exit. Works anywhere.

styre run

Drive one ticket to an open pull request, then exit.

styre run <ticket>

<ticket> is the tracker identifier, e.g. ENG-482. It is required for a fresh run and omitted when resuming.

A fresh styre run <ticket> refuses (exit 64) when a checkpoint already exists for that ident — it will not silently overwrite in-progress state. Resume it with --resume <ident>, or discard it and start over with styre run <ticket> --fresh.

Flag	Default	Effect
--profile <path>	the cwd repo’s profile	The project profile to run against.
--config <path>	discovered	Use this config file only. When set, nothing else is merged — see Configuration.
--slug <name>	derived from the repo	Which project’s profile and config to load.
--db <path>	the run’s checkpoint at ~/.local/state/styre/<slug>/<ident>/run.db	Override where the run’s state of record lives.
--resume <ident>	—	Resume a paused run instead of starting one. Replaces the positional argument.
--fresh	off	Discard an existing checkpoint for this ticket and reconcile the worktree, then start over. Fresh-run only.
--accept-head	off	On resume, proceed even though the branch moved — dropping the carried-over context.
--inspect	off	On resume, print what would happen and exit without running.
--in-place	off	Work on a branch in the repo root instead of an isolated worktree. See the warning below.

--in-place rewrites your working checkout

Normally Styre works in a throwaway git worktree and never touches your checkout. --in-place makes it check out and mutate the branch in the repo root directly. It is meant for disposable, single-use checkouts — a CI job, a container — and it refuses to run unless the repo root contains a file named .styre-disposable. Do not use it in a checkout you care about.

run writes only NDJSON telemetry to stdout; everything human-readable — progress, the final summary, warnings, resume hints — goes to stderr. This is what makes styre run … | jq clean.

See The run loop for what happens between the command and the pull request, and Recovering a run for --resume, --fresh, --accept-head and --inspect in context.

styre ls

List every styre effort across all projects, by checkpoint state.

styre ls

No flags. Prints three sections, in order:

Paused/resumable efforts:
  <ident>  [<kind>, <age>]  <note>
    resume: styre run --resume <ident> --slug <slug>

Finished leftovers (reap per project with `styre clean --all`):
  <slug>/<ident>  [<kind>, <age>]  <note>

Running:
  <ident>  [<kind>, <age>]

• Paused/resumable efforts — every checkpoint that is resumable and not currently live. Each row is followed by the exact command to resume it (--slug included, since ls spans every project).
• Finished leftovers — checkpoints classified pr-ready/done and not live: provably finished, safe to reap with styre clean --all. Rows are slug-qualified (<slug>/<ident>) since leftovers span every project. There is no merge-state check (nothing confirms the PR actually merged) and no age-based staleness heuristic.
• Running — checkpoints currently live (an active styre run holds the lock). A live effort never appears as reapable, even if its classified kind would otherwise qualify.

styre clean

Reap an effort’s disk artifacts — free its worktree and delete its checkpoint directory.

styre clean <ident>
styre clean --all
styre clean <ident> --purge

Flag	Default	Effect
<ident>	—	Ticket ident to clean, e.g. ENG-123. Required unless --all.
--all	off	Reap only the provably-finished (pr-ready/done) efforts for the current project; skips resumable pauses and live runs. Mutually exclusive with <ident>.
--purge	off	Single-ident only — rejects alongside --all (exit 64). After reaping, also deletes the local + remote branch, closing the PR.
--slug <name>	derived from the repo	Project slug to locate the profile.
--profile <path>	discovered	Path to the project-profile JSON.

• styre clean <ident> reaps that one effort’s worktree + checkpoint. Clean never changes ticket status — that’s the issue tracker’s job, driven by the merge itself. Cleaning a run’s disk state is not the same as abandoning the ticket. It refuses a live run: exit 75.
• styre clean --all is scoped to the current project’s slug: it reaps only checkpoints classified pr-ready/done and not live. Resumable pauses and live runs are skipped, not reaped.
• styre clean <ident> --purge additionally deletes the local + remote branch after reaping, closing the PR. It’s opt-in and single-ident (--all --purge together is rejected, exit 64), and silent when there is no branch/PR to delete. On the repo’s default branch, --purge skips the branch/PR deletion — the default branch is never deleted — but still reaps the disk state, printing a stderr warning and exiting 0 (a soft skip, not a failure).

styre setup

Probe a repository and write its project profile.

styre setup <repo>

<repo> is optional. Give a path and it probes that repo. Omit it and it probes the current directory — but only if the repo root holds a .styre-disposable marker, the same guard as --in-place. Pass the path explicitly and you do not need the marker.

Flag	Default	Effect
--out <path>	the profile path for this repo	Write the profile somewhere else.
--checks <github|external|none>	the probe decides	Override how CI status is read. Any other value is rejected.
--slug <name>	derived from the repo	Store the profile under a different project name.
--force	off	Discard the existing profile and probe from scratch, dropping hand-resolved values.
--reprobe	off	Same behaviour as --force.
--config <path>	discovered	Selects the agent provider for the probe, so the right API key is required. Not written into the profile.
--trust-agent-commands	off	Headless only. Accept agent-refined command strings without a prompt. See the warning.

When run in a terminal, setup prints the full resolved command list and waits for you to type y. Anything else aborts and writes nothing. See Your first run for that flow.

--trust-agent-commands skips the one safety prompt

The interactive y prompt exists because the listed commands later run on your machine with repo write and network access, and some may have been written by the agent that probed the repo. --trust-agent-commands accepts them with no prompt. It only applies when there is no terminal to prompt at, and it is safe only on a repo you trust in an isolated environment.

styre migrate

Create or upgrade the shared SQLite database. Idempotent — safe to run any time.

styre migrate

Flag	Default	Effect
--db <path>	the default state database	Which database file to create or upgrade.

Most people never run this directly. styre run journals to its own per-run checkpoint by default (~/.local/state/styre/<slug>/<ident>/run.db), so migrate only matters if you point runs at a shared --db you manage yourself.

styre notify

Send one test message through your configured notifier, to check your Slack setup.

styre notify --test

Flag	Default	Effect
--test	off	Required. Send one test message. Without it, notify prints usage and exits 64.
--config <path>	discovered	Use a specific config file.
--slug <name>	derived from the cwd repo	Which project’s notifier config to use.

It resolves config exactly as styre run does, so it tests the same channel a real run would post to. Notifier setup lives in Configuration.

Environment variables

Styre reads all credentials from the environment; see Install for setting them.

Credentials

Variable	Needed for
ANTHROPIC_API_KEY	The default claude agent provider.
OPENAI_API_KEY	The codex agent provider.
GITHUB_TOKEN	Pushing the branch, opening the PR, reading checks.
LINEAR_API_KEY	The Linear tracker.
JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN	The Jira tracker.
SLACK_BOT_TOKEN	The Slack notifier.

Paths and telemetry

Variable	Effect
XDG_CONFIG_HOME	Base for Styre’s config and profiles. Defaults to ~/.config.
XDG_STATE_HOME	Base for the database, run checkpoints and telemetry id. Defaults to ~/.local/state.
STYRE_TELEMETRY	Set to 0 or false to disable analytics.
DO_NOT_TRACK	Any value except empty/0/false disables analytics.

See Files and paths for what Styre reads and writes, and Telemetry for what analytics covers. Full exit-code meanings are on the Exit codes page.