Coraline CLI Reference

Coraline is invoked as coraline [COMMAND] [OPTIONS] [PATH].

When [PATH] is omitted, the current working directory is used as the project root.

Commands at a Glance

coraline init [PATH]

Initialize Coraline in a project directory. Creates .coraline/ with a SQLite database, default config.toml, and initial memory templates.

When stdin is a TTY and no model decision flag is given, prompts to download the embedding model (~137 MB) after initialization. Decline to skip — all non-embedding tools remain fully functional and you can download later with coraline model download. Use --embed, --no-embed, or --yes to make the decision non-interactively (see below); if the model is already present on disk, init skips the prompt entirely regardless of flags.

If .coraline/ already exists and --index is passed without --force, init skips the overwrite and runs indexing directly on the existing project.

Options:

Examples:

coraline init                    # Initialize current directory
coraline init /path/to/my-app   # Initialize a specific path
coraline init -i                 # Initialize, prompt for model, then index
coraline init -i --no-hooks      # Initialize and index, skip git hooks
coraline init --force            # Wipe and reinitialize existing project
coraline init --embed            # Initialize and download the embedding model, no prompt
coraline init --no-embed         # Initialize, skip the model entirely, no prompt
coraline init --yes              # Initialize non-interactively; auto-downloads the model

Which model is downloaded is controlled by vectors.model in config (default nomic-embed-text-v1.5), not by an init flag — see coraline model below and the [vectors] section in Configuration.

On success, creates:

• .coraline/coraline.db — SQLite knowledge graph
• .coraline/config.toml — Annotated config template
• .coraline/memories/ — Initial memory files
• .coraline/.gitignore — Excludes local data files from git
• .git/hooks/post-commit — Auto-sync hook (unless --no-hooks)

coraline index [PATH]

Perform a full reindex of the project. Parses all matching source files, extracts symbols and edges, resolves cross-file references, and stores results in the knowledge graph.

Options:

Examples:

coraline index                   # Index current directory
coraline index /path/to/project  # Index a specific path
coraline index -f                # Force full re-parse
coraline index -q                # Silent (useful in scripts)

coraline sync [PATH]

Perform an incremental update using git-diff to identify changed files. Faster than a full index for routine updates.

Options:

Examples:

coraline sync                    # Sync current directory
coraline sync -q                 # Silent sync (used by git hook)

coraline status [PATH]

Show the current project status: initialization state, paths to config and database, database size, embedding-model state, and git hook status.

Examples:

coraline status

Sample output:

Coraline Status

Project: /home/user/my-app
Config:  /home/user/my-app/.coraline/config.toml
Database: /home/user/my-app/.coraline/coraline.db (1048576 bytes)
Embeddings: model_quantized.onnx (161 MB)
Model:      jina-embeddings-v2-base-code
Model dir:  /home/user/.config/coraline/models/jina-embeddings-v2-base-code
Git hooks: installed

The Embeddings line shows not present (with a fix hint) when no model file has been downloaded yet for the project’s configured model (vectors.model, default nomic-embed-text-v1.5). See coraline model and coraline doctor below.

For deeper diagnostics (every probe with detail + fix hints, deep model-load / inference / embed-coverage checks, machine-readable JSON), use coraline doctor — it’s the same probe set that the MCP coraline_status tool runs when called with include_doctor: true.

coraline stats [PATH]

Show index statistics: file count, node count, edge count, and unresolved reference count.

Options:

Examples:

coraline stats
coraline stats --json

Sample output:

Coraline Statistics

Files:     128
Nodes:     4201
Edges:     9872
Unresolved refs: 153

coraline query <SEARCH> [PATH]

Search for symbols in the knowledge graph by name. Uses SQLite full-text search (FTS5) for fast, fuzzy matching.

Arguments:

Options:

Valid KIND values: file, module, class, struct, interface, trait, protocol, function, method, property, field, variable, constant, enum, enum_member, type_alias, namespace, parameter, import, export, route, component

Examples:

coraline query resolve_unresolved
coraline query "index" --kind function --limit 5
coraline query Auth --json

coraline context <TASK> [PATH]

Build structured context for an AI task description. Searches the graph, traverses relationships, and returns relevant code snippets.

Arguments:

Options:

Examples:

coraline context "add authentication middleware"
coraline context "how does indexing work" --format json
coraline context "refactor database layer" --max-nodes 30 --max-code 5

coraline callers <NODE_ID> [PATH]

