CLI Reference

ctx CLI¶

This is a complete reference for all ctx commands.

Global Options¶

All commands support these flags:

The NO_COLOR=1 environment variable also disables colored output.

Commands¶

ctx init¶

Initialize a new .context/ directory with template files.

ctx init [flags]

Flags:

Creates:

• .context/ directory with all template files
• .claude/settings.local.json with pre-approved ctx permissions
• PROMPT.md with session prompt (autonomous mode with --ralph)
• IMPLEMENTATION_PLAN.md with high-level project direction
• CLAUDE.md with bootstrap instructions (or merges into existing)

Claude Code hooks and skills are provided by the ctx plugin (see Integrations).

Example:

# Collaborative mode (agent asks questions when unclear)
ctx init

# Autonomous mode (agent works independently)
ctx init --ralph

# Minimal setup (just core files)
ctx init --minimal

# Force overwrite existing
ctx init --force

# Merge into existing files
ctx init --merge

ctx status¶

Show the current context summary.

ctx status [flags]

Flags:

Output:

• Context directory path
• Total files and token estimate
• Status of each file (loaded, empty, missing)
• Recent activity (modification times)
• Drift warnings if any

Example:

ctx status
ctx status --json
ctx status --verbose

ctx agent¶

Print an AI-ready context packet optimized for LLM consumption.

ctx agent [flags]

Flags:

Output:

• Read order for context files
• Constitution rules (never truncated)
• Current tasks
• Key conventions
• Recent decisions

Example:

# Default (8000 tokens, markdown)
ctx agent

# Custom budget
ctx agent --budget 4000

# JSON format
ctx agent --format json

# With cooldown (outputs once, then silent for 10m)
ctx agent --budget 4000 --session $PPID

Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.

ctx load¶

Load and display assembled context as AI would see it.

ctx load [flags]

Flags:

Example:

ctx load
ctx load --budget 16000
ctx load --raw

ctx add¶

Add a new item to a context file.

ctx add <type> <content> [flags]

Types:

Flags:

Examples:

# Add a task
ctx add task "Implement user authentication"
ctx add task "Fix login bug" --priority high

# Record a decision (requires all ADR—Architectural Decision Record—fields)
ctx add decision "Use PostgreSQL for primary database" \
  --context "Need a reliable database for production" \
  --rationale "PostgreSQL offers ACID compliance and JSON support" \
  --consequences "Team needs PostgreSQL training"

# Note a learning (requires context, lesson, and application)
ctx add learning "Vitest mocks must be hoisted" \
  --context "Tests failed with undefined mock errors" \
  --lesson "Vitest hoists vi.mock() calls to top of file" \
  --application "Always place vi.mock() before imports in test files"

# Add to specific section
ctx add convention "Use kebab-case for filenames" --section "Naming"

ctx complete¶

Mark a task as completed.

ctx complete <task-id-or-text>

Arguments:

• task-id-or-text: Task number or partial text match

Examples:

# By text (partial match)
ctx complete "user auth"

# By task number
ctx complete 3

ctx drift¶

Detect stale or invalid context.

ctx drift [flags]

Flags:

Checks:

• Path references in ARCHITECTURE.md and CONVENTIONS.md exist
• Task references are valid
• Constitution rules aren't violated (heuristic)
• Staleness indicators (old files, many completed tasks)

Example:

ctx drift
ctx drift --json
ctx drift --fix

Exit codes:

ctx sync¶

Reconcile context with the current codebase state.

ctx sync [flags]

Flags:

What it does:

• Scans codebase for structural changes
• Compares with ARCHITECTURE.md
• Suggests documenting dependencies if package files exist
• Identifies stale or outdated context

Example:

ctx sync
ctx sync --dry-run

ctx compact¶

Consolidate and clean up context files.

• Moves completed tasks older than 7 days to the archive
• Deduplicates the "learning"s with similar content
• Removes empty sections

ctx compact [flags]

Flags:

Example:

ctx compact
ctx compact --archive

ctx completion¶

Generate shell autocompletion scripts.

ctx completion <shell>

Subcommands¶

Installation¶

# Add to ~/.bashrc
source <(ctx completion bash)

# Add to ~/.zshrc
source <(ctx completion zsh)

ctx completion fish | source
# Or save to completions directory
ctx completion fish > ~/.config/fish/completions/ctx.fish

ctx tasks¶

