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 lets you hand real work to coding agents and still decide what joins your 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.

You use these in an interactive terminal.

Open the desk, your interactive view of every task in this project. From the desk you can start tasks and agents, run project scripts, review changes and Proof, land work or pre-approve it, and clean up worktrees. Run it from the main checkout; bare discern opens it too. It needs an interactive terminal. To list worktrees from a script, use discern status --all --json.

Usage: discern desk [options]

Open a shell in another worktree, in the same folder you're in now. Pick the main checkout or a worktree from the list, and exit the shell to return. If that folder doesn't exist there, the shell opens in the nearest one that does. It changes nothing and needs an interactive terminal. To list worktrees from a script, use discern status --all --json.

Usage: discern enter [options]

Your coding agent runs these as it works.

Show where this checkout stands and what to do next. It runs no checks, tests, or measurements, and changes nothing in your project. From the main checkout, it also lists the task worktrees.

Usage: discern status [options]

Run the quick checks while you work: fix and regenerate files, then run the read-only checks, without tests. In order, it runs the fix jobs, such as the formatter, the [generated] commands, and discern refresh, then the check jobs, such as lint and type-check. It works on uncommitted changes, may change files, and never commits. It skips build and test jobs, scopeScope↗A named area of your project, such as its documentation, defined by path patterns. gates, and standards, and records no Proof. Run it before your final commit, so discern done has nothing left to rewrite.

Usage: discern prepare [options]

Run the gateGate↗The full set of checks your project requires before a change counts as finished. on a clean, committed tree and record Proof when it passes. The gate is your project's full quality check: the jobs it configures, such as format, lint, type-check, and tests. Uncommitted or untracked files stop it before anything runs. Its fixers may change files, and a change to a committed file fails the run without committing anything, so run discern prepare and commit first. discern asks any checkpoint questionsQuestion↗Something discern asks your agent to judge, about a change or about the project as a whole. before the checks run. If current Proof already covers this commit, done returns it without running the checks again.

Usage: discern done [options]

Run your project's tests on their own, without the rest of the gate. It runs every test-stageStage↗A group in the order the gate runs its work. job, such as test and smoke, and waits for a free test-run slot first. It works on uncommitted changes and records no Proof. You don't need it before discern done, which runs the tests itself.

Usage: discern test [options]

Check on a long operation, such as discern done, after losing track of it. It shows the operation's current phase, the counts and failures so far, and its result once it finishes. Pass the progress handleProgress handle↗A short code, such as R1-XXXX-XXXX-XX, that lets your agent read back a long-running command after losing track of it. that an MCP call announced or discern status shows; without one, it reads this checkout's latest operation. It changes nothing and never reruns the operation.

Usage: discern progress [handle] [options]

Run a command, such as a test suite, once a test-run slot is free, so parallel tasks don't overload this machine. [gate].concurrent_test_runs sets how many slots every checkout shares. Outside a project, or when that setting is 0, the command runs straight away. discern runs it directly, not through a shell, and passes its output and exit status through unchanged. Everything after -- belongs to the command, and there's no --json, --markdown, or --render form. To wait for another task instead, use discern await.

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

Format the files discern manages: the mapMap↗Your project's own guide to how its software works and why, which your agents write and keep current., the TODO list, your instruction files, and discern.toml. A file a [generated] group owns is left to its generator. Pass md or toml to format one kind; leave it out for both. It also checks that box-drawing diagrams in code blocks stay aligned: a misaligned diagram fails the run without stopping the formatting, and a fence marked freeform is skipped. If any file can't be parsed, such as Markdown with invalid YAML frontmatter, or formatting would drop cells from a table row, discern changes no files at all. Escape a pipe inside a code span as \| to keep its cell.

Usage: discern tidy [type] [options]

Your agent starts, updates, and lands each task with these.

