CLI Reference

ContextFS provides a full-featured command-line interface. The main command is contextfs with a short alias ctx.

Commands

contextfs save

Save a memory to the store.

contextfs save CONTENT [OPTIONS]

Option	Description
--type, -t	Memory type: fact, decision, procedural, episodic, code, error, user
--tags	Comma-separated tags
--summary, -s	Brief summary

Examples:

contextfs save "Use React 18 with TypeScript" --type decision --tags frontend,react

contextfs save "Deploy with: docker compose up -d" --type procedural --summary "Deployment command"

contextfs search

Search memories using semantic similarity.

contextfs search QUERY [OPTIONS]

Option	Description
--limit, -n	Maximum results (default: 10)
--type, -t	Filter by memory type

Examples:

contextfs search "how to deploy"
contextfs search "database" --type decision --limit 5

contextfs init

Initialize a repository for ContextFS indexing. Creates a .contextfs/config.yaml marker file that opts the repo into automatic indexing.

contextfs init [PATH] [OPTIONS]

Option	Description
--no-index	Don't run index after init
--auto-index/--no-auto-index	Enable/disable auto-indexing on session start (default: enabled)
--max-commits	Maximum commits to index (default: 100)
--force, -f	Reinitialize even if already initialized
--quiet, -q	Minimal output

Examples:

# Initialize current repo for ContextFS
contextfs init

# Initialize without immediate indexing
contextfs init --no-index

# Initialize with custom settings
contextfs init --max-commits 500 --no-auto-index

# Reinitialize existing repo
contextfs init --force

The config file (.contextfs/config.yaml) controls: - auto_index: Whether SessionStart hooks should auto-index this repo - max_commits: How much commit history to index

contextfs index

Index a repository for semantic code search.

contextfs index [PATH] [OPTIONS]

Option	Description
--force, -f	Force re-index even if already indexed
--incremental/--full	Incremental (default) or full re-index
--background	Run indexing in background subprocess
--quiet, -q	Suppress output
--require-init	Only index if repo has .contextfs/config.yaml (used by hooks)
--mode	Index mode: all, files_only, or commits_only

Examples:

# Index current repo
contextfs index

# Index specific path
contextfs index /path/to/repo

# Force full re-index
contextfs index --force --full

# Background indexing (for hooks)
contextfs index --quiet --background --require-init

contextfs list

List recent memories.

contextfs list [OPTIONS]

Option	Description
--limit, -n	Maximum results (default: 10)
--type, -t	Filter by memory type

contextfs recall

Recall a specific memory by ID.

contextfs recall MEMORY_ID

The ID can be partial (first 8 characters).

contextfs delete

Delete a memory.

contextfs delete MEMORY_ID [OPTIONS]

Option	Description
--yes, -y	Skip confirmation

contextfs sessions

List recent sessions.

contextfs sessions [OPTIONS]

Option	Description
--limit, -n	Maximum results (default: 10)
--tool	Filter by tool (claude-code, gemini, etc.)
--label	Filter by label

contextfs status

Show ContextFS status and statistics.

contextfs status

Displays: - Data directory location - Current namespace - Memory counts by type - Vector store statistics - Active session info

contextfs serve

Start the MCP server.

contextfs serve

Typically not run directly - used by Claude Desktop integration.

contextfs web

Start the web UI server.

contextfs web [OPTIONS]

Option	Description
--host, -h	Host to bind (default: 127.0.0.1)
--port, -p	Port to bind (default: 8000)

contextfs install-claude-desktop

Install/uninstall MCP server for Claude Desktop.

contextfs install-claude-desktop [OPTIONS]

Option	Description
--uninstall	Remove from Claude Desktop

contextfs save-session

Save session for use with hooks.

contextfs save-session [OPTIONS]

Option	Description
--label, -l	Session label
--transcript, -t	Path to transcript JSONL file

contextfs chroma-server

Manage the ChromaDB server for multi-process safe access.

contextfs chroma-server [OPTIONS]

Option	Description
--daemon	Start server in background
--status	Check if server is running
--install	Install as system service (auto-start on boot)
--uninstall	Remove system service
--port	Port to use (default: 8000)
--path	Data directory path

Examples:

# Start ChromaDB server in background
contextfs chroma-server --daemon

# Check server status
contextfs chroma-server --status

# Install as system service (macOS/Linux/Windows)
contextfs chroma-server --install

# Uninstall system service
contextfs chroma-server --uninstall

Why use ChromaDB server mode?

When multiple MCP clients (Claude Code, Claude Desktop) access ChromaDB simultaneously, the embedded mode can cause corruption. Server mode provides: - Safe multi-process access - Auto-recovery from connection issues - Persistent service across reboots (with --install)

Environment Variables

Variable	Description	Default
CONTEXTFS_DATA_DIR	Data storage directory	~/.contextfs
CONTEXTFS_SOURCE_TOOL	Tool identifier	auto-detect
CONTEXTFS_EMBEDDING_MODEL	Embedding model	all-MiniLM-L6-v2
CONTEXTFS_CHROMA_HOST	ChromaDB server host (enables server mode)	-
CONTEXTFS_CHROMA_PORT	ChromaDB server port	8000
CONTEXTFS_EMBEDDING_BACKEND	Embedding backend: auto, fastembed, sentence_transformers	auto

Shell Completion

Install shell completion:

# Bash
contextfs --install-completion bash

# Zsh
contextfs --install-completion zsh

# Fish
contextfs --install-completion fish