CLI reference

Find a command, check its options, or look up how the terminal reader works. Your agent usually runs these commands for you; this page is here when you want to understand an invocation or use the terminal yourself.

discern <command> --help shows the same command options in your terminal. Help works before project setup; commands that need a configured project return setup_unfinished until setup is complete.

For options shared by commands, see Global options. For keyboard and mouse controls, see Interactive documentation reader. To interpret a returned status code, see Exit behavior.

These options apply to commands unless an entry says otherwise. When discerndiscern↗A tool that installs and runs an agent development practice in a project. runs another command, options after that boundary belong to the command it runs. For example, options after discern queue -- are passed to the queued command.

Interactive task supervision and worktree entry.

Open the live desk: see tasks, review Proof and changes, open an agent, run Project Scripts, or review acceptance and worktree controls. Bare discern opens the desk. The desk is interactive only; use status --markdown or status --json to list every worktree.

Usage: discern desk [options]

Choose a worktree and open a child shell at the matching project-relative directory. This command is interactive only; use status --all --json to inspect the fleetFleet↗The project's collection of task worktrees..

Usage: discern enter [options]

Your coding agent runs these as it works.

Show what's true right now and what to do next (read-only; does not run the gateGate↗The configured checks a change must satisfy for ordinary completion., the project's full quality check).

Usage: discern status [options]

Fast inner loop: fixers, [generated] regenerations, complete refresh, then read-only checks (no other build jobs, no tests).

Usage: discern prepare [options]

Require a clean, committed tree. Run finishing steps that may change files, then verify the gate — the project's full quality check: format, lint, type-check, and tests.

Usage: discern done [options]

Run the project's configured tests on their own, outside the full gate.

Usage: discern test [options]

Read a long operation back after a lost call: its phase, the counts and failures known so far, and the retained result. Pass the progress handleProgress handle↗The short R1-XXXX-XXXX-XX code recorded for a long operation and announced to MCP callers. the operation announced; with no handle, read this checkout's most recently started operation. Reading changes nothing.

Usage: discern progress [handle] [options]

Run a command while holding one configured concurrent test-run slot. Use discern await to watch a fleet condition instead. This command has no --json, --markdown, or --render mode; tokens after -- belong to the child.

Usage: discern queue -- <command> [args...]

Canonically format discern's configured Markdown sources and root discern.toml, and check that fenced box-drawing diagrams stay aligned. Select md or toml; omit the type to run both. A Markdown file whose frontmatter is not valid YAML, or whose table rows would drop cells when formatted (escape pipes inside code spans as \|), is refused and left unchanged.

Usage: discern tidy [type] [options]

Isolated workspaces your agent drives.

From the main checkout, create a worktree with a separate checkout and branch for one effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to.. Base it on the trunk, the shared landing branch, then print its path.

Usage: discern start [options]

Update this branch: merge the trunk's latest into this branch and re-run generated groups and refresh Agent artifacts. The trunk is the shared landing branch. Use discern upgrade for discern itself; use discern refresh for agent files alone.

Usage: discern update [options]

Block until a fleet condition holds: a sibling branch is green (its worktree holds an honored gate Proof), a branch's work has landed on the trunk, or the trunk has moved. Timing out is not an error; the result carries a short continuation handle that preserves the original condition across calls. To wrap a command behind the concurrent test-run cap, use discern queue -- <command> [args...].

Usage: discern await [options]

Submit this worktree's proven commit and land it on the trunk, the shared landing branch. Landing needs the owner's consent in this conversation or a recorded grant; without one, the submissionSubmission↗An effort's recorded request to land one exact commit. waits in the landing queue. If the trunk moved after the Proof, the landing composes and checks the combined code in a disposable integration worktreeIntegration worktree↗A disposable worktree a landing creates for itself when the trunk moved after a submission's Proof. and lands that exact proven commit; a second accept waits its turn. Landing removes the worktree and its branch when the branch holds nothing beyond the landed commit. Use accept emergency --reason <text> to review an explicit exception against actual trunk. Emergency integration requires fresh exact owner confirmation and issues no passing Proof.

Usage: discern accept [action] [options]

Manage worktrees — separate checkouts and branches for individual changes.

Usage: discern worktree <subcommand>

Set up or re-sync the current worktree.

Usage: discern worktree setup [options]

Idempotent session-start worktree setup.

Usage: discern worktree ensure [options]

Change this worktree's display title. Its id, branch, path, brief, and creation source stay unchanged.

