Complete CLI Reference

Every deciduous command, flag, node type, and configuration option in one place.

Command Overview

Subcommands

Core Commands

deciduous init [OPTIONS]

Initialize deciduous in the current directory. Creates .deciduous/, .claude/commands/, .claude/skills/, CLAUDE.md, and docs/.

Options:
  --opencode    Also create OpenCode integration (AGENTS.md)
  --windsurf    Also create Windsurf integration (.windsurfrules)

deciduous update

Update integration files to the current binary version. Auto-detects installed assistants. Overwrites .claude/commands/, .claude/skills/, .claude/hooks/, .claude/agents.toml, and the deciduous section of CLAUDE.md.

Not touched: .claude/settings.json, .deciduous/config.toml, docs/.

deciduous check-update

Compare .deciduous/.version with current binary version. Exit code 0 if up to date, 1 if update needed.

deciduous add <TYPE> <TITLE> [OPTIONS]

Add a node to the decision graph.

Arguments:
  TYPE     goal | option | decision | action | outcome | observation | revisit
  TITLE    Title of the node (quoted string)

Options:
  -d, --description <TEXT>    Optional description
  -c, --confidence <0-100>    Confidence level
  -p, --prompt <TEXT>         User prompt that triggered this node
  --prompt-stdin              Read prompt from stdin (for multi-line)
  -f, --files <LIST>         Associated files (comma-separated)
  -b, --branch <NAME>        Git branch (default: auto-detected)
  --no-branch                 Skip branch auto-detection
  --commit <HASH|HEAD>       Link to a git commit
  --date <DATE>              Backdate node (YYYY-MM-DD or RFC3339)

Example:

deciduous link <FROM> <TO> [OPTIONS]

Create a directed edge between two nodes.

Arguments:
  FROM    Source node ID (integer)
  TO      Target node ID (integer)

Options:
  -r, --rationale <TEXT>     Reason for the connection
  -t, --edge-type <TYPE>    Edge type (default: leads_to)

deciduous unlink <FROM> <TO>

Remove the edge between two nodes.

deciduous edit <ID> [OPTIONS]

Edit an existing node's title, description, or metadata.

Arguments:
  ID    Node ID to edit

Options:
  --title <TEXT>              New title
  --description <TEXT>        New description
  -c, --confidence <0-100>   New confidence level
  -f, --files <LIST>         New associated files

deciduous delete <ID>

Delete a node and all its edges from the graph.

deciduous status <ID> <STATUS>

Update a node's status.

Arguments:
  ID       Node ID
  STATUS   pending | active | completed | superseded | abandoned | rejected

deciduous prompt <ID> [TEXT]

Set or update the verbatim user prompt on a node. If TEXT is omitted, reads from stdin.

Arguments:
  ID      Node ID
  TEXT    The prompt text (optional; reads stdin if omitted)

Query Commands

deciduous nodes [OPTIONS]

List all nodes with optional filtering.

Options:
  -b, --branch <NAME>       Filter by git branch
  -t, --node-type <TYPE>    Filter by node type
  --status <STATUS>         Filter by status

deciduous edges

List all edges with their types and rationales.

deciduous show <ID> [OPTIONS]

Show detailed information for a single node, including metadata, prompt, and all connected edges.

Arguments:
  ID    Node ID to display

Options:
  --json    Output as JSON

deciduous graph

Export the full graph as JSON to stdout.

deciduous commands

Show the recent deciduous command log.

deciduous pulse

Show a health report: node/edge counts by type, status breakdown, orphan detection, and last activity timestamp.

Export Commands

deciduous sync

Export graph to docs/graph-data.json and docs/git-history.json for static hosting on GitHub Pages.

deciduous dot [OPTIONS]

Export graph as DOT format for Graphviz visualization.

Options:
  -o, --output <FILE>       Output file (default: stdout)
  -r, --roots <IDS>         Root node IDs for BFS traversal (comma-separated)
  -n, --nodes <SPEC>        Specific nodes (e.g., "1-11" or "1,3,5-10")
  -t, --title <TITLE>       Graph title
  --rankdir <DIR>           Graph direction: TB (top-bottom) or LR (left-right)
  --png                     Generate PNG file (requires graphviz)
  --auto                    Branch-specific filenames

deciduous writeup [OPTIONS]

Generate a markdown PR writeup from graph nodes.

Options:
  -t, --title <TITLE>       PR title
  -r, --roots <IDS>         Root node IDs (BFS traversal)
  -n, --nodes <SPEC>        Specific node IDs or ranges
  -o, --output <FILE>       Output file (default: stdout)
  --png <FILENAME>          PNG file to embed
  --auto                    Auto-detect branch-specific PNG
  --no-dot                  Skip DOT graph section
  --no-test-plan            Skip test plan section

