Skip to content

cli-reference.md

Latest commit

 

History

History
430 lines (293 loc) · 13.4 KB

cli-reference.md

File metadata and controls

430 lines (293 loc) · 13.4 KB

CLI Reference

Complete listing of all Codanna H.P.002-COMMANDS and options.

Global Options

Available for all H.P.002-COMMANDS:

  • -c, --H.P.009-CONFIG <CONFIG> - Path to custom settings.toml file
  • --info - Show detailed loading information
  • -h, --help - Print help
  • -V, --version - Print version

Top-Level Commands

Command Description
codanna init Set up .codanna directory with default H.P.009-CONFIGuration
codanna index Build searchable index from codebase
codanna add-dir Add a folder to be indexed
codanna remove-dir Remove a folder from indexed paths
codanna list-dirs List all folders that are being indexed
codanna retrieve Query symbols, relationships, and dependencies
codanna serve Start MCP server
codanna H.P.009-CONFIG Display active settings
codanna mcp-test Test MCP connection
codanna mcp Execute MCP tools directly
codanna benchmark Benchmark parser performance
codanna parse Output AST nodes in JSONL format
codanna plugin Manage Claude Code plugins
codanna documents Index and search document collections
codanna profile Manage workspace profiles and providers

Command Details

codanna init Set up .codanna directory with default H.P.009-CONFIGuration

Options:

  • -f, --force - Force overwrite existing H.P.009-CONFIGuration

codanna index [PATHS...] Build searchable index from codebase

Arguments:

  • [PATHS...] - Paths to files or directories to index (multiple paths allowed)
  • If no paths provided, uses indexed_paths from H.P.009-CONFIGuration (must be H.P.009-CONFIGured via add-dir)

Options:

  • -t, --threads <THREADS> - Number of threads to use (overrides H.P.009-CONFIG)
  • -f, --force - Force re-indexing even if index exists
  • --dry-run - Dry run - show what would be indexed without indexing
  • --max-files <MAX_FILES> - Maximum number of files to index

Examples:

# Index a single directory
codanna index src 

# Index multiple directories at once
codanna index src lib tests 

# Use H.P.009-CONFIGured indexed paths
codanna index

Behavior:

  • Accepts multiple paths for indexing in a single operation
  • When run without arguments, uses folders from indexed_paths H.P.009-CONFIGuration
  • Reuses cached results; prints Index already up to date (no changes detected). when nothing changed
  • Automatically cleans up symbols from removed folders when using H.P.009-CONFIGuration
  • CLI path additions are idempotent: prints Skipping <path> (already covered by <parent>) when a parent directory is already tracked
  • Forced runs (--force) rebuild all H.P.009-CONFIGured roots first, even if you target a nested subdirectory
  • Single-file paths are indexed ad-hoc; the CLI prints Skipping <file> (indexed file is tracked ad-hoc and not stored in settings) to signal they are not added to indexed_paths
  • Backward compatible with single-path usage

codanna add-dir <PATH> Add a folder to indexed paths in settings.toml

Arguments:

  • <PATH> - Path to folder (canonicalized to absolute)

Examples:

codanna add-dir /path/to/project
codanna add-dir src

Behavior:

  • Updates settings.toml (source of truth)
  • Prevents duplicate entries
  • Next command automatically indexes the folder

codanna remove-dir <PATH> Remove a folder from indexed paths in settings.toml

Arguments:

  • <PATH> - Path to folder (must exist in H.P.009-CONFIGuration)

Examples:

codanna remove-dir /path/to/old-project
codanna remove-dir tests

Behavior:

  • Updates settings.toml (source of truth)
  • Next command automatically removes symbols, embeddings, and metadata

codanna list-dirs List H.P.009-CONFIGured indexed directories from settings.toml

Example:

codanna list-dirs

Automatic Sync Mechanism

Every command compares settings.toml (source of truth) with index metadata:

  • New paths in H.P.009-CONFIG → automatically indexed
  • Removed paths → symbols, embeddings, and metadata cleaned

Example:

codanna add-dir examples/typescript
codanna retrieve symbol Button
# ✓ Added 1 new directories (5 files, 127 symbols)

