CLI reference

Every verb, every flag — generated from noggin help on the same build of the CLI that's published to npm. If a verb appears here, it works in the binary.

Path syntax

The CLI addresses items by path. Two forms:

• Absolute — starts with /. Walks 1-based positions from the root: /1 is the first root, /1/2 is its second child.
• Relative — everything else, resolved against the active item:
  • . active item
  • .. parent of active
  • - / + previous / next sibling of active
  • ./X, ../X, -/X, +/X descend further from those anchors
  • bare X / X/Y are short for ./X / ./X/Y

Paths are display coordinates: /1/2 might point at "spec the API" today and at "wire up tests" tomorrow after you reorder. That's fine — paths are how you type at the CLI, not how items are tracked. Use them as you'd use line numbers in an editor: convenient for typing, not for long-term storage.

Verbs and flags

Below is the verbatim output of noggin help, generated at build time from the current CLI:

noggin — working-memory tree CLI

An item has: title, done flag, timestamps, and append-only notes.
No fixed schema for content. Anything worth saying goes in a note.

Addressing:
  path   absolute starts with `/` (e.g. "/1/2/3");
         everything else is relative to the active item:
         "." ".." "-" "+" "./X" "../X" "-/X" "+/X" or bare "X/Y" (= "./X/Y")
  tree   "<path> 📍✅ title ✏️" — 📍 active, ✅ done (before title),
         ✏️ has notes (after title)

Verbs:
  push <title>                    child of active, becomes active
  add  <title> [--before|--after|--into <path>] [--goto [path]]
                                  child of active by default; placement flags pick a different spot
  move [<path>] (--before|--after|--into <path>) [--goto [path]]
                                  relocate an item; required placement flag picks the destination
  goto <path>                     make <path> the active item
  done [<path>] [--force|--close-all]
                                  mark done, then make the parent active (idempotent);
                                  --close-all closes any open descendants first;
                                  --force closes the target anyway, leaving kids open
  pop [--force|--close-all]       same as `done` on the active item (no path)
  edit [<path>] [--done|--open] [--title T] [--force|--close-all] [--goto [path]]
                                  edit an item's state and/or title (idempotent);
                                  --done/--open change lifecycle state;
                                  --title T renames the item;
                                  pass at least one of those three
  show [<path>] [--no-children|--with-descendants] [--with-siblings] [--with-all] [--with-notes] [--goto [path]]
                                  current tree view; --with-notes adds note bodies;
                                  --with-siblings includes all sibling rows along the spine;
                                  --with-descendants expands the target subtree recursively;
                                  --with-all = --with-siblings --with-descendants
  note [<path>] <text…> [--goto [path]]
                                  append a timestamped note
  delete <path> [--recursive]     remove an item; --recursive also removes its subtree
  where                           print which noggin would be used and why
  copy <from> <to>                append every item from <from> into <to> (whole-noggin, append-only, fresh keys; notes and timestamps preserved)
  providers                       list registered providers (file://, etc.)
  help

Item creation flags (push/add):
  --title T                       title (alternative to positional)

Common:
  --noggin <location>             override the noggin location (highest priority)
  --goto [path]                   move after command; relative paths resolve from target
  --json                          structured output
  --with-json                     human output followed by structured output

Noggin location (highest first):
  1. --noggin <location>
  2. $NOGGIN env var
  3. ~/.noggin.yaml

Locations may be a bare filesystem path (handled by the file
provider directly) or a URI like `file:///abs/path.yaml` or
`memory://demo`. Run `noggin providers` to see all registered
providers. A URI without a scheme (e.g. just `myfile`) is treated
as a filesystem path.

JSON output

Add --json to any verb to print a structured response envelope to stdout instead of the human view. Errors under --json emit an error envelope to stderr, and the process exits with the envelope's exitCode (1 for runtime errors, 2 for usage errors).

Add --with-json to get human output followed by the JSON envelope — useful for tee'ing into both eyes and downstream tooling.

Choosing a noggin

By default the CLI works against a single noggin per shell — the one resolved by, in priority order:

1. --file <path>
2. $NOGGIN_FILE
3. ~/.noggin.yaml

The flag and env var are currently file-only. The CLI's location-selection design will evolve to support other providers (databases, remote services, embedded fragments); the flag name will broaden along with it. For now, --file works.

Use noggin where to see which noggin the CLI would touch right now (plus whether it currently exists).

See it in action

The verb demo page runs each verb against a seeded tree and shows the resulting human view + JSON envelope side-by-side.