deciduous backup

Create a timestamped copy of the database in .deciduous/backups/.

Multi-User Sync Commands

deciduous migrate

Add change_id (UUID) columns to nodes and edges for multi-user sync. One-time operation for databases created before v0.10.

deciduous diff export [OPTIONS]

Options:
  -o, --output <FILE>       Output patch file (required)
  -b, --branch <NAME>       Filter by branch
  -n, --nodes <SPEC>        Specific node IDs or ranges
  --author <NAME>           Author name in the patch

deciduous diff apply [OPTIONS] <FILES...>

Arguments:
  FILES    Patch file(s) to apply (supports glob patterns)

Options:
  --dry-run    Preview changes without applying

deciduous diff status

List patches in .deciduous/patches/ and their apply status.

deciduous events status

Show event-based sync status: author, sync directory, checkpoint info, pending event count.

deciduous events rebuild

Rebuild the local database from event files (after git pull).

deciduous events checkpoint [OPTIONS]

Compact events into a single checkpoint file.

Options:
  --clear-events    Remove event files after checkpointing

Document Commands

deciduous doc attach <NODE_ID> <FILE> [OPTIONS]

Options:
  -d, --description <TEXT>    Description of the document
  --ai-describe               Generate description using AI

deciduous doc list [NODE_ID]

List all documents, or documents attached to a specific node.

deciduous doc show <DOC_ID>

Show detailed information about a document.

deciduous doc describe <DOC_ID> [TEXT]

Options:
  --ai    Generate description using AI

deciduous doc open <DOC_ID>

Open the document in the default application.

deciduous doc detach <DOC_ID>

Soft-delete a document attachment (recoverable).

deciduous doc gc

Garbage collect orphaned document files from .deciduous/documents/.

Narrative & Archaeology Commands

deciduous narratives init

Scaffold .deciduous/narratives.md from active goal node titles.

deciduous narratives show

Display the narratives document.

deciduous narratives pivots

Show pivot chains: outcome → observation → revisit → new decision.

deciduous archaeology pivot <OUTCOME_ID> <REASON>

Create a revisit node from an outcome, linking through an observation.

deciduous archaeology timeline [OPTIONS]

Options:
  --limit <N>               Maximum nodes to display
  --node-type <TYPE>        Filter by node type

deciduous archaeology supersede <OLD_ID> <NEW_ID>

Mark old node as superseded and link to its replacement.

Theme & Tag Commands

deciduous themes create <NAME> [OPTIONS]

Options:
  --color <HEX>              Theme color (e.g., "#3b82f6")
  -d, --description <TEXT>   Theme description

deciduous themes list

List all themes with name, color, and description.

deciduous themes delete <NAME>

Delete a theme and remove all its tag associations.

deciduous tag add <NODE_ID> <THEME>

Tag a node with a theme.

deciduous tag remove <NODE_ID> <THEME>

Remove a theme tag from a node.

deciduous tag list <NODE_ID>

List all themes assigned to a node.

deciduous tag suggest

AI-analyze node titles and suggest theme assignments.

deciduous tag confirm

Apply the most recent AI suggestions from tag suggest.

Hook Commands

deciduous hooks install

Generate and install git pre-commit hook scripts based on .deciduous/config.toml settings.

deciduous hooks status

Show hook installation status, active checks, and branch configuration.

deciduous hooks uninstall

Remove deciduous hooks from .git/hooks/.

Assistant Integration Commands

deciduous opencode install

Install OpenCode integration files (AGENTS.md).

deciduous opencode status

Check OpenCode integration status and version.

deciduous opencode uninstall

Remove OpenCode integration files.

deciduous serve [OPTIONS]

Options:
  -p, --port <PORT>    Port number (default: 3000)

Node Types

The Canonical Flow

goal → option(s) → decision → action(s) → outcome(s)
                                                    ↑
                                              observations attach anywhere
                                              revisits connect old → new

Edge Types

Node Statuses

Metadata Flags

These flags are available on deciduous add and some on deciduous edit:

Configuration

Configuration lives in .deciduous/config.toml:

[branch]
# Branches NOT considered feature branches
main_branches = ["main", "master", "develop"]

# Auto-detect git branch when creating nodes
auto_detect = true

[hooks]
# Require an active goal before committing
require_active_goal = true

# Require recent deciduous activity
require_recent_activity = true
recent_activity_minutes = 30

# Require commit linked to an action node
require_commit_link = false

# Branches where hooks are enforced (empty = all)
enforced_branches = []

# Branches where hooks are skipped
skip_branches = ["main", "master"]

Environment Variables

File Locations