codanna remove-dir examples/typescript
codanna retrieve symbol Button
# ✓ Removed 1 directories from index

Settings.toml can be edited manually - changes detected on next command.

codanna retrieve <SUBCOMMAND> Query indexed symbols, relationships, and dependencies

SubH.P.002-COMMANDS:

Subcommand Description
retrieve symbol Find a symbol (accepts <name> or symbol_id:ID)
retrieve calls Show what functions a given function calls (accepts <name> or symbol_id:ID)
retrieve callers Show what functions call a given function (accepts <name> or symbol_id:ID)
retrieve implementations Show what types implement a given trait (accepts <trait_name> or trait:NAME)
retrieve search Search for symbols using full-text search (accepts query:TEXT with optional kind:, limit:, module:)
retrieve describe Show symbol signature, location, documentation, dependencies, and relationships (accepts <name> or symbol_id:ID)

All retrieve subH.P.002-COMMANDS support:

  • --json - Output in JSON format
  • lang:LANGUAGE - Filter results by language (e.g., lang:rust, lang:typescript)

Using symbol_id:

# By name (may be ambiguous)
codanna retrieve calls process_file

# By ID (always unambiguous)
codanna retrieve calls symbol_id:1883

# Works with: calls, callers, describe

codanna serve Start MCP server with optional HTTP/HTTPS modes

Options:

  • --watch - Enable hot-reload when index changes
  • --watch-interval <WATCH_INTERVAL> - How often to check for index changes (default: 5)
  • --http - Run as HTTP server instead of stdio transport
  • --https - Run as HTTPS server with TLS support
  • --bind <BIND> - Address to bind HTTP/HTTPS server to (default: 127.0.0.1:8080)

codanna H.P.009-CONFIG Display active settings

codanna mcp-test Test MCP connection - verify connectivity and list available tools

codanna mcp <TOOL> [POSITIONAL]... Execute MCP tools directly without spawning server

Arguments:

  • <TOOL> - Tool to call
  • [POSITIONAL]... - Positional arguments (can be simple values or key:value pairs)

Options:

  • --args <ARGS> - Tool arguments as JSON (for backward compatibility and complex cases)
  • --json - Output in JSON format

Available Tools:

Tool Description
find_symbol Find symbol by exact name
search_symbols Full-text search with fuzzy matching
semantic_search_docs Natural language search
semantic_search_with_context Natural language search with relationships
get_calls Functions called by a function (use function_name:<name> or symbol_id:ID)
find_callers Functions that call a function (use function_name:<name> or symbol_id:ID)
analyze_impact Impact radius of symbol changes (use symbol_name:<name> or symbol_id:ID)
get_index_info Index statistics

Tip: For tools that accept symbol identifiers you can use either the plain name (process_file) or a fully qualified symbol_id:1234 reference.

codanna benchmark [LANGUAGE] Benchmark parser performance

Arguments:

  • [LANGUAGE] - Language to benchmark (rust, python, typescript, go, php, c, cpp, all) [default: all]

Options:

  • -f, --file <FILE> - Custom file to benchmark

codanna parse <FILE> Parse file and output AST as JSON Lines

Arguments:

  • <FILE> - File to parse

Options:

  • -o, --output <OUTPUT> - Output file (defaults to stdout)
  • -d, --max-depth <MAX_DEPTH> - Maximum depth to traverse
  • -a, --all-nodes - Include all nodes (by default only named nodes are shown)

codanna documents <SUBCOMMAND> Index Markdown and text documents for semantic search

Full Documentation: See Document Search for detailed usage, chunking strategies, and H.P.009-CONFIGuration.

SubH.P.002-COMMANDS:

Subcommand Description
documents add-collection Add a document collection to settings.toml
documents remove-collection Remove a document collection from settings.toml
documents index Index documents from H.P.009-CONFIGured collections
documents search Search indexed documents using natural language
documents list List all document collections
documents stats Show statistics for a collection

documents add-collection <NAME> <PATH> Add a document collection to settings.toml

Arguments:

  • <NAME> - Collection name
  • <PATH> - Path to directory containing documents

documents remove-collection <NAME> Remove a document collection from settings.toml

Arguments:

  • <NAME> - Collection name to remove