Create a worktree for a new task: a separate checkout on its own branch, started from the trunk, your project's shared branch. Run it from the main checkout. discern sets the worktree up, including its resources and setup commands, then prints its path. Uncommitted work in the main checkout stays where it is.

Usage: discern start [options]

Merge the latest trunk, your project's shared branch, into this branch, and refresh what depends on it. For a newer discern, use discern upgrade; for agent filesAgent file↗An instruction file your coding agent reads when it works on your project. alone, use discern refresh. Run it in a task worktree with no uncommitted changes to tracked files. discern settles conflicts in generated filesGenerated file↗A file discern builds for your coding agents: an agent file or a skill folder. by regenerating them; any other conflict stops the merge and leaves your files as they were. Then it reruns the generators, refreshes agent files, and runs the ensure commands, even when there was nothing to merge. It lists the files both sides changed, so you can re-read them.

Usage: discern update [options]

Wait for another task: until its work passes the gate, until it lands, or until the trunk moves. By default it waits up to 3300 seconds and returns as soon as the condition holds. If time runs out first, it exits with status 124 and returns a short handle; pass it to --resume to keep waiting for the same thing. It doesn't change any work, and it blocks only the command that called it. To wait for a free test-run slot before running a command, use discern queue -- <command> [args...] instead.

Usage: discern await [options]

Land this worktree's proven commit on the trunk, your project's shared branch. A proven commit is one that discern done passed. It lands only with the owner's approval in this conversation or a recorded grant; otherwise discern records it in the landing queue for the owner. If the trunk moved since the Proof, discern checks the combined code in a temporary integration worktreeIntegration worktree↗A temporary copy of the project where discern checks a change combined with newer work before landing it. and lands exactly what passed. A second accept waits its turn. After landing, discern removes the worktree, its resources, and its branch, unless the branch has newer commits or the checkout has uncommitted changes. discern accept queue adds the commit to the landing queue without landing it. discern accept emergency --reason <text> starts an emergency landing of a repair whose checks haven't passed: it needs the owner's fresh, explicit approval and issues no passing Proof.

Usage: discern accept [action] [options]

Manage worktrees: separate checkouts, each on its own branch, for one task.

Usage: discern worktree <subcommand>

Set up this worktree, or bring its setup up to date. discern start runs it for you. The first run creates the worktree's resources, env values, and port, and runs its one-time setup steps. Later runs check the resources and rerun the ensure commands. Run it inside the worktree. If a setup step was interrupted, it stops and shows how to recover.

Usage: discern worktree setup [options]

Make sure this worktree is set up; it's safe to run any number of times. Coding agents' session-start hooks run it. In a worktree that isn't set up yet, it runs the full setup. In one that is, it checks the resources and reruns the ensure commands, and a failure never blocks the session. In the main checkout it changes nothing and reminds the agent to start a worktree before editing.

Usage: discern worktree ensure [options]

Change this worktree's title. Its id, branch, path, brief, and starting point stay the same.

Usage: discern worktree rename <title> [options]

Remove this worktree's resources, such as its database, and keep everything else. The checkout, branch, and Proof stay. Run it inside the worktree. To remove the worktree as well, use discern worktree drop from the main checkout.

Usage: discern worktree teardown [options]

Set a task aside: remove its checkout and resources, and keep its branch, title, and brief so you can resume it. Run it from the main checkout. The worktree must have no uncommitted or untracked changes. Parking also removes the task's Proof, grant, and landing-queue entry. Resume with discern start --from <branch>. Name the worktree by id, path, local branch, or full local ref.

Usage: discern worktree park <worktree> [options]

Delete a worktree, its resources, and its branch. Run it from the main checkout. discern refuses when the worktree has uncommitted changes or commits that aren't on the trunk, unless you pass --force, and it never drops a locked worktree. It first saves the branch's last commit to a recovery ref and prints it. It deletes the branch only if discern created it. Name the worktree by id, path, local branch, or full local ref.

Usage: discern worktree drop <worktree> [options]