Manage task archival and snapshots.

ctx tasks <subcommand>

ctx tasks archive¶

Move completed tasks from TASKS.md to a timestamped archive file.

ctx tasks archive [flags]

Flags:

Archive files are stored in .context/archive/ with timestamped names (tasks-YYYY-MM-DD.md). Completed tasks (marked with [x]) are moved; pending tasks ([ ]) remain in TASKS.md.

Example:

ctx tasks archive
ctx tasks archive --dry-run

ctx tasks snapshot¶

Create a point-in-time snapshot of TASKS.md without modifying the original.

ctx tasks snapshot [name]

Arguments:

• name: Optional name for the snapshot (defaults to "snapshot")

Snapshots are stored in .context/archive/ with timestamped names (tasks-<name>-YYYY-MM-DD-HHMM.md).

Example:

ctx tasks snapshot
ctx tasks snapshot "before-refactor"

ctx permissions¶

Manage Claude Code permission snapshots.

ctx permissions <subcommand>

ctx permissions snapshot¶

Save .claude/settings.local.json as the golden image.

ctx permissions snapshot

Creates .claude/settings.golden.json as a byte-for-byte copy of the current settings. Overwrites if the golden file already exists.

The golden file is meant to be committed to version control and shared with the team.

Example:

ctx permissions snapshot
# Saved golden image: .claude/settings.golden.json

ctx permissions restore¶

Replace settings.local.json with the golden image.

ctx permissions restore

Prints a diff of dropped (session-accumulated) and restored permissions. No-op if the files already match.

Example:

ctx permissions restore
# Dropped 3 session permission(s):
#   - Bash(cat /tmp/debug.log:*)
#   - Bash(rm /tmp/test-*:*)
#   - Bash(curl https://example.com:*)
# Restored from golden image.

ctx decisions¶

Manage the DECISIONS.md file.

ctx decisions <subcommand>

ctx decisions reindex¶

Regenerate the quick-reference index at the top of DECISIONS.md.

ctx decisions reindex

The index is a compact table showing the date and title for each decision, allowing AI tools to quickly scan entries without reading the full file.

Use this after manual edits to DECISIONS.md or when migrating existing files to use the index format.

Example:

ctx decisions reindex
# ✓ Index regenerated with 12 entries

ctx learnings¶

Manage the LEARNINGS.md file.

ctx learnings <subcommand>

ctx learnings reindex¶

Regenerate the quick-reference index at the top of LEARNINGS.md.

ctx learnings reindex

The index is a compact table showing the date and title for each learning, allowing AI tools to quickly scan entries without reading the full file.

Use this after manual edits to LEARNINGS.md or when migrating existing files to use the index format.

Example:

ctx learnings reindex
# ✓ Index regenerated with 8 entries

ctx recall¶

Browse and search AI session history from Claude Code and other tools.

ctx recall <subcommand>

ctx recall list¶

List all parsed sessions.

ctx recall list [flags]

Flags:

Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.

Example:

ctx recall list
ctx recall list --limit 5
ctx recall list --project ctx
ctx recall list --tool claude-code

ctx recall show¶

Show details of a specific session.

ctx recall show [session-id] [flags]

Flags:

The session ID can be a full UUID, partial match, or session slug name.

Example:

ctx recall show abc123
ctx recall show gleaming-wobbling-sutherland
ctx recall show --latest
ctx recall show --latest --full

ctx recall export¶

Export sessions to editable journal files in .context/journal/.

ctx recall export [session-id] [flags]

Flags:

Exported files include session metadata, tool usage summary, and the full conversation. When re-exporting, YAML frontmatter from enrichment (topics, type, outcome, etc.) is preserved by default; only the conversation content is regenerated.

The journal/ directory should be gitignored (like sessions/) since it contains raw conversation data.

Example:

ctx recall export abc123                # Export one session
ctx recall export --all                 # Export/update all sessions
ctx recall export --all --skip-existing # Skip files that already exist
ctx recall export --all --force         # Overwrite completely (lose frontmatter)

ctx journal¶

Analyze and synthesize exported session files.

ctx journal <subcommand>

ctx journal site¶

Generate a static site from journal entries in .context/journal/.

ctx journal site [flags]

Flags:

Creates a zensical-compatible site structure with an index page listing all sessions by date, and individual pages for each journal entry.

Requires zensical to be installed for --build or --serve:

pipx install zensical