Find all nodes that call the specified node (incoming calls edges).

Arguments:

Options:

Examples:

coraline callers abc123
coraline callers abc123 --limit 50 --json

coraline callees <NODE_ID> [PATH]

Find all nodes that the specified node calls (outgoing calls edges).

Same flags as callers.

coraline impact <NODE_ID> [PATH]

Analyze the impact radius of a symbol — what would be affected if it changed. Performs a BFS over incoming edges up to --depth hops.

Arguments:

Options:

Examples:

coraline impact abc123
coraline impact abc123 --depth 5 --json

coraline config [PATH]

Read or update the project configuration at .coraline/config.toml.

Options:

Examples:

coraline config                                 # Print full config (TOML)
coraline config --section context               # Print one section
coraline config --json                          # Print as JSON
coraline config --set context.max_nodes=30      # Update a value
coraline config --set indexing.batch_size=50
coraline config --set vectors.enabled=true

coraline hooks <ACTION> [PATH]

Manage the git post-commit hook that runs coraline sync automatically after each commit.

Actions:

Options:

Examples:

coraline hooks install
coraline hooks status
coraline hooks remove

coraline doctor [PATH]

Run diagnostic checks against a project and report pass/fail per check, with a fix hint for anything failing. Exits 0 if every check passed, 1 otherwise — safe to use as a CI gate.

Checks (in order):

The three deep checks require a build with the embeddings or embeddings-dynamic feature; they’re skipped (not failed) on builds without it.

Options:

Examples:

coraline doctor                  # Full diagnostic run (deep checks included)
coraline doctor --quick          # Skip slow model checks — good for CI
coraline doctor --json           # Machine-readable report

Sample output:

✔  config
✔  database
✔  git hooks
✘  model file
    → Run `coraline model download`.

Sample --json output:

{
  "probes": [
    {
      "name": "config",
      "ok": true,
      "detail": "/path/.coraline/config.toml (3775 bytes)"
    },
    {
      "name": "database",
      "ok": true,
      "detail": "/path/.coraline/coraline.db (2 nodes, 1 edges, 1 files)"
    },
    { "name": "git hooks", "ok": true, "detail": "installed" },
    {
      "name": "model file",
      "ok": false,
      "detail": "no model file for 'nomic-embed-text-v1.5' in ...",
      "fix": "Run `coraline model download`."
    }
  ],
  "exit_code": 1
}

The same --json shape is exposed by the MCP coraline_status tool when called with include_doctor: true (plus a top-level doctor_needs_attention bool) — see mcp-tools.md for the full MCP tool reference. This means MCP clients don’t need a separate coraline doctor invocation; one round-trip via coraline_status returns both the index stats and the full probe report.

coraline serve [PATH]

Start the MCP server. With --mcp, communicates over stdio using the Model Context Protocol.

Options:

Examples:

coraline serve --mcp
coraline serve --mcp --path /path/to/project

Typically invoked by an MCP client (Claude Desktop, Claude Code, etc.) rather than directly.

Environment Variables

Examples:

CORALINE_LOG=debug coraline index
CORALINE_LOG=coraline=trace coraline serve --mcp

Logs are written to .coraline/logs/coraline.log (daily rotating) and to stderr at the configured level.

coraline embed [PATH]

Generate vector embeddings for all indexed nodes using the local ONNX model. Embeddings enable the coraline_semantic_search MCP tool.

Options:

Examples:

coraline embed                        # Embed using already-downloaded model
coraline embed --download             # Download the configured model then embed
coraline embed --download --variant model_fp16.onnx

Run coraline index first. Uses the model configured by vectors.model (default nomic-embed-text-v1.5), stored in ~/.config/coraline/models/<model>/ — see coraline model list.

coraline model [PATH]

Manage embedding model files. Supports multiple models — run coraline model list to see the registry.

coraline model list

List every embedding model Coraline knows how to download and run, with dimension and description.

coraline model list

coraline model download

Download model files from HuggingFace.

Downloads tokenizer.json, tokenizer_config.json, and the chosen ONNX weights into the shared model directory ~/.config/coraline/models/<model>/.

nomic-embed-text-v1.5 variants (smallest to largest):

jina-embeddings-v2-base-code variants:

coraline model download                                    # download vectors.model's default variant
coraline model download --model jina-embeddings-v2-base-code

coraline model status

Show which model files are present in the model directory for the configured (or --model-selected) model.

coraline model status
coraline model status --model jina-embeddings-v2-base-code