Clean up what finished work leaves behind: landed worktrees and their branches, stale records, folders that reappeared, and orphaned resources. discern removes only what it can show it created, such as a clean worktree whose branch is fully merged. Commits that haven't landed stay on their branches. Run it from the main checkout; it asks before changing anything unless you pass --yes.

Usage: discern worktree prune [options]

Print a stable value discern derives for a checkout's branch, development host, port, database, and external resources. Choose one value per call; the default is the id. Name another checkout by id, path, local branch, or full local ref; the default is the checkout you're in.

Usage: discern identity [worktree] [options]

Your project's own scripts, listed or run by name.

List your project's scripts, or run one by name. discern looks the name up as written, with no partial matches. It runs the script from the project root with DISCERN_ROOT, DISCERN_TOML, DISCERN_SCRIPTS_DIR, and DISCERN_TRUNK set, passes every following argument through unchanged, and returns its exit status.

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

You or your agent set up, check, and look after discern.

Start here to set up discern: see what setup involves and which step comes next. It changes nothing, and it works even outside a Git repository. Run discern setup begin only once the owner is ready for discern to add its files.

Usage: discern setup <subcommand>

Preview what setup will change, and the checklist to agree with the owner first. It changes nothing. It reports what it finds, such as existing agent instructions and the coding agents installed here, and where worktrees will go. Then it prints the consent checklist your agent goes through with the owner before anything is written.

Usage: discern setup verify [options]

Set discern up in this project: add its files and settings, and print the setup brief for your agent. This is the first setup step that changes files. A fresh setup starts on the trunk with no uncommitted changes to tracked files. It works on a new discern-setup branch, commits discern's own wiring, and records which discern versiondiscern version↗The version of discern you're running, shown by discern --version. and model ran it. Without --confirmed or --config, it writes nothing and shows the consent checklist again. Partway through setup, it prints the brief again; once setup is complete, it does nothing unless you pass --reseed.

Usage: discern setup begin [options]

Show one numbered step of the setup brief again, to refocus partway through setup. It changes nothing.

Usage: discern setup step <n> [options]

Finish setup: run the gate on the committed setup, record its Proof and a summary of what was set up, and mark setup complete ([meta].bootstrapped). Everything must be committed, with every setup placeholder filled in. discern commits the completion, checks it in a temporary worktree, and runs the full gate; if that fails, it removes its own commit. Then discern setup accept lands the setup.

Usage: discern setup done [options]

Land the proven setup branch on the trunk, then list the checks that confirm each coding agent can reach discern. Run it from the discern-setup branch. If the trunk has moved, discern merges it in and runs the gate again first. It records a Proof noteProof note↗A copy of a landed change's Proof, stored with its commit in Git., switches you to the trunk, and deletes the setup branch. It doesn't push.

Usage: discern setup accept [options]

Bring this project up to date with the discern you have installed. To bring the trunk into a task branch, use discern update; to regenerate agent files only, use discern refresh. It runs any pending config migrations and restores discern's sections, keys, and comment banners in discern.toml without touching your values. It updates discern's blocks in .gitignore and .gitattributes, and refreshes agent files, skills, and integrations. Run it from the project root. It never installs a newer discern, uses no network, and doesn't commit.

Usage: discern upgrade [options]

Check that discern is installed correctly and that Git is set up safely for it. It checks the config, jobs, generated groups, agent integrations, skills, worktree resourcesWorktree resource↗Something one worktree needs of its own, such as a test database, an emulator, or a container., and logbookLogbook↗discern's local record of what each command did and how long it took., and Git settings such as commit identity and history retention. Then it lists the steps each workflow command runs. It changes nothing, and exits 1 only when a check fails.

Usage: discern doctor [options]

Read, explain, and edit discern.toml, keeping its comments. set-job, set-scope, and set-standard edit those tables; set <dotted.key> edits other keys, such as generated groups, checkpoints, and resources. discern checks each edit against the schema, writes nothing if the result would be invalid, and never commits. Run edits from the project root.