documents index Index documents from all H.P.009-CONFIGured collections

Options:

  • --collection <NAME> - Index only this collection
  • -f, --force - Force re-indexing even if documents haven't changed

documents search <QUERY> Search indexed documents using natural language

Arguments:

  • <QUERY> - Natural language search query

Options:

  • --collection <NAME> - Search only within this collection
  • -l, --limit <LIMIT> - Maximum number of results (default: 5)
  • --json - Output in JSON format

documents list List all H.P.009-CONFIGured document collections

documents stats <NAME> Show statistics for a collection

Arguments:

  • <NAME> - Collection name

codanna plugin <SUBCOMMAND> Manage Claude Code plugins by installing from Git-based marketplaces

Full Documentation: See Plugin System Documentation for detailed usage, creating plugins, and marketplace structure.

SubH.P.002-COMMANDS:

Subcommand Description
plugin add Install a plugin from a marketplace repository
plugin remove Remove an installed plugin and clean up its files
plugin update Update a plugin to a newer version
plugin list List all installed plugins with their versions
plugin verify Verify that a plugin's files match their expected checksums

plugin add <MARKETPLACE> <PLUGIN_NAME> Install a plugin from a marketplace repository

Arguments:

  • <MARKETPLACE> - Marketplace repository URL or local path
  • <PLUGIN_NAME> - Plugin name to install

Options:

  • --ref <REF> - Git reference (branch, tag, or commit SHA)
  • -f, --force - Force installation even if conflicts exist
  • --dry-run - Perform a dry run without making changes

plugin remove <PLUGIN_NAME> Remove an installed plugin and clean up its files

Arguments:

  • <PLUGIN_NAME> - Plugin name to remove

Options:

  • -f, --force - Force removal even if other plugins depend on it
  • --dry-run - Perform a dry run without making changes

plugin update <PLUGIN_NAME> Update a plugin to a newer version

Arguments:

  • <PLUGIN_NAME> - Plugin name to update

Options:

  • --ref <REF> - Update to specific Git reference
  • --dry-run - Perform a dry run without making changes

plugin list List all installed plugins with their versions

plugin verify <PLUGIN_NAME> Verify that a plugin's files match their expected checksums

Arguments:

  • <PLUGIN_NAME> - Plugin name to verify

Getting Help

To get detailed help for any command or subcommand:

# Top-level command help
codanna help <command>
codanna <command> --help

# Subcommand help
codanna help retrieve <subcommand>
codanna retrieve <subcommand> --help
codanna help plugin <subcommand>
codanna plugin <subcommand> --help

Profile System

Profiles package reusable H.P.005-HOOKS, H.P.002-COMMANDS, and H.P.009-CONFIGuration. Providers (git repositories or local folders) distribute profiles and are registered globally while installations live per workspace.

Full Guide: See Profile System Documentation for H.P.006-WORKFLOWS, storage locations, and structure.

Command Description
codanna profile provider add <source> Register provider (GitHub shorthand, git URL, or local path)
codanna profile list [--verbose] [--json] Inspect profiles offered by registered providers
codanna profile install <name> [--force] Install profile into current workspace
codanna profile status [--verbose] Show installed profiles
codanna profile sync [--force] Install profiles based on workspace lockfile
codanna profile update <name> [--force] Update an installed profile to latest
codanna profile verify [<name>] [--all] [--verbose] Verify integrity of installed profiles
codanna profile remove <name> [--verbose] Remove a profile from the workspace

Profiles are cached under ~/.codanna while workspace installs are tracked in .codanna/profiles.lock.json.

Exit Codes

  • 0 - Success
  • 1 - General error
  • 3 - Not found (used by retrieve H.P.002-COMMANDS)

Notes

  • All retrieve H.P.002-COMMANDS support --json flag for structured output
  • MCP tools support both positional and key:value arguments
  • Plugin command manages codanna extensions
  • Profile command manages workspace H.P.009-CONFIGurations and provider registry
  • Use --dry-run with index, plugin add, and plugin remove to preview without making changes
  • Language filtering available in semantic search: lang:rust, lang:typescript, etc.
  • Profiles are stored globally (~/.codanna/providers.json) and installed per workspace (.codanna/profiles.lock.json)