CLI reference

cdno is the command-line interface to a Cuaderno vault. This section documents every command. For the why behind them, see Concepts and Tutorials.

cdno [OPTIONS] <COMMAND>

Run cdno --help for the command list, or cdno <command> --help for any command’s flags.

Global options

These apply to every command:

Finding the vault

When --vault is not given, cdno discovers the vault by walking up from the current directory until it finds a .cuaderno/ folder. If that finds nothing, it falls back to the CUADERNO_VAULT_PATH environment variable. Standing inside a vault always wins over the env var. See Initialise a vault.

Interactive vs. scripted

Write commands follow one convention (the “flags-and-prompts” pattern):

• Interactive terminal, missing a required flag → cdno prompts for it, then asks you to confirm before writing.
• Non-interactive (either stream not a terminal — piped, redirected, < /dev/null, or running in CI, which is the usual reason neither is — or --no-interactive) → a missing required flag is an error. Supply every flag and the command runs unattended.

This means the same command serves a human at a prompt and a script with no changes.

Read commands add one thing on top. In a terminal, several listings offer to open one of the rows they just printed — cdno project list asks which project you want to see, prints it, and asks again until you press Esc. The listing itself is printed first either way, so piping, --no-interactive, and --json all behave exactly as they did before. See Colour and interactivity.

JSON output

--json makes any supported verb emit structured output:

• Read verbs (commitments, questions, status, now, orient, search, open, and the list/show verbs of project/portfolio/stewardship, plus action list) emit their listing or detail object.
• Write verbs (log, capture, file, track, and the create/update verbs of project, action, portfolio, stewardship, question, commit) emit a { "path": ..., "message": ... } result, and run non-interactively (so prompts can’t corrupt the JSON on a terminal). project complete and drop add what was let go, and print a refusal object and exit 1 while items are open (see JSON output).
• migrate emits its report, the plan with --dry-run (see migrate).
• Maintenance / interactive / bootstrap commands (init, lint, reindex, normalise, triage, review, weekly, monthly) ignore --json.

The CLI’s JSON shapes match the MCP server DTOs. See JSON output for every shape.

Naming a note: --slug

Every verb that creates a note derives its filename, the slug, from the title. For a long title the derived slug can stop mid-thought (rerun-the-surrogate-model-ablation-on), and it is what every later [[wikilink]] has to type. The create verbs therefore take an optional --slug <SLUG> to name the file yourself: project create, question create, portfolio create, action add --note, action promote, note create, stewardship create and commit create. The title is unchanged; only the filename is.

An explicit slug must be:

• lowercase a-z, 0-9 and single -, with no - at either end;
• at most 50 characters;
• not something YAML would read as a number, a boolean, a null or a date (2026, yes, null, 2026-11-05): add a word to it.

An explicit slug is used exactly or refused, never rewritten. If another note already holds the name (as its filename, or as the folder of a folder note such as portfolios/surrogate-model/) the create is refused and nothing is written; pick another name. The -2 suffix belongs to derived slugs only. --slug is never prompted for; omit it and the slug derives from the title. In a terminal a refusal reads:

$ cdno project create --title "Surrogate model" --context work --slug surrogate-model
Error: creating project

Caused by:
    slug 'surrogate-model' is taken by 'projects/surrogate-model.md' (as its stem)

Under --json a refusal is a coded object.

A derived slug takes -2 when the name is held, and a folder note’s name counts as held: a question titled “Surrogate model” created beside the portfolio portfolios/surrogate-model/ gets surrogate-model-2, since the bare name would shadow the portfolio’s _index in a [[surrogate-model]] link. This applies to the verbs that disambiguate: project create, question create, action add --note and action promote, note create and commit create. portfolio create and stewardship create keep the raw derived slug (a portfolio’s slug correlates with its question’s) and refuse a collision outright.

cdno action add --project surrogate-model --note --energy deep \
  --title "Rerun the surrogate model ablation on the held-out split with feature set B" \
  --slug feature-set-b-ablation
# -> actions/feature-set-b-ablation.md

Renaming a note after the fact is a separate verb, planned under RFC 0007.

The commands