Usage: discern config <subcommand>

Add or change a gate jobGate job↗One named step the gate runs, such as your tests or your linter.: one of the commands the gate runs. A known name (format, build, lint, typecheck, test, smoke) has a fixed stage: give its command as the argument, or with --run, repeated for commands that run in order. A custom name needs --stage and --run. For a known job this project doesn't have, use --not-applicable.

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

Add or change a scope: a named region of the repository, defined by path patterns. The patterns you give replace the scope's paths, and options you leave out keep their current values.

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

Add or change a standard: a limit on a measured number, such as test coverage, that the gate holds. Give exactly one of --run or --producer.

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

Set one key in discern.toml, named as section.key, including keys in named tables. discern takes the value's type from the schema, and turns a single value into a one-item list for a key that takes a list of strings. It refuses sections, unknown keys, and retired names, and writes nothing if the result would be invalid.

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

Print one value as it's written in discern.toml, such as repository.trunk. It fails for a key the file doesn't set; use discern config has to check first.

Usage: discern config get <key> [options]

Print a list value from discern.toml, one item per line.

Usage: discern config array <key> [options]

Check whether discern.toml sets a key or section. On its own, it prints nothing and exits 0 if it does, 1 if not. With --json, it reports the answer in data.present and exits 0.

Usage: discern config has <key> [options]

Print the names of the tables directly under a section, such as each named table under standards.

Usage: discern config subsections <key> [options]

Print the names of the keys a section sets, without its nested tables.

Usage: discern config keys <key> [options]

Explain a section, a family of named tables, or one key of discern.toml: what it controls, why it matters, its keys and defaults, your current value, and examples. It works outside a project too.

Usage: discern config explain <path> [options]

Regenerate your agent files, skills, agent integrations, and ADR index from their sources. To bring the trunk into this branch, use discern update; to update the project for a newer discern, use discern upgrade. It also updates discern's block in .gitattributes and discern's settings in the repository's Git config. It writes files but never commits. It never removes an agent's files, even when you drop that agent from [project].agents.

Usage: discern refresh [options]

Remove discern's wiring from this project, and keep the files you wrote. It removes the generated agent files, installed skills, agent integrations, and discern's blocks and settings. Your discern.toml, instruction source, map, own skills, project scripts, and TODO list stay. It asks before removing anything. It refuses while task worktrees or their resources exist. It keeps local Git refs such as Proof notes, doesn't remove the discern program, and doesn't commit.

Usage: discern uninstall [options]

Reports, reviews, and documentation for you or your agent.

Find the most valuable improvement to make next in how this project uses discern. It scores what discern can check automatically, lists the review questions it can't, for your agent and you to weigh together, and suggests one next step. It changes nothing.

Usage: discern improvement [options]

Measure your project's standards: limits on measured numbers, such as test coverage or bundle size. A change can tighten a limit, but loosening one needs the owner's approval. Name standards to measure only those; otherwise discern measures them all. It first checks that no limit is looser than the trunk's, and saves each measurement so a later --pin or discern done can reuse it for the same commit. You don't need it before finishing: discern done checks every standard. For a number that grows with the project, hold a rate with per. Give a total that drifts a margin, or a limit pinned at today's value fails the next ordinary change.

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

Propose a looser limit for a standard this change breaks, for the owner to approve. Run it on the branch's final, clean commit. discern measures the standard and commits a proposal that changes only its limit, set to the measured value. Rerun after later commits, with the same reason, to carry an unchanged proposal forward without a new commit. Landing still needs the owner's explicit approval of the value and reason.

Usage: discern standards propose <name> [options]

Show the checkpoints that apply to this task, whether each question has an answer, and which ones the current change would trigger. It also shows how often each checkpoint has fired, been answered unmet, and needed a variance. It runs no when commands and changes no checkpoint state.

