CLI Reference

The Chaos Cypher CLI (chaoscypher) provides command-line access to all core features -- source management, knowledge graph operations, AI chat, database management, local serving, multi-package composition, and package sharing.

Installation

# Install uv first: https://docs.astral.sh/uv/getting-started/installation/
uv sync --package chaoscypher-cli

Verify the installation:

uv run chaoscypher --version

chaoscypher, version 0.1.0

Help Output

Running chaoscypher --help displays the full list of available commands:

chaoscypher --help
Usage: chaoscypher [OPTIONS] COMMAND [ARGS]...

  Chaos Cypher CLI - Knowledge Graph Platform.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  chat         Chat with AI using your knowledge graph
  completions  Generate shell completion script (bash, zsh, fish)
  compose      Multi-package orchestration and composition
  config       View and manage CLI configuration
  db           Manage databases (create, list, delete, reset)
  graph        Build and manage knowledge graphs
  health       Check system health (LLM, embedding, search, queue, database)
  lexicon      Lexicon Hub - login, search, manage packages
  mcp          Start MCP server for AI assistant integration
  pull         Download a package from Lexicon Hub
  push         Upload a package to Lexicon Hub
  serve        Start the local API server
  setup        Configure LLM provider for extraction and chat
  source       Add, list, search, and manage document sources
  upgrade      Apply pending Alembic migrations (alembic upgrade head)

First-Time Setup

Run the setup wizard to configure your LLM provider:

chaoscypher setup

The wizard guides you through provider selection (Ollama, OpenAI, Anthropic, or Gemini), model configuration, and connection testing. For Ollama users, a VRAM-based preset system automatically selects appropriate models for your GPU.

# Skip the provider prompt
chaoscypher setup --provider ollama

# Ollama with a specific VRAM tier
chaoscypher setup --provider ollama --vram 24

# Non-interactive mode for CI/scripts (auto-detects provider from env vars)
chaoscypher setup --non-interactive

See Configuration for details.

Command Reference

Core Commands

Command	Description
`setup`	Configure LLM provider (Ollama, OpenAI, Anthropic, Gemini)
`chat`	Chat with AI using your knowledge graph (single message or interactive)
`source`	Add, list, search, and manage document sources (includes `source quality`)
`graph`	Build and manage knowledge graphs (nodes, links, templates, workflows, packages)
`db`	Manage databases (create, list, switch, delete, info)
`health`	Check system health -- LLM, embedding, search, queue, and database status
`upgrade`	Apply pending Alembic migrations (`alembic upgrade head`)

Package Management

Command	Description
`lexicon`	Lexicon Hub authentication and package management
`pull`	Download a package from Lexicon Hub (shortcut for `lexicon pull`)
`push`	Upload a package to Lexicon Hub (shortcut for `lexicon push`)

Runtime Commands

Command	Description
`mcp`	Start Model Context Protocol (MCP) server for AI assistant integration
`serve`	Start a local API server
`compose`	Multi-package orchestration using `axiomatize.yaml`

Utility Commands

Command	Description
`config`	View and manage CLI configuration
`completions`	Generate shell completion scripts (bash, zsh, fish)
`diagnostics`	Export a diagnostic bundle for bug reports
`scaffold`	Generate a new Cortex VSA feature skeleton

Shortcuts

For convenience, some commands are available at both the top level and within their group:

Shortcut	Equivalent	Purpose
`chaoscypher pull <pkg>`	`chaoscypher lexicon pull <pkg>`	Download a package
`chaoscypher push <path>`	`chaoscypher lexicon push <path>`	Upload a package

Quality evaluation commands are available under chaoscypher source quality (e.g., chaoscypher source quality score <id>). See the Quality reference for details.

health

Check the health of all system subsystems -- LLM provider, embedding service, search indexes, queue, and database connectivity.

chaoscypher health

Options

Option	Short	Description
`--database DATABASE`	`-d`	Database to check (default: `default`)
`--json`		Output as JSON

Sample Output

chaoscypher health

System Health Check

  LLM          healthy   ollama / qwen3:30b-instruct
  Embedding    healthy   Qwen/Qwen3-Embedding-0.6B
  Search       healthy   1500 docs indexed, 1500 vectors
  Queue        healthy   valkey:6379
  Database     healthy   default

Overall: healthy

JSON Output

chaoscypher health --json

{
  "status": "healthy",
  "checks": {
    "llm": { "status": "healthy", "details": { "provider": "ollama", "model": "qwen3:30b-instruct" } },
    "embedding": { "status": "healthy", "details": { "model": "Qwen/Qwen3-Embedding-0.6B" } },
    "search": { "status": "healthy", "details": { "fulltext_doc_count": 1500, "vector_index_size": 1500 } },
    "queue": { "status": "healthy", "details": { "host": "valkey", "port": 6379 } },
    "database": { "status": "healthy", "details": { "database_name": "default" } }
  }
}

upgrade

Apply pending Alembic migrations against the configured database.

chaoscypher upgrade

This is equivalent to running alembic upgrade head directly. Cortex runs the same command on startup; chaoscypher upgrade is the operator-grade alternative for ad-hoc invocations — for example, after restoring a backup or pulling a new release in a dev environment.

# These are equivalent — pick whichever fits your workflow:
chaoscypher upgrade
# or
uv run alembic upgrade head

