Utility Commands

This page covers four smaller commands for system health, diagnostics, shell completions, and developer scaffolding.

health

Check that all Chaos Cypher system components are reachable and configured. The health check runs in parallel and reports the status of Ollama, your configured models, embeddings, the search index, and the graph database.

chaoscypher health

Example Output

  Chaos Cypher System Health
  -----------------------------------
  + Ollama          Connected at http://localhost:11434
  + Chat Model      qwen3:30b
  + Extraction      qwen3:30b-instruct
  + Embeddings      qwen3-embedding:0.6b configured
  + Search Index    18,432 docs / 18,432 vectors
  + Database        247 entities / 612 relationships

  All systems healthy.

Status indicators:

Symbol	Meaning
`+` (green)	Component is healthy
`x` (red)	Component has a problem
`!` (yellow)	Warning or not configured

What is checked:

Check	How
Ollama	`GET /api/tags` at the configured URL
Chat Model	Presence in the installed models list from Ollama
Extraction Model	Presence in the installed models list from Ollama
Embeddings	Reads the configured embedding model name from CLI config
Search Index	Full-text document count and vector count from the search repository
Database	Entity count and relationship count from the graph repository

The health command exits with status 0 if all checks pass, or a non-zero status if any check fails.

diagnostics

Export a ZIP bundle containing system information, database statistics, sanitized settings, and any available log files. Attach the bundle to bug reports to provide the development team with the context needed to reproduce and fix issues.

chaoscypher diagnostics [OPTIONS]

Options

Option	Short	Description
`--output PATH`	`-o`	Output path for the ZIP file (default: current directory)

Default Filename

When --output is not specified, the file is named with a UTC timestamp:

chaoscypher-diagnostics-20260413T142356.zip

Examples

Export to the current directory:

chaoscypher diagnostics

  Chaos Cypher Diagnostics
  -----------------------------------
  + Database found: /home/user/.chaoscypher/databases/default/app.db
  + Log directory: 3 log files
  Collecting diagnostics...
  + Bundle saved: chaoscypher-diagnostics-20260413T142356.zip (48 KB)

  Attach this file to your bug report.

Export to a specific path:

chaoscypher diagnostics -o /tmp/debug.zip

Bundle Contents

The ZIP file includes:

System information — OS, Python version, installed package versions
Database statistics — entity counts, edge counts, source counts (no content data)
Sanitized settings — configuration with API keys and passwords redacted
Log files — any .log files found in the CLI data directory

No document content, graph node data, or personal information is included.

completions

Generate and install shell completion scripts for bash, zsh, or fish. Once installed, pressing Tab while typing a chaoscypher command shows available subcommands, options, and arguments.

chaoscypher completions SHELL [OPTIONS]

Arguments

Argument	Choices	Description
`SHELL`	`bash`, `zsh`, `fish`	Shell to generate completions for

Options

Option	Short	Description
`--install`		Install completions to the shell config file automatically
`--uninstall`		Remove completions from the shell config file
`--show-install`	`-i`	Show manual installation instructions

Examples

Auto-install (recommended):

chaoscypher completions bash --install
# Installs to ~/.bashrc, then run: source ~/.bashrc

chaoscypher completions zsh --install
# Installs to ~/.zshrc, then run: source ~/.zshrc

chaoscypher completions fish --install
# Installs to ~/.config/fish/completions/chaoscypher.fish

Print the script to stdout (manual installation):

# Append to your shell config manually
chaoscypher completions bash >> ~/.bashrc

# Or save to a dedicated file
chaoscypher completions zsh > ~/.zfunc/_chaoscypher

Show detailed manual installation instructions:

chaoscypher completions bash --show-install
chaoscypher completions zsh --show-install
chaoscypher completions fish --show-install

Remove previously installed completions:

chaoscypher completions bash --uninstall
chaoscypher completions zsh --uninstall
chaoscypher completions fish --uninstall

Re-running --install

If completions are already installed, --install updates the existing block in place rather than appending a duplicate. It is safe to run multiple times.

scaffold

Generate a new Cortex VSA feature skeleton for backend development. This is a developer tool that creates the full set of boilerplate files (models.py, repository.py, service.py, api.py, __init__.py) for a new vertical slice feature.

The command must be run from inside the Chaos Cypher monorepo. It detects the monorepo root by looking for CLAUDE.md and a packages/ directory.

chaoscypher scaffold FEATURE_NAME [OPTIONS]

Arguments

Argument	Description
`FEATURE_NAME`	Snake-case name for the new feature (e.g., `my_feature`)

Options

Option	Description
`--fields TEXT`	Comma-separated field definitions: `"name:str, count:int, active:bool"`
`--dry-run`	Show what would be created without writing any files

Supported Field Types

str / string, int / integer, float, bool / boolean, text, datetime, date

Examples

Scaffold a minimal feature:

chaoscypher scaffold my_feature

  Created packages/cortex/src/chaoscypher_cortex/features/my_feature/__init__.py
  Created packages/cortex/src/chaoscypher_cortex/features/my_feature/models.py
  Created packages/cortex/src/chaoscypher_cortex/features/my_feature/repository.py
  Created packages/cortex/src/chaoscypher_cortex/features/my_feature/service.py
  Created packages/cortex/src/chaoscypher_cortex/features/my_feature/api.py

Feature 'my_feature' scaffolded.
Next: register the router in packages/cortex/src/chaoscypher_cortex/api/v1/router.py

Scaffold with fields:

chaoscypher scaffold my_feature --fields "name:str, count:int, active:bool"

The field definitions are used to populate the Pydantic models in models.py. Response and create models use the fields as required; update models make all fields optional (field | None = None).

Preview without writing files:

chaoscypher scaffold my_feature --fields "title:str, score:float" --dry-run

Would create: packages/cortex/src/chaoscypher_cortex/features/my_feature/
  __init__.py
  models.py
  repository.py
  service.py
  api.py

Class name: MyFeature
Fields: [('title', 'str'), ('score', 'float')]

Remember to register the router in
packages/cortex/src/chaoscypher_cortex/api/v1/router.py

Generated File Structure

packages/cortex/src/chaoscypher_cortex/features/my_feature/
├── __init__.py       # Barrel exports — exports MyFeatureService
├── models.py         # Pydantic DTOs — MyFeatureResponse, MyFeatureCreate, MyFeatureUpdate
├── repository.py     # Data access — MyFeatureRepository (SQLModel session)
├── service.py        # Business logic — MyFeatureService
└── api.py            # REST endpoints + factory DI — get_my_feature_service()

The factory function in api.py follows the naming convention get_{feature_name}_service() and uses Depends() for session and settings injection.

After scaffolding, register the new router in packages/cortex/src/chaoscypher_cortex/api/v1/router.py and add any required SQLModel entities to the shared database models.

See the Cortex Architecture section for details on the three-layer pattern each generated file follows.

health​

Example Output​

diagnostics​

Options​

Default Filename​

Examples​

Bundle Contents​

completions​

Arguments​

Options​

Examples​

scaffold​

Arguments​

Options​

Supported Field Types​

Examples​

Generated File Structure​

health

Example Output

diagnostics

Options

Default Filename

Examples

Bundle Contents

completions

Arguments

Options

Examples

scaffold

Arguments

Options

Supported Field Types

Examples

Generated File Structure