Usage: discern checkpoints [options]

Manage skills, the reusable playbooks your agents follow: list them, or copy a built-in one so you can edit it.

Usage: discern skills <subcommand>

List the skills your agents get: discern's built-in skills and yours, which of yours replace a built-in, and which are excluded.

Usage: discern skills list [options]

Copy a built-in skillSkill↗A ready-made playbook that tells your agent how to handle a particular kind of task. into your skills folder, [skills].dir, so you can edit it; your copy then replaces the built-in. If discern.toml doesn't set [skills].dir yet, discern adds it. It refuses a name that isn't a built-in skill, or one you've already copied, and it doesn't commit.

Usage: discern skills eject <name> [options]

Show which scopes this branch's changes touch, and so which scope gates discern done will run. Scopes are named regions of the repository, set in discern.toml. It counts the branch's commits since it left the trunk, plus uncommitted and untracked files. Neutral scopes never appear. It also lists code when any file outside the neutral scopes changed, and previewable when a scope with a preview command changed.

Usage: discern impact [options]

Find files that usually change together in your Git history, so a change doesn't miss one. With no arguments, it lists files that often change with the ones you changed but are missing from your change. With one file, it lists that file's usual partners. With two files, it lists recent commits that changed both. It's advice only and always exits 0.

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

Show patterns in how this project uses discern, from its local logbook. Findings cover standard trends, how well the gate fits the work, habits such as repeated failures, and the path from start to landing. Each finding shows its counts and what the logbook couldn't see, and says when there isn't enough evidence. It's advice only.

Usage: discern patterns [options]

List the logbook's sealed archives, with each one's event count, date range, and size.

Usage: discern patterns archives [options]

Delete the active logbook for good, once you confirm in an interactive terminal. Sealed archives and discern's other files in .git stay. The confirmation defaults to keeping the logbook. In CI, with --plain, or with --json or --markdown, only --dry-run works.

Usage: discern patterns reset [options]

Archive the active logbook under a timestamped name and start a fresh one, once you confirm in an interactive terminal. The confirmation defaults to keeping the logbook as it is. In CI, with --plain, or with --json or --markdown, only --dry-run works.

Usage: discern patterns seal [options]

Browse your project's map, the documentation your agents keep about how the project works, or read one page by name.

Usage: discern map [target] [options]

Browse discern's manual, which comes with discern, or read one page by name.

Usage: discern docs [target] [options]

Show help for discern, or for one command, such as discern help worktree prune.

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

Print discern's licenses and notices, and the notices for the third-party software built into it.

Usage: discern licenses [options]

Open discern's release notes in your browser, to see what's new and whether a newer discern is out. discern itself makes no network request: the page compares your version with the latest. The browser opens only from an interactive terminal. Inside a project, discern records when you last looked, for its reminder to check for releases.

Usage: discern releases [options]

Run discern's MCP (Model Context Protocol) server, which gives coding agents most of discern's commands as tools. You don't need to run it yourself: setup and discern refresh configure each agent to start it. It talks over standard input and output.

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 script name, belong to the child command rather than discern.

Bare discern docs on an interactive terminal opens the documentation reader: grouped contents with a preview of the selected document, one document at a time, and search across every entry. discern map uses the same reader for the configured project map, and the desk opens it over the manual without leaving its screen.

Admitted relative-document links and heading fragments stay inside the reader. Absolute http:// and https:// destinations open in the system browser while the reader stays on screen; if a page can't open, the reader says why. Other external schemes are not supported.

With mouse tracking available, the wheel moves the contents selection or scrolls the document under the pointer by three rows. A left click selects an entry, a click on the selected entry opens it, and 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 a terminal of at least 32 columns and 10 rows. Below 80 columns the contents show a short summary of the selected entry instead of its preview. A terminal resized below the minimum shows a notice until it grows again.

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.

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.