Skip to content

cli-reference.md

Latest commit

 

History

History
274 lines (215 loc) · 13.3 KB

cli-reference.md

File metadata and controls

274 lines (215 loc) · 13.3 KB
Raw

CLI Reference

Global Flags

Flag Description
--namespace <name> Namespace for data isolation (e.g. --namespace backend)
--db-driver <driver> Database driver: sqlite, postgres (default sqlite)
--db-dsn <dsn> Database connection string (default ccg.db; the default local SQLite database auto-migrates only when its schema is missing)
--log-level <level> Log level: debug, info, warn, error (default info)
--log-json Output logs in JSON format
--config <path> Config file path (default: .ccg.yaml in ./ then ~/.config/ccg/)

Namespace

In MSA environments, you can isolate per-service code graphs in a single database.

# Build per service
ccg build ./backend --namespace backend
ccg build ./frontend --namespace frontend

# Search within a specific namespace
ccg search --namespace backend "auth"

# Incremental update with namespace
ccg update ./backend --namespace backend

Commands

Command Description
ccg init Generate default .ccg.yaml in current directory
ccg init --project Generate .ccg.yaml in current directory (explicit)
ccg init --user Generate .ccg.yaml in ~/.config/ccg/ (global)
ccg migrate Run database schema and search index migrations
ccg build [dir] Parse and build code graph
ccg build --exclude <pat> Exclude files/paths (repeatable)
ccg build --no-recursive [dir] Only parse top-level directory
ccg build --fallback-calls Enable best-effort fallback call resolution (strict by default)
ccg update [dir] Incremental sync
ccg update --fallback-calls Enable best-effort fallback call resolution for incremental sync
ccg status Graph statistics
ccg search <query> Full-text search
ccg search --path <prefix> <query> Scoped search by path prefix
ccg docs [--out dir] Generate Markdown documentation and the wiki-index.json compatibility snapshot (prunes stale generator-managed docs by default)
ccg docs --rag-index-dir <dir> Override the legacy-named Wiki index output directory (default .ccg or rag.index_dir)
ccg docs --prune=false Regenerate docs without deleting older generator-managed files
ccg docs --exclude <pat> Exclude files/paths from generated docs (repeatable)
ccg hooks install Install pre-commit git hook
ccg hooks install --lint-strict Install hook that blocks commit on issues
ccg lint [--out dir] 8-category docs lint
ccg lint --strict Exit 1 on issues (for CI/pre-commit)
ccg version Print build version, commit, date

For the default local SQLite database (ccg.db, including ./ccg.db, absolute paths ending in ccg.db, and file: DSNs for that file), runtime commands auto-run migrations only when the schema is missing. Existing SQLite schemas, PostgreSQL, custom SQLite DSNs, and controlled upgrades require an explicit ccg migrate. If you already have a default ccg.db from an older CCG version, treat it as an existing schema and run ccg migrate after upgrading.

Search and Documentation Routing

CCG has two search surfaces with different jobs:

Use case Preferred entrypoint
Natural-language code understanding and module exploration ccg docs, then MCP search_docs, get_doc_content
Exact symbol lookup, callers/callees, imports, bounded graph traversal MCP get_node, query_graph, get_minimal_context
Impact analysis, flow tracing MCP analysis tools such as get_impact_radius, trace_flow
Focused annotation/keyword candidate search ccg search or MCP search

For coding agents, the recommended natural-language path is:

ccg build .
ccg docs --out docs

ccg docs always writes .ccg/wiki-index.json as a ccg-server Wiki compatibility snapshot. The Wiki API prefers the graph database for tree navigation and search, then uses that snapshot only when DB-backed navigation is unavailable. The snapshot is built directly from folders, packages, files, and symbols; it does not depend on community postprocessing. Symbol nodes carry structured annotation details so the browser Wiki can show params, returns, rules, side effects, and other tags even when the symbol itself has no generated Markdown file. Wiki indexes also store hidden annotation search text so Wiki search can match non-intent tags without returning that hidden text in normal tree payloads. The browser Wiki also provides a Graph tab backed by /wiki/api/graph; it reads the namespace's graph nodes and edges directly from the configured database and opens clicked file/symbol nodes through the same document viewer. Then use MCP search_docs to find relevant docs and get_doc_content to read one directly. ccg search remains useful for quick keyword or annotation matches over symbols, but it should not be treated as the primary answering surface for broad natural-language questions.