A non-zero exit from Alembic propagates as a non-zero exit code from chaoscypher upgrade.

See Upgrading and ADR-0006 for background.

serve

Start a local API server. This launches Cortex backed by your knowledge graph database.

chaoscypher serve

If Cortex is installed, it runs the full Cortex server. Otherwise, a built-in lightweight fallback server provides basic endpoints.

chaoscypher serve
╭──── Server ────╮
│ Chaos Cypher Local Server          │
│                                    │
│ Database: default                  │
│ API URL:  http://localhost:8081    │
│ Data dir: ~/.local/share/chaoscypher/databases/default │
╰────────────────╯

Database Statistics:
  Nodes: 142
  Edges: 387
  Templates: 5

Starting Cortex...
Press Ctrl+C to stop

Option	Description
`--port, -p`	API port (default: `8081`)
`--host, -h`	Host to bind to (default: `localhost`)
`--database, -d`	Database to serve (default: `default`)
`--reload`	Auto-reload on file changes (dev mode)

# Serve on a custom port
chaoscypher serve --port 9000

# Serve a specific database
chaoscypher serve --database my-project

# Enable auto-reload for development
chaoscypher serve --reload

compose

Multi-package orchestration and composition. Combine multiple .ccx packages defined in an axiomatize.yaml configuration file into a unified knowledge system with merged graphs and shared contexts.

chaoscypher compose --help

chaoscypher compose --help
Usage: chaoscypher compose [OPTIONS] COMMAND [ARGS]...

  Multi-package orchestration and composition.

  Compose enables combining multiple .ccx packages defined in
  axiomatize.yaml into a unified knowledge system.

Options:
  --help  Show this message and exit.

Commands:
  build  Build composition package
  down   Stop composition services
  run    Run a one-off command
  up     Start composition services

compose build

Compile an axiomatize.yaml into a runtime database. Resolves all referenced packages (from Lexicon Hub or local), downloads them, and merges them into a unified knowledge database ready for serving.

chaoscypher compose build

Option	Description
`--config, -c`	Path to composition config file (default: `axiomatize.yaml`)
`--clean`	Clean output directory before building

# Build from a custom config file
chaoscypher compose build --config my-compose.yaml

# Clean build (removes previous output first)
chaoscypher compose build --clean

compose up

Start the composition defined in axiomatize.yaml. Builds the database if it does not exist or if --build is specified, then starts a knowledge server from the composed packages.

chaoscypher compose up

Option	Description
`--config, -c`	Path to composition config file (default: `axiomatize.yaml`)
`--port, -p`	API port (overrides config setting)
`--detach, -d`	Run in background
`--build, -b`	Force rebuild before starting

# Start on a custom port
chaoscypher compose up --port 9000

# Start in the background
chaoscypher compose up --detach

# Force rebuild and start
chaoscypher compose up --build

compose down

Stop composition services started by compose up --detach.

chaoscypher compose down

Option	Description
`--config, -c`	Path to composition config file (default: `axiomatize.yaml`)

compose run

Execute a one-off command in the composition context. Sets environment variables for the composed database so scripts and tools can access the merged data.

chaoscypher compose run python script.py

Option	Description
`COMMAND`	Command and arguments to execute (required)
`--config, -c`	Path to composition config file (default: `axiomatize.yaml`)

# Run tests against composed data
chaoscypher compose run pytest tests/

# Run an analysis script with a custom config
chaoscypher compose run --config my-compose.yaml python analyze.py

Global Options

The top-level CLI supports these options:

Flag	Description
`--version`	Show the version and exit
`--help`	Show the help message and exit

Most commands additionally support these output options:

Flag	Description
`--json`	Output as JSON
`--quiet, -q`	Minimal output
`--verbose, -v`	Detailed output
`--database, -d`	Target database (default: `default`)

Shell Completions

Generate tab completions for your shell using the completions command. Supports bash, zsh, and fish.

Auto-install (recommended)

# Bash
chaoscypher completions bash --install

# Zsh
chaoscypher completions zsh --install

# Fish
chaoscypher completions fish --install

The --install flag writes the completion script directly to your shell configuration file (~/.bashrc, ~/.zshrc, or ~/.config/fish/completions/chaoscypher.fish).

Manual installation

Print the completion script to stdout for manual setup:

# Print bash completions
chaoscypher completions bash

# Redirect to a file
chaoscypher completions bash > ~/.bash_completion.d/chaoscypher

Other options

Option	Description
`SHELL`	Shell to generate for: `bash`, `zsh`, or `fish` (required)
`--install`	Install completions to shell config
`--uninstall`	Remove completions from shell config
`--show-install, -i`	Show detailed installation instructions

# View installation instructions without installing
chaoscypher completions zsh --show-install

# Remove previously installed completions
chaoscypher completions bash --uninstall

Configuration

CLI settings are stored in ~/.config/chaoscypher/cli.yaml. See Configuration for details.

Installation​

Help Output​

First-Time Setup​

Command Reference​

Core Commands​

Package Management​

Runtime Commands​

Utility Commands​

Shortcuts​

health​

Options​

Sample Output​

JSON Output​

upgrade​

serve​

compose​

compose build​

compose up​

compose down​

compose run​

Global Options​

Shell Completions​

Auto-install (recommended)​

Manual installation​

Other options​

Configuration​