Skip to content

DepthFusion CLI Reference

Generated by cli-printing-press v4.11.0 from the DepthFusion REST API (29 endpoints). Compound commands (discovery-audit, graph-inspect, batch-recall) are hand-authored.

Scorecard: A (83%) — 30 commands, full MCP bundle, offline cache, agent-native JSON output.

Requires: REST API running on 127.0.0.1:7300 (see docs/install/vps-gpu-quickstart.md §8).

Install

# Binaries are at:
~/printing-press/library/depthfusion/build/stage/bin/depthfusion-pp-cli
~/printing-press/library/depthfusion/build/stage/bin/depthfusion-pp-mcp

# Add to PATH (add to ~/.zshrc or ~/.bashrc):
export PATH="$HOME/printing-press/library/depthfusion/build/stage/bin:$PATH"

Auth

The MCP HTTP server is fail-closed: every request to /sse and /messages requires a valid Bearer token. Set DEPTHFUSION_MCP_TOKEN on the server and export the same value as DEPTHFUSION_API_KEY in your client environment.

# Set the token on the server side (in ~/.claude/depthfusion.env):
#   DEPTHFUSION_MCP_TOKEN=<your-secret-token>

# On the client — export the matching token:
export DEPTHFUSION_API_KEY="<value-of-DEPTHFUSION_MCP_TOKEN-on-server>"
depthfusion-pp-cli doctor   # confirm auth OK

The bind host is controlled by DEPTHFUSION_MCP_HOST (default 127.0.0.1). Set it to 0.0.0.0 when you need remote access (ensure a firewall rule is in place and DEPTHFUSION_MCP_TOKEN is configured).

Config file: ~/.config/depthfusion-pp-cli/config.toml

base_url = "http://127.0.0.1:7300"

Start DepthFusion REST API

cd ~/projects/depthfusion
DEPTHFUSION_REST_API=true python -m uvicorn depthfusion.api.rest:app \
  --host 127.0.0.1 --port 7300

# Or use the systemd service (recommended — survives reboots):
systemctl --user start depthfusion-rest

Common Workflows

Status and diagnostics

depthfusion-pp-cli status              # service health
depthfusion-pp-cli doctor              # auth + connectivity check
depthfusion-pp-cli tiers               # tier config and corpus size
depthfusion-pp-cli capabilities        # enabled feature flags
depthfusion-pp-cli hnsw                # HNSW vector index state

Recall (primary use case)

# Recall relevant context for a query
depthfusion-pp-cli recall relevant --query "agent-ops architecture decisions" --json

# With limit and threshold
depthfusion-pp-cli recall relevant --query "RLS policy bugs" --limit 10 --threshold 0.8

Session management

depthfusion-pp-cli session seed --project agent-ops --branch main
depthfusion-pp-cli session compress
depthfusion-pp-cli session tags --tags "refactor,auth"
depthfusion-pp-cli cognitive-state     # memory counts + feature flags

Context publishing and retrieval

depthfusion-pp-cli context publish \
  --content "Auth middleware now validates JWT expiry before role check" \
  --tags "auth,security,jwt"

depthfusion-pp-cli context retrieve --tags "auth,security"

Discoveries management

depthfusion-pp-cli discoveries list
depthfusion-pp-cli discoveries confirm-discovery --text "Supabase RLS must use service role for admin queries"
depthfusion-pp-cli discoveries inspect-discovery --filename "/path/to/discovery.md"
depthfusion-pp-cli discoveries pin-discovery --filename "/path/to/discovery.md" --pinned true
depthfusion-pp-cli discoveries prune --older-than-days 30

Graph traversal

depthfusion-pp-cli graph get-status
depthfusion-pp-cli graph traverse --from-node "auth-middleware" --depth 2 --direction both

Knowledge scoring and decisions

depthfusion-pp-cli memories score --memory-id "abc123" --score 0.95
depthfusion-pp-cli decisions --decision "Use HNSW tier for all recall" \
  --rationale "BM25 recall quality improves 40% after 1000 sessions"
depthfusion-pp-cli outcomes --task-id "S-42" --outcome success
depthfusion-pp-cli skills --query "database migration patterns"

Compound Commands

These three commands aggregate across multiple API calls and implement multi-step logic that cannot be generated from the OpenAPI spec alone.

discovery-audit

Lists all discoveries, groups by age, and flags items older than 7 days with potential conflicts against pinned context.

# Basic audit (human-readable table)
depthfusion-pp-cli discovery-audit

# Only discoveries 7+ days old with detected conflicts, as JSON
depthfusion-pp-cli discovery-audit --min-age-days 7 --show-conflicts-only --json

# CI-friendly (pipe to jq)
depthfusion-pp-cli discovery-audit --json | jq '.groups.gt_7d[] | .filename'

Output groups: lt_1d, 1_7d, gt_7d.

graph-inspect

Recalls seed nodes for a query using BM25+fusion-gate recall, then traverses the knowledge graph from each seed. Deduplicates nodes across traversals.

# 2-hop inspect (default depth)
depthfusion-pp-cli graph-inspect --query "Supabase RLS policies"

# Deeper traversal, JSON output
depthfusion-pp-cli graph-inspect --query "authentication architecture" --depth 3 --json

# Agent-friendly (compact JSON envelope)
depthfusion-pp-cli graph-inspect --query "rate limiting" --agent

Output: seed nodes (distance=0) + traversal nodes (distance=1+), sorted by distance then score.

batch-recall

Reads queries from stdin or a file, runs all recalls concurrently, and deduplicates results across queries keeping the highest score per unique chunk.

# From stdin
echo -e "auth architecture\nRLS policies\nrate limiting" | \
  depthfusion-pp-cli batch-recall --json

# From file
depthfusion-pp-cli batch-recall --file queries.txt --concurrency 8 --threshold 0.8

# Pipe into jq to get the top 5 results
depthfusion-pp-cli batch-recall --file queries.txt --json | \
  jq '.results[:5] | .[] | {score, chunk_id, snippet}'

Flags: --file, --concurrency (default 4), --threshold (default 0.7), --json.

MCP Server

The MCP bundle mirrors all 30 commands (29 generated + 3 compound) as agent tools. Use it to expose DepthFusion to any MCP-compatible AI agent (Claude Code, etc.).

# Run the MCP server (stdio transport)
~/printing-press/library/depthfusion/build/stage/bin/depthfusion-pp-mcp

# Register with Claude Code (user scope — available in all projects):
claude mcp add --scope user depthfusion-cli \
  ~/printing-press/library/depthfusion/build/stage/bin/depthfusion-pp-mcp

# Verify:
claude mcp list | grep depthfusion-cli

Or add to .claude/settings.json for project scope:

{
  "mcpServers": {
    "depthfusion-cli": {
      "type": "stdio",
      "command": "/home/gregmorris/printing-press/library/depthfusion/build/stage/bin/depthfusion-pp-mcp"
    }
  }
}

Source Files

File Purpose
infra/depthfusion/openapi-spec.yaml 29-endpoint OpenAPI 3.0 spec (source of truth for generation)
infra/depthfusion/catalog.yaml Local cli-printing-press catalog entry
infra/systemd/depthfusion-rest.service systemd user service for the REST API
~/printing-press/library/depthfusion/ Generated CLI tree
~/printing-press/library/depthfusion/internal/cli/compound_*.go Hand-authored compound commands
src/depthfusion/api/rest.py DepthFusion REST API (29 MCP tool endpoints)