Skip to content

cli-commands.md

Latest commit

 

History

History
519 lines (367 loc) · 14.1 KB

cli-commands.md

File metadata and controls

519 lines (367 loc) · 14.1 KB

CLI Commands Reference

Reference for Causantic command-line interface.

General Syntax

npx causantic <command> [options]

Commands

init

Initialize Causantic with an interactive setup wizard.

npx causantic init [options]

Options:

Option Description
--skip-mcp Skip MCP configuration (settings.json, project .mcp.json, skills, CLAUDE.md)
--skip-encryption Skip the database encryption prompt
--skip-ingest Skip the session import step

The wizard performs the following steps:

  1. Checks Node.js version (requires 20+)
  2. Creates ~/.causantic/ directory structure
  3. Offers database encryption setup (ChaCha20-Poly1305, key stored in system keychain)
  4. Initializes the SQLite database
  5. Configures MCP server in ~/.claude.json
  6. Patches project-level .mcp.json files
  7. Installs Causantic skills to ~/.claude/skills/
  8. Updates ~/.claude/CLAUDE.md with Causantic reference block
  9. Runs a health check
  10. Offers to import existing Claude Code sessions
  11. Runs post-ingestion processing (clustering)
  12. Offers Anthropic API key setup for cluster labeling

Example:

# Full interactive setup
npx causantic init

# Non-interactive (skip all prompts)
npx causantic init --skip-mcp --skip-encryption --skip-ingest

serve

Start the MCP server.

npx causantic serve [options]

Options:

Option Description
--port <port> HTTP port (default: stdio)
--health-check Enable health check endpoint

Example:

npx causantic serve
npx causantic serve --health-check

ingest

Ingest a single session.

npx causantic ingest <session-path> [options]

Arguments:

Argument Description
session-path Path to session JSONL file or project directory

Options:

Option Description
--force Re-ingest even if already processed
--dry-run Show what would be ingested

Example:

npx causantic ingest ~/.claude/projects/my-project/session-123.jsonl
npx causantic ingest ~/.claude/projects/my-project/

batch-ingest

Ingest all sessions from a directory.

npx causantic batch-ingest <directory> [options]

Options:

Option Description
--parallel <n> Number of parallel workers (default: 4)
--force Re-ingest all sessions

Example:

npx causantic batch-ingest ~/.claude/projects
npx causantic batch-ingest ~/.claude/projects --parallel 8

recall

Query memory from the command line.

npx causantic recall <query> [options]

Options:

Option Description
--limit <n> Maximum results (default: 10)
--json Output as JSON

Example:

npx causantic recall "authentication flow"
npx causantic recall "error handling" --limit 5 --json

maintenance

Run maintenance tasks.

npx causantic maintenance <subcommand> [options]

Subcommands:

Subcommand Description
run <task> Run a specific task
run all Run all tasks
status Show task status
daemon Run as background daemon
rebuild-edges Rebuild all edges from ingested session data

Tasks:

Task Description
scan-projects Discover and ingest new sessions
update-clusters Re-run HDBSCAN clustering and refresh labels
cleanup-vectors Remove expired vectors and chunks (TTL + FIFO cap)
vacuum Optimize database

Example:

npx causantic maintenance run cleanup-vectors
npx causantic maintenance run all
npx causantic maintenance status
npx causantic maintenance daemon

config

Manage configuration.

npx causantic config <subcommand> [options]

Subcommands:

Subcommand Description
show Display current configuration
validate Validate configuration files
set-key <name> Store an API key
get-key <name> Retrieve an API key

Example:

npx causantic config show
npx causantic config validate
npx causantic config set-key anthropic
npx causantic config get-key anthropic

encryption

Manage database encryption.

npx causantic encryption <subcommand> [options]

Subcommands:

Subcommand Description
setup Enable encryption and generate a key
status Show encryption status
rotate-key Rotate the encryption key
backup-key [path] Back up the encryption key to a password-protected file
restore-key <path> Restore an encryption key from a backup file
audit [limit] Show recent audit log entries

Example:

# Enable encryption
npx causantic encryption setup

# Check status
npx causantic encryption status

# Rotate key
npx causantic encryption rotate-key

# Back up key
npx causantic encryption backup-key ~/causantic-key-backup.enc

# Restore key
npx causantic encryption restore-key ~/causantic-key-backup.enc

# View last 20 audit entries
npx causantic encryption audit 20

export

Export memory data. Archives are gzip-compressed by default and include vector embeddings for semantic search continuity.

npx causantic export [options]

Options:

