> For the complete documentation index, see [llms.txt](https://novusedge0.gitbook.io/docket-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://novusedge0.gitbook.io/docket-docs/technical-reference/commands.md). # Commands Ledger commands use the file that `docket where` reports. Run `docket COMMAND --help` for a command's flags. For a walkthrough, start with [Your first decision](/docket-docs/getting-started/quickstart.md). | Command | What it does | | ------------------------------------- | ---------------------------------------------------------------------------- | | `docket claim TEXT` | Record a proposition | | `docket decision QUESTION --choice C` | Record a commitment | | `docket question TEXT` | Record an open question | | `docket list` | List current records | | `docket show ID` | Print one record in full | | `docket graph` | Browse how records connect | | `docket context` | Print the briefing an agent reads | | `docket where` | Print which ledger file is in use | | `docket check` | Report what makes the ledger unreadable | | `docket init` | Create a project ledger and copy any existing private records into it | | `docket migrate` | Convert a pre-0.8 ledger to the current schema | | `docket rebase` | Renumber another branch's records onto this ledger | | `docket update` | Update this Docket installation; `--check` reports without changing anything | | `docket completion SHELL` | Print a shell completion script | ## Recording `claim`, `decision`, and `question` share most of their flags. | Flag | Applies to | Effect | | ------------------ | --------------- | --------------------------------------------------------------------------------------------------- | | `--choice C` | decision | The choice made. Required. | | `--alternative A` | decision | An option considered and put down | | `--decided-by WHO` | decision | Who made the call | | `--state S` | claim, decision | `unassessed`, `accepted`, `disputed`, `rejected` for a claim; `adopted` or `revoked` for a decision | | `--scope GLOB` | all | Files the record applies to | | `--rationale TEXT` | all | Why | | `--cost TEXT` | all | What it costs you if this is wrong | | `--evidence REF` | all | A pointer to what backs the record | | `--revisit TEXT` | all | A condition that should bring this back up | | `--supports IDS` | all | Earlier claims or decisions given as grounds | | `--depends-on IDS` | decision | Claims or decisions required for this decision to apply | | `--answers IDS` | claim, decision | Questions this record settles | | `--supersedes IDS` | all | Same-kind records this one retires | | `--pin` | all | Add a ranking bonus in briefings; inclusion is not guaranteed | Every ID flag takes a comma-separated list. Repeat `--supports` for alternative sets of grounds: `--supports c1,c2 --supports c3` means `(c1 AND c2) OR c3`. Repeat `--scope`, `--evidence`, or `--alternative` for more than one value. A decision prerequisite must be current, adopted, and applicable. A claim prerequisite must be current and accepted. A decision with missing prerequisites remains recorded as adopted but reports that it is blocked. See the [relationship reference](/docket-docs/technical-reference/ledger.md#relations). ## Reading `docket list` | Flag | Effect | | --------------------- | ------------------------------------------------------- | | `--kind K` | Only `claim`, `decision`, or `question` | | `--state S` | Only records in that state | | `--find TEXT` | Match record text or a decision's choice, ignoring case | | `--superseded` | Include records a later one retired | | `--oneline` | One line per record | | `--json` | Print records as JSON | | `--plain`, `--pretty` | Force colour off or on | `docket show ID` | Flag | Effect | | --------- | ----------------------------------------------- | | `--json` | Print every field | | `--at ID` | Show the record as history stood at that record | `docket graph` | Flag | Effect | | ----------------------------------- | ----------------------------------- | | `--style forest\|rail\|compact` | Static layout | | `--kind`, `--state`, `--find` | Filter, as in `list` | | `--interactive`, `--no-interactive` | Require or refuse the native viewer | | `--plain`, `--pretty` | Force colour off or on | `docket context` | Flag | Effect | | --------------------------------- | -------------------------------------------------------------------------- | | `--query TEXT` | Aim the briefing at a task | | `--file PATH` | Aim it at a file. Repeat for more. | | `--max-chars N` | Set a hard character ceiling. The default minimum is 512. | | `--all` | Drop relevance filtering, keep the budget | | `--auto-scope`, `--no-auto-scope` | Derive scope from the working tree, or never | | `--since ID` | Report changes after that record; also accepts `ID@DIGEST` from a briefing | | `--for gemini\|copilot\|cursor` | Wrap the output in that tool's hook format | ## Maintenance `docket check` prints the record count when the ledger reads cleanly, and names the bad line or relation when it does not. `docket rebase OTHER` renumbers the records in `OTHER` onto the end of this ledger. Use `--dry-run` to see the ID map first. `docket migrate` converts a schema 1 ledger. Use `--dry-run` to review the conversion, `--emit-map PATH` to write the derived classification map, and `--map PATH` to apply a map you edited. See [Maintenance](/docket-docs/everyday-use/maintenance.md) for when to reach for these. ## Constructing `docket construct PATHS` reads the markdown under `PATHS` and stages ledger proposals in `.docket/proposed.jsonl`. It writes nothing to the ledger. `--dry-run` lists the documents and calls nothing. `--jobs N` sets how many documents are read at once. `docket construct --review` prints the staged proposals with the source line each one quotes. `docket construct --accept` appends the proposals you marked `accepted`. `--source PATH` takes one document's records and leaves the rest staged. This command needs the `openai` SDK and an API key. See [Constructing on existing projects](/docket-docs/everyday-use/construct.md) and [Environment variables](/docket-docs/technical-reference/environment.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://novusedge0.gitbook.io/docket-docs/technical-reference/commands.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.