Reference
The command is sd (crate seeds-ai). Each verb has its own page under
The verbs; this page is the summary.
Global options
Accepted on every verb.
| option | meaning |
|---|---|
--json | output as JSON, in br’s output shape |
--actor <NAME> | actor recorded on writes and used by --claim (env SEEDS_ACTOR, else $USER) |
--store <PATH> | use this local quipu store file (configuration) |
--quipu <URL> | use this quipu server (mode 2) |
--graph <IRI> | the project’s named graph (configuration) |
--at <TX> | read as of this transaction (a pin); refused on writes |
-h, --help / -V, --version | help and version |
Verbs
| verb | flags (a br-compatible subset) |
|---|---|
create [TITLE] | --title, -t/--type, -p/--priority, -d/--description, --description-file, -a/--assignee, -l/--labels, --parent, --deps, --dry-run, --silent |
show <ID>... | |
list | -s/--status, -t/--type, --assignee, --unassigned, -l/--label, -p/--priority, -a/--all, --limit (default 50, 0 = all), --sort |
ready | --limit (default: none), --assignee [NAME], --unassigned, -l/--label, -t/--type, -p/--priority, --parent |
count | --by, --status, --type, --assignee, --include-closed |
update <ID>... | --title, -d/--description, --notes, -s/--status, -p/--priority, --assignee, --claim, --add-label, --remove-label, --defer |
close <ID>... | -r/--reason, -f/--force |
dep add <ISSUE> <DEPENDS_ON> | -t/--type (default blocks) |
dep remove <ISSUE> <DEPENDS_ON> | -t/--type (default blocks) |
dep list <ID> | --direction down|up |
comments add <ID> [TEXT]... | -f/--file, -m/--message (alias --content), --author |
comments list <ID> | |
export | --to <DIR> |
import <DIR> | --prefer pendant|store, --replace |
sync | --remote <URL>, --allow-remote-deletes, --dry-run, --status |
merge-driver <BASE> <OURS> <THEIRS> |
create and update also take --workflow-run <RUN> (Formulas).
Exit codes
Exit codes are a contract. A code is never reused or renumbered.
| code | meaning |
|---|---|
| 0 | success |
| 1 | failed: store I/O or anything without a more specific code |
| 2 | usage: an unknown verb, a bad flag or value, --at on a write |
| 3 | not found: an unknown id, dependency or comment |
| 4 | conflict: a lost --claim, the seed changed since it was read, or two ledgers disagree (import, sync, merge-driver, a pendant that changed alongside the store); nothing was written |
| 5 | refused: the shapes rejected the write, a dependency cycle, closing a seed with open blockers without --force, a write over the request limit (SEEDS_MAX_WRITE_BYTES, SEEDS_MAX_WRITE_CLAUSES or the server’s HTTP 413; nothing was sent) |
| 6 | configuration: contradictory or unreadable config (for example store and url both set) |
| 7 | unreachable: the configured quipu server cannot be reached (seeds never falls back to a local store) |
| 8 | indeterminate: a remote write’s response was lost and a read-back does not show it; it may still land. Check the named ids before doing anything; do not simply retry |
| 10-18 | retired: the v0 shell’s per-verb “not yet implemented” codes. Never reused. |
| 20 | not built: reserved for a configured capability that exists in the design but not in this build (no verb returns it today) |
| 21 | elsewhere: a br verb whose capability lives in another tool of the stack (query, upgrade, gate, scheduler, audit, robot-docs); the message says where |
In --json mode an error prints {"error": {"code": "<NAME>", "message": "..."}} on stdout, where <NAME> is FAILED, USAGE, NOT_FOUND,
CONFLICT, REFUSED, CONFIG, UNREACHABLE, INDETERMINATE, NOT_BUILT or ELSEWHERE. The message
always goes to stderr as well.
Remote request task attribution
Every remote request retains X-Quipu-Client: seeds. Set QUIPU_TASK
explicitly to attach diagnostic X-Quipu-Task metadata. Valid task ids are
1–64 ASCII letters, digits, dots, underscores or hyphens after trimming;
they are lowercased for the server’s bounded task label. Invalid or absent
values send no task header and remain unattributed. This header grants no
authority and does not change the selected graph, actor or signed writes.
Remote health, graph-list and query reads preserve explicit caller, session and
task declarations. With no caller declaration or actual harness context, reads
omit X-Quipu-Agent; the executable is not a crew identity. Inherited
SHANTY_AGENT alone remains insufficient outside a harness. Write provenance,
actors, authentication and signatures retain their existing contract.
Reads separately declare X-Quipu-Source (default sd-show, sd-list,
sd-ready, sd-search, sd-stats, sd-count, sd-create, sd-update,
sd-close, sd-comments, sd-where, sd-info, or sd-other from the parsed
CLI command; library calls outside a CLI scope default to seeds) and
X-Quipu-Operation (finite endpoint name: health, graphs, query). Wrappers
may supply QUIPU_SOURCE and QUIPU_OPERATION, using the same bounded token
syntax as task ids. A supplied wrapper source such as st-anchor remains the
outer attribution. No command arguments or item/message text enter the default
source value. Command scope is restored after a call or failure without changing
the process environment or write actor. These are diagnostic extension headers, not authenticated
identity or new metric labels. Servers that do not expose them still cannot
join a completion to its source operation; header propagation alone does not
prove that server visibility. No request body or credential is logged.
Owner-filtered readiness discovers only explicitly open candidates before checking dependencies. Closed ownership history does not create readiness requests. Deferred inclusion still uses its separate existing read, and all remaining filters and claim checks retain their existing semantics.