Option Description
--output <path> Output file path (default: causantic-backup.causantic)
--no-encrypt Skip encryption
--projects <slugs> Comma-separated project slugs to export
--redact-paths Redact file paths in content
--redact-code Redact code blocks in content
--no-vectors Skip vector embeddings (smaller file, but semantic search won't work after import)

Example:

npx causantic export --output backup.causantic
npx causantic export --output backup.json --no-encrypt
npx causantic export --projects my-project,other-project --no-encrypt --output filtered.json
npx causantic export --redact-paths --redact-code --output sanitized.causantic
npx causantic export --no-vectors --output lightweight.causantic

import

Import memory data. Supports encrypted, compressed, and plain JSON archives.

npx causantic import <file> [options]

Options:

Option Description
--merge Merge with existing data (default: replace)
--dry-run Validate and report without importing

Example:

npx causantic import backup.causantic
npx causantic import backup.causantic --merge
npx causantic import backup.causantic --dry-run

stats

Show memory statistics.

npx causantic stats [options]

Options:

Option Description
--json Output as JSON

Example:

npx causantic stats
npx causantic stats --json

reindex

Re-embed all chunks with the current embedding model. Required after changing embedding.model in configuration.

npx causantic reindex [options]

Options:

Option Description
--batch-size <n> Number of chunks per batch (default: 50)
--dry-run Show what would be re-embedded

Example:

# Re-embed all chunks
npx causantic reindex

# Dry run to see scope
npx causantic reindex --dry-run

# Re-embed in larger batches
npx causantic reindex --batch-size 100

health

Check system health.

npx causantic health

Example:

npx causantic health

hook

Run a hook manually.

npx causantic hook <hook-name> [options]

Hooks:

Hook Description
session-start Session start hook — retrieves memory context
session-end Session end hook — ingests the current session
pre-compact Pre-compaction hook — ingests the current session before compaction
claudemd-generator Update CLAUDE.md with memory context

Example:

npx causantic hook session-start
npx causantic hook claudemd-generator

dashboard

Launch the web dashboard for exploring your memory graph, clusters, and search results.

npx causantic dashboard [options]

Options:

Option Description
--port <port> HTTP port (default: 3333)

Example:

# Launch on default port
npx causantic dashboard

# Launch on custom port
npx causantic dashboard --port 8080

The dashboard provides 5 pages: Overview (collection stats), Timeline (D3.js swimlane visualization with chain walking), Search (query memory), Clusters (browse topic clusters), and Projects (per-project breakdowns).

See Dashboard Guide for details.

benchmark-collection

Run benchmarks against your collection to evaluate health, retrieval quality, graph value, and latency.

npx causantic benchmark-collection [options]

Options:

Option Description
--quick Health only (~1 second)
--standard Health + retrieval (~30 seconds, default)
--full All categories (~2-5 minutes)
--categories <list> Comma-separated: health,retrieval,chain,latency
--sample-size <n> Number of sample queries (default: 50)
--seed <n> Random seed for reproducibility
--project <slug> Limit to one project
--output <path> Output directory (default: ./causantic-benchmark/)
--json Output JSON only (no markdown)
--no-tuning Skip tuning recommendations
--history Show trend from past runs

Example:

# Quick health check
npx causantic benchmark-collection --quick

# Standard benchmark with reproducible sampling
npx causantic benchmark-collection --seed 42

# Full benchmark for a specific project
npx causantic benchmark-collection --full --project my-app

# View historical trends
npx causantic benchmark-collection --history

See Benchmarking Guide for details on interpreting results and acting on recommendations.

uninstall

Remove Causantic and all its artifacts.

npx causantic uninstall [options]

Options:

Option Description
--force Skip confirmation prompt and export offer
--keep-data Remove integrations but preserve ~/.causantic/ data
--dry-run Show what would be removed without making changes

Removes the following artifacts:

  • CLAUDE.md Causantic memory block
  • ~/.claude.json MCP server entry
  • ~/.claude/settings.json legacy MCP server entry (pre-0.5.0)
  • Project .mcp.json Causantic server entries
  • ~/.claude/skills/causantic-*/ skill directories
  • Keychain entries (causantic-db-key, anthropic-api-key)
  • ~/.causantic/ data directory (unless --keep-data)

Example:

# Preview what would be removed
npx causantic uninstall --dry-run

# Remove integrations but keep data
npx causantic uninstall --keep-data

# Remove everything without prompts
npx causantic uninstall --force

# Full uninstall, non-interactive
npx causantic uninstall --force

Global Options

These options work with all commands:

Option Description
--version Show version
--help Show help

Exit Codes

Code Description
0 Success
1 General error
2 Invalid arguments
3 Configuration error
4 Database error