Database Choice

Use SQLite for local, single-user workflows where the database is a disposable cache for one small or medium repository. Use PostgreSQL when running CCG as a shared MCP or webhook service, when storing multiple namespaces in one server database, or when operational backup/restore matters.

As a rough scale guide, consider PostgreSQL once a namespace reaches about 50k search documents or 100k graph nodes. For 300k+ graph nodes, multiple always-synced repositories, or frequent webhook updates, PostgreSQL is the recommended default. See Operations for deployment profiles and runtime signals.

Build/Update Fallback Policy

--fallback-calls is intentionally off by default. Use it only when strict call resolution is known to under-connect code graphs and you need temporary recall recovery.

  • Use fallback for one-off recovery, language-specific tuning, or migration bootstraps.
  • Keep strict mode (--fallback-calls off) for CI, --strict checks, and production-serving workflows.
  • If fallback is enabled for a long period, monitor fallback_calls share by namespace and rollback to strict when it grows unexpectedly.

Serve

Command Description
ccg serve Start local MCP server over stdio
ccg serve --cache-ttl <dur> TTL for MCP serve session cache (default 5m; use 0 or --no-cache to disable)
ccg serve --no-cache Disable the in-memory MCP serve session cache
ccg serve --otel-endpoint <url> Enable OTLP HTTP trace export to the given full endpoint URL (for example http://collector:4318/v1/traces); when unset, CCG still creates SDK spans locally but does not export them
ccg serve --namespace-root <dir> Root directory for file namespaces (default namespaces)
ccg serve --max-file-bytes <bytes> Maximum bytes allowed per parsed source file (0 disables the limit)
ccg serve --max-total-parsed-bytes <bytes> Maximum total bytes parsed across source files (0 disables the limit)

HTTP MCP and webhook hosting now live in the dedicated ccg-server binary:

Command Description
ccg-server --http-addr 0.0.0.0:9090 Start the self-hosted HTTP server (default 127.0.0.1:8080)
ccg-server --http-bearer-token <token> Require a bearer token for MCP HTTP requests on /mcp when set
ccg-server --otel-endpoint <url> Enable OTLP HTTP trace export
ccg-server --insecure-http Allow non-loopback HTTP binding without a bearer token (testing only)
ccg-server --stateless Stateless session mode (multi-instance deployments)
ccg-server --wiki-dir <dir> Enable the browser Wiki UI at /wiki using a built React dist directory; /wiki/api/* uses the same bearer token as /mcp
ccg-server --namespace-root <dir> Root directory for file namespaces (default namespaces)
ccg-server --allow-repo <pat> Allowed repo patterns for webhook sync (e.g. org/*, org/api:main,develop)
ccg-server --webhook-secret <s> HMAC secret for webhook signature verification (prefer CCG_WEBHOOK_SECRET to avoid argv exposure)
ccg-server --insecure-webhook Allow unsigned webhook requests for local testing only
ccg-server --repo-clone-base-url <url> Canonical base URL used to reconstruct webhook clone targets (repeatable)
ccg-server --repo-root <dir> Root directory for cloned repositories
ccg-server --webhook-workers <n> Number of webhook sync workers (default 4; SQLite webhook deployments default to 1 unless explicitly set)
ccg-server --webhook-max-tracked-repos <n> Maximum repositories tracked by the webhook sync queue (default 1024)
ccg-server --webhook-attempt-timeout <dur> Timeout for one webhook sync attempt, covering clone/pull and graph update (default 15m)
ccg-server --webhook-retry-attempts <n> Maximum webhook sync attempts per queued item (default 3)
ccg-server --webhook-retry-base-delay <dur> Initial webhook retry delay (default 1s)
ccg-server --webhook-retry-max-delay <dur> Maximum webhook retry delay (default 30s)
ccg-server --webhook-fail-on-unreadable Fail webhook sync attempts when source files cannot be read instead of warning and skipping
ccg-server --max-file-bytes <bytes> Maximum bytes allowed per parsed source file (0 disables the limit)
ccg-server --max-total-parsed-bytes <bytes> Maximum total bytes parsed across source files (0 disables the limit)

Webhook-related server flags can also be configured with matching environment variables where supported: CCG_WEBHOOK_SECRET, CCG_WEBHOOK_WORKERS, CCG_WEBHOOK_MAX_TRACKED_REPOS, CCG_WEBHOOK_ATTEMPT_TIMEOUT, CCG_WEBHOOK_RETRY_ATTEMPTS, CCG_WEBHOOK_RETRY_BASE_DELAY, CCG_WEBHOOK_RETRY_MAX_DELAY, and CCG_REPO_ROOT.

CCG_HTTP_BEARER_TOKEN is also supported for --http-bearer-token, and CCG_OTEL_ENDPOINT is supported for --otel-endpoint. This token protects the MCP HTTP endpoint on /mcp; it does not make /health, /ready, /status, or /webhook private by itself.

When --otel-endpoint or CCG_OTEL_ENDPOINT is unset, CCG still creates real OpenTelemetry SDK spans for inbound MCP/webhook requests and internal webhook sync work. Logs emitted from traced contexts include trace_id, span_id, and trace_sampled, which is useful for local debugging even without an exporter.

Config File (.ccg.yaml)

Project-level defaults loaded automatically from the current directory, with a global fallback at ~/.config/ccg/.ccg.yaml.

db:
  driver: sqlite   # sqlite | postgres
  dsn: ccg.db

exclude:
  - vendor
  - ".*\\.pb\\.go$"
  - ".*_test\\.go$"

include_paths:
  - src/
  - lib/

docs:
  out: docs

include_paths

Restricts the build target paths. When set, only paths under the specified directories are parsed.

  • CLI: .ccg.yaml's include_paths is automatically applied during ccg build
  • Webhook: After cloning a repo, .ccg.yaml's include_paths and exclude are auto-loaded to set build scope
  • Incremental build (ccg update): include_paths filter applied when collecting changed files
include_paths:
  - src/backend/
  - src/shared/

exclude

Filters matching files and directories from the build scope. It supports path prefixes, filename globs, full-path globs, and regular expressions.

  • CLI and incremental builds apply exclude while collecting source files.
  • Webhook builds load exclude from the cloned repository's root .ccg.yaml.
exclude:
  - vendor/
  - "*_generated.go"

Regex Patterns

The exclude and rules pattern fields support regular expressions. Patterns containing $, ^, +, {}, |, \., .* are automatically detected as regex:

rules:
  - pattern: "pkg/store/.*"
    category: unannotated
    action: ignore

  - pattern: ".*_generated\\.go::.*"
    category: incomplete
    action: warn

Config Search Order

  1. ./.ccg.yaml (project-local, highest priority)
  2. ~/.config/ccg/.ccg.yaml (global fallback)

Override with ccg --config path/to/config.yaml.

Lint Categories

ccg lint checks 8 categories:

Category Description
orphan Documentation file with no corresponding code
missing Code file with no documentation
stale Documentation not updated after code change
unannotated Function/type without annotation
contradiction Mismatch between code and documentation
dead-ref @see tag pointing to a non-existent target
incomplete Incomplete annotation
drifted Annotation not updated after code change

For lint rule matching, both drifted and drift are accepted for the same category. User-facing reports use drifted, while internal normalization may use drift.

See Lint Guide for the exact per-category rules, overlaps, and implementation-aligned semantics.

Lint Rules

Lint policy lives in .ccg.yaml's rules section — a list of suppression rules:

Field Purpose
pattern Exact qualified name or regular expression to match
category Lint category the rule applies to (e.g. unannotated, orphan)
action ignore to suppress matching findings

action: ignore rules are applied in normal and --strict mode alike; findings they match are filtered from the report and excluded from the strict failure count.