Usage: discern worktree rename <title> [options]

Discard this worktree's resources (destroy without accepting).

Usage: discern worktree teardown [options]

Remove a clean task checkout and its resources while retaining its branch and task wording for resume. Select it by worktree id, path, local branch, or full local ref.

Usage: discern worktree park <worktree> [options]

Discard a worktree from the main checkout: tear down its resources, remove it, and delete its branch. Protects uncommitted work and commits not on the trunk, the shared landing branch, unless --force is set. Select it by worktree id, path, local branch, or full local ref.

Usage: discern worktree drop <worktree> [options]

Reclaim positively-owned merged worktrees, stale state, reappeared paths, and orphaned resources.

Usage: discern worktree prune [options]

Print stable values that keep each checkout's branch, development host, port, database, and external resources separate.

Usage: discern identity [worktree] [options]

Project-owned automation, listed or run by name.

List executable Project Scripts, or run one literal name at the project root with the four supported DISCERN_* variables and every following argument forwarded unchanged.

Usage: discern scripts [name] [args...] [options]

You or your agent tend the installation.

Read the setup welcome and learn the canonical first step. Run discern setup begin only after the owner is ready to scaffold.

Usage: discern setup <subcommand>

Preview what setup will do and the consent checklist to confirm with your human (read-only).

Usage: discern setup verify [options]

Scaffold discern, record provenance, and print the setup brief (the first mutating step).

Usage: discern setup begin [options]

Re-serve one numbered step of the setup brief (read-only; for a mid-setup re-focus).

Usage: discern setup step <n> [options]

Prove the committed setup, return canonical Proof and completion inventory, and record [meta].bootstrapped.

Usage: discern setup done [options]

Land the proved setup branch on the trunk, then return provider activation checks.

Usage: discern setup accept [options]

Bring this project forward to the installed discern: run pending config migrations, reconcile discern-owned config, .gitignore and .gitattributes blocks, and refresh bundled skills and instructions. Never replaces the binary. Use discern update to bring trunk into a task branch; use discern refresh to regenerate project artifacts only.

Usage: discern upgrade [options]

Check the install and Git safety settings, then print each verb's execution model.

Usage: discern doctor [options]

Edit jobs, scopes, and standards with set-*; edit generated groups, checkpoints, and resources with set <dotted.key>; read or explain discern.toml.

Usage: discern config <subcommand>

Set a gate jobGate job↗A named check or operation scheduled by the gate.. Known names (format, build, lint, typecheck, test, smoke) derive their stageStage↗A group in the order the gate runs work. and accept a positional scalar or repeatable ordered --run. Custom names require --stage and --run. Known-job applicability uses --not-applicable or --applicable.

Usage: discern config set-job <name> [command] [options]

Set a scope — a named region of the repository a change can touch.

Usage: discern config set-scope <name> <globs...> [options]

Set a quality standard — standards are numbers that can never get worse.

Usage: discern config set-standard <name> [options]

Set a config key (section.key). The value's TOML type follows the schema; an array-of-strings key wraps a single value.

Usage: discern config set <key> <value> [options]

Print a scalar config value.

Usage: discern config get <key> [options]

Print an array config value, one item per line.

Usage: discern config array <key> [options]

Test whether a key or section exists. Bare: print nothing and exit 0/1. JSON: report data.present and exit 0.

Usage: discern config has <key> [options]

Print the immediate child table names under a section.

Usage: discern config subsections <key> [options]

Print the flat key names declared in a section.

Usage: discern config keys <key> [options]

Explain a config section, named-table family, or key: what it governs, why it matters, its keys and defaults, the current value, and worked examples. Works outside a project too.

Usage: discern config explain <path> [options]

Refresh the agent files, skills, provider integrations, and the maintained ADR index. Use discern update for this branch; use discern upgrade for discern itself.

Usage: discern refresh [options]

Remove discern's wiring from this project (keeps your discern.toml, instructions, and map).

Usage: discern uninstall [options]

Read-only views for you or your agent.

Find the highest-value next improvement, with the health audit and open reviews for agent and owner to evaluate together.

Usage: discern improvement [options]

Measure the named quality standards, or every configured standard when no names are given: numbers that can never get worse. discern done already verifies and measures them on every run. Authoring one? Hold a rate (per) for a number that rises as the project grows, and give a drifting total a margin — a ceiling pinned at today's value fails the next legitimate change.

Usage: discern standards [names...] [options]