Example:

ctx journal site                    # Generate in .context/journal-site/
ctx journal site --output ~/public  # Custom output directory
ctx journal site --build            # Generate and build HTML
ctx journal site --serve            # Generate and serve locally

ctx journal obsidian¶

Generate an Obsidian vault from journal entries in .context/journal/.

ctx journal obsidian [flags]

Flags:

Creates an Obsidian-compatible vault with:

• Wikilinks ([[target|display]]) for all internal navigation
• MOC pages (Map of Content) for topics, key files, and session types
• Related sessions footer linking entries that share topics
• Transformed frontmatter (topics → tags for Obsidian integration)
• Minimal .obsidian/ config enforcing wikilink mode

No external dependencies are required: Open the output directory as an Obsidian vault directly.

Example:

ctx journal obsidian                          # Generate in .context/journal-obsidian/
ctx journal obsidian --output ~/vaults/ctx    # Custom output directory

ctx serve¶

Serve a static site locally via zensical.

ctx serve [directory]

If no directory is specified, serves the journal site (.context/journal-site).

Requires zensical to be installed:

pipx install zensical

Example:

ctx serve                           # Serve journal site
ctx serve .context/journal-site     # Serve specific directory
ctx serve ./docs                    # Serve docs folder

ctx watch¶

Watch for AI output and auto-apply context updates.

Parses <context-update> XML commands from AI output and applies them to context files.

ctx watch [flags]

Flags:

Example:

# Watch stdin
ai-tool | ctx watch

# Watch a log file
ctx watch --log /path/to/ai-output.log

# Preview without applying
ctx watch --dry-run

ctx hook¶

Generate AI tool integration configuration.

ctx hook <tool>

Supported tools:

Example:

ctx hook cursor
ctx hook aider

ctx loop¶

Generate a shell script for running an autonomous loop.

An autonomous loop continuously runs an AI assistant with the same prompt until a completion signal is detected, enabling iterative development where the AI builds on its previous work.

ctx loop [flags]

Flags:

Example:

# Generate loop.sh for Claude Code
ctx loop

# Generate for Aider with custom prompt
ctx loop --tool aider --prompt TASKS.md

# Limit to 10 iterations
ctx loop --max-iterations 10

# Output to custom file
ctx loop -o my-loop.sh

Usage:

# Generate and run the loop
ctx loop
chmod +x loop.sh
./loop.sh

See Autonomous Loops for detailed workflow documentation.

ctx pad¶

Encrypted scratchpad for sensitive one-liners that travel with the project.

When invoked without a subcommand, lists all entries.

ctx pad
ctx pad <subcommand>

ctx pad add¶

Append a new entry to the scratchpad.

ctx pad add <text>

Example:

ctx pad add "DATABASE_URL=postgres://user:pass@host/db"

ctx pad show¶

Output the raw text of an entry by number.

ctx pad show <n>

Arguments:

• n: 1-based entry number

Example:

ctx pad show 3

ctx pad rm¶

Remove an entry by number.

ctx pad rm <n>

Arguments:

• n: 1-based entry number

ctx pad edit¶

Replace, append to, or prepend to an entry.

ctx pad edit <n> [text]

Arguments:

• n: 1-based entry number
• text: Replacement text (mutually exclusive with --append/--prepend)

Flags:

Example:

ctx pad edit 2 "new text"
ctx pad edit 2 --append " suffix"
ctx pad edit 2 --prepend "prefix "

ctx pad mv¶

Move an entry from one position to another.

ctx pad mv <from> <to>

Arguments:

• from: Source position (1-based)
• to: Destination position (1-based)

ctx pad resolve¶

Show both sides of a merge conflict in the encrypted scratchpad.

ctx pad resolve

Exit Codes¶

Environment Variables¶

Configuration File¶

Optional .contextrc (YAML format) at project root:

# .contextrc
context_dir: .context    # Context directory name
token_budget: 8000       # Default token budget
priority_order:          # File loading priority
  - TASKS.md
  - DECISIONS.md
  - CONVENTIONS.md
auto_archive: true       # Auto-archive old items
archive_after_days: 7    # Days before archiving
scratchpad_encrypt: true # Encrypt scratchpad (default: true)
allow_outside_cwd: false # Skip boundary check (default: false)

Priority order: CLI flags > Environment variables > .contextrc > Defaults

All settings are optional. Missing values use defaults.