Finalize a proposed limit for a standard breached by this change. On a clean final HEAD, measure the named standard, then create its config-only proposal commit or renew an unchanged descendant binding. Acceptance still requires explicit approval for the value and reason.

Usage: discern standards propose <name> [options]

Report the governing checkpoint policy, each open question's declaration state, and a read-only preview of what the current change would fire. Nothing runs and nothing is recorded.

Usage: discern checkpoints [options]

Manage skills: list the effective set, or eject a built-in to customize it.

Usage: discern skills <subcommand>

List the effective skills (built-ins + yours; which override which).

Usage: discern skills list [options]

Copy a bundled built-in into [skills].dir so you can customize it.

Usage: discern skills eject <name> [options]

Show which configured scopes the branch and working tree wake in the quality gate. Scopes are named regions of the repository with their own gate jobs. With --has, JSON reports data.membership and exits successfully for either Boolean value.

Usage: discern impact [options]

Report files that historically change together as a read-only advisory. With no args, report likely siblings missing from the change. With file, report its top partners. Add with to report commits where both changed.

Usage: discern coupling [file] [with] [options]

Report the patterns in this project's discern use, read from the local logbookLogbook↗The local record of the project's use of discern.: validation, evidence reuse, waits, landing latency, gate fit and standard trends. Counts include observation limits. A read-only advisory.

Usage: discern patterns [options]

List sealed logbook archives with their event counts, date spans, and byte sizes.

Usage: discern patterns archives [options]

Permanently remove the active logbook after terminal confirmation. Sealed archives and other Git-admin state remain. A dry-run previews one result; apply is refused with --json or --markdown.

Usage: discern patterns reset [options]

Seal the active event history into a timestamped archive and begin a fresh active logbook after terminal confirmation. A dry-run previews one result; apply is refused with --json or --markdown.

Usage: discern patterns seal [options]

Browse the configured project map that coding agents maintain, or read a named map page.

Usage: discern map [target] [options]

Browse the complete bundled product manual, or read a named manual page.

Usage: discern docs [target] [options]

Show command-line help.

Usage: discern help [command...] [options]

Print discern's licenses and bundled third-party software notices.

Usage: discern licenses [options]

Open discern's release information in the browser, see what's changed, and whether an upgrade is available.

Usage: discern releases [options]

The stdio MCP server, exposing the verbs to an agent as tools. You don't usually need to run this; agents should connect automatically.

Usage: discern mcp [options]

No project setup is required to read help or the version. The command parser owns command usage, argument validation, aliases, and option help. discern <command> --help and discern help <command> read the same command tree as this page.

Options after an exec-style boundary, including discern queue -- and a project scriptProject script↗A runnable procedure the project supplies for its agents and maintainers. name, belong to the child command rather than discern.

Bare discern docs on an interactive terminal opens the grouped documentation reader. The picker searches document titles and paths. discern map uses the same reader for the configured project map.

Admitted relative-document links and heading fragments stay inside the reader. Absolute http:// and https:// destinations open in the system browser only after discern restores the terminal. Other external schemes are not supported.

With mouse tracking available, the wheel moves three picker entries or three document rows under the pointer. A left click focuses a pane and selects a picker entry; clicking a link follows it. Other mouse buttons and releases have no product action. Use the terminal application's own selection modifier to select terminal text while tracking is active; discern does not define that modifier.

The rich reader requires ANSI terminal control and at least 32 columns. With the default three chrome rows, the picker-only layout needs 10 total rows, document-only needs 11, and the split layout begins at 18. Between those bounds, the focused pane occupies all usable rows.

If the rich reader cannot start because ANSI control is unavailable or the terminal is too small, discern uses the sequential picker. An internally rendered document then waits at the exact prompt Press Enter to continue. and the next picker restores the remembered document selection. --pager selects this sequential flow and hands each document to $PAGER, or less -R when $PAGER is unset, when the pager succeeds.

A direct discern docs <target> renders and exits without waiting. Bare discern docs off a terminal prints the table of contents and never requests input. --list, --json, and --raw never enter the reader; --search prints matches. Export writes or returns one Markdown stream, except --export select can request a selection on an interactive terminal.

The implementation and real-terminal contract are public in src/commands/docs.ts and tests/docs_test.ts.

Quiet JSON and Markdown results evaluate their completion policy before choosing the controlled exit status. Predicate result modes exit 0 and place the boolean in data; bare predicates use 0 or 1.

For result-envelope fields and Model Context Protocol delivery, see MCP and results. For symptom-led recovery, see Troubleshooting.