gRPC API Reference

GoCPG exposes a gRPC interface for CPG operations, queries, navigation, lifecycle status, and pattern scanning. The Python client (GrpcTransport in src/services/gocpg/grpc_transport.py) wraps all RPCs into async methods that return the same Pydantic models as the subprocess transport.

Five gRPC services are used: CPGService (parse/update/indexes), QueryService (query/stats/branches/submodules/frontends), PatternService (search/scan/validate), NavigationService (nav_* methods), and LifecycleService (status/freshness/maintenance).

Connection¶

Parameter	Default	Description
`grpc_host`	`localhost`	Server hostname
`grpc_port`	`50051`	Server port
`grpc_api_key`	`None`	Bearer token for `authorization` metadata
`grpc_tls_cert`	`None`	Path to root CA certificate for TLS

Max message size: 64 MB (send and receive). All methods accept an optional timeout parameter (seconds).

Authentication is passed as gRPC metadata: ("authorization", "Bearer <api_key>").

CPG Operations¶

parse¶

Parse source code into a DuckDB CPG database. Server-streaming RPC with progress events.

Parameter	Type	Default	Description
`input_path`	`str`	required	Source directory path
`output_path`	`str`	required	Output DuckDB file path
`language`	`str`	`"c"`	Source language
`workers`	`int \\| None`	`None`	Parallel workers (0 = auto)
`patterns`	`PatternConfig \\| None`	`None`	Include/exclude patterns and test flag
`include_tests`	`bool`	`False`	Include test files
`exclude_patterns`	`list[str] \\| None`	`None`	Glob patterns to exclude
`include_patterns`	`list[str] \\| None`	`None`	Glob patterns to include
`domain_config`	`str \\| None`	`None`	Domain configuration file path
`no_index`	`bool`	`False`	Skip index creation
`timeout`	`int \\| None`	`3600`	RPC timeout (seconds)

Returns: GoCPGParseResult

update¶

Incremental update of an existing CPG database. Server-streaming RPC with progress events.

Parameter	Type	Default	Description
`input_path`	`str`	required	Source directory path
`output_path`	`str`	required	Existing DuckDB file path
`git_refs`	`GitRefConfig \\| None`	`None`	Commit range (overrides individual params)
`from_commit`	`str \\| None`	`None`	Start commit hash
`to_commit`	`str \\| None`	`None`	End commit hash
`language`	`str \\| None`	`None`	Source language
`force`	`bool`	`False`	Force full rebuild
`domain_config`	`str \\| None`	`None`	Domain configuration file path
`timeout`	`int \\| None`	`600`	RPC timeout (seconds)

Returns: GoCPGUpdateResult

ci_update¶

CI-optimized incremental update with base/head ref support. Unary RPC.

Parameter	Type	Default	Description
`input_path`	`str`	required	Source directory path
`output_path`	`str`	required	DuckDB file path
`git_refs`	`GitRefConfig \\| None`	`None`	Commit range (overrides individual params)
`base_ref`	`str`	`"origin/main"`	Base git reference
`head_ref`	`str`	`"HEAD"`	Head git reference
`cache_dir`	`str \\| None`	`None`	Cache directory for intermediate results
`language`	`str \\| None`	`None`	Source language
`timeout`	`int \\| None`	`600`	RPC timeout (seconds)

Returns: GoCPGCIUpdateResult

create_indexes¶

Create or rebuild indexes on a CPG database. Unary RPC.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`300`	RPC timeout (seconds)

Returns: None

Query & Search¶

query¶

Execute a SQL query against a CPG database. Unary RPC.

Parameter	Type	Default	Description
`sql`	`str`	required	SQL query string
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`60`	RPC timeout (seconds)

Returns: GoCPGQueryResult

search¶

Structural code search using tree-sitter patterns. Unary RPC.

Parameter	Type	Default	Description
`pattern`	`str`	required	Search pattern
`language`	`str`	required	Source language
`db_path`	`str \\| None`	`None`	DuckDB file path
`max_results`	`int \\| None`	`None`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`60`	RPC timeout (seconds)

Returns: GoCPGSearchResult

stats¶

Get CPG database statistics. Unary RPC.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`60`	RPC timeout (seconds)

Returns: GoCPGStatsResult

quality_stats¶

Get code quality statistics (complexity hotspots, dead code). Unary RPC.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`top`	`int`	`20`	Number of top entries per category
`timeout`	`int \\| None`	`60`	RPC timeout (seconds)

Returns: GoCPGQualityStatsResult

Lifecycle & Maintenance¶

lifecycle_status¶

Get the current lifecycle snapshot for a database. Maps to LifecycleService.GetDatabaseStatus.

Parameter	Type	Default	Description
`db_path`	`str`	required	Target DuckDB file path
`repo_path`	`str \\| None`	`None`	Repository root used for freshness checks
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: GoCPGLifecycleStatusResult

Fields include state, read_available, active_operation, progress_percent, started_at, last_successful_update_at, last_successful_maintenance_at, lock metadata, and freshness details.

watch_database_status¶

Stream status snapshots for a database. Maps to LifecycleService.WatchDatabaseStatus.

Parameter	Type	Default	Description
`db_path`	`str`	required	Target DuckDB file path
`repo_path`	`str \\| None`	`None`	Repository root used for freshness checks
`max_events`	`int`	`0`	Maximum streamed events (0 = until cancel)
`poll_interval_ms`	`int`	`0`	Poll interval override in milliseconds
`timeout`	`int \\| None`	`60`	RPC timeout (seconds)

Returns: AsyncIterator[GoCPGLifecycleStatusResult]

freshness_status¶

Get the freshness-only projection for a database. Maps to LifecycleService.GetFreshnessStatus.

Parameter	Type	Default	Description
`db_path`	`str`	required	Target DuckDB file path
`repo_path`	`str \\| None`	`None`	Repository root used for freshness checks
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: GoCPGFreshnessStatusResult

run_maintenance¶

Run explicit DuckDB maintenance inside GoCPG. Maps to LifecycleService.RunMaintenance.

Parameter	Type	Default	Description
`db_path`	`str`	required	Target DuckDB file path
`mode`	`str`	required	`checkpoint_vacuum` or `copy_from_database_rewrite`
`timeout`	`int \\| None`	`300`	RPC timeout (seconds)

Returns: GoCPGMaintenanceResult

maintenance_plan¶

Get the current maintenance recommendation for a database. Maps to LifecycleService.GetMaintenancePlan.

Parameter	Type	Default	Description
`db_path`	`str`	required	Target DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: GoCPGMaintenancePlanResult

nav_symbols¶

Find symbols by name in the CPG. Supports exact and prefix matching.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Symbol name to search
`prefix`	`bool`	`False`	Enable prefix matching
`node_type`	`str`	`""`	Filter by node type
`file`	`str`	`""`	Filter by file path
`visibility`	`str`	`""`	Filter by visibility
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavSymbolResult]

nav_callers¶

Find callers of a method, with optional transitive depth.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Method name
`depth`	`int`	`0`	Transitive call depth (0 = direct only)
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavCallerResult]

nav_callees¶

Find callees of a method, with optional transitive depth.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Method name
`depth`	`int`	`0`	Transitive call depth (0 = direct only)
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavCalleeResult]

nav_hierarchy¶

Traverse type inheritance hierarchy (supertypes/subtypes).

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Type name
`direction`	`str`	`""`	`"up"` (supertypes), `"down"` (subtypes), or `""` (both)
`depth`	`int`	`0`	Traversal depth (0 = unlimited)
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavHierarchyNode]

nav_outline¶

Get the symbol outline of a file (functions, classes, methods).

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`file`	`str`	required	File path within the project
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavOutlineEntry]

nav_usages¶

Find all usages (references) of a symbol.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Symbol name
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavUsageResult]

nav_deps¶

Get file-level dependencies (imports/includes).

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`file`	`str`	required	File path within the project
`direction`	`str`	`""`	`"in"` (dependents), `"out"` (dependencies), or `""` (both)
`limit`	`int`	`0`	Maximum results (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavDepResult]

nav_resolve¶

Resolve a symbol name to its fully-qualified name chain.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`name`	`str`	required	Symbol name to resolve
`signature`	`str`	`""`	Method signature for disambiguation
`file`	`str`	`""`	File hint for disambiguation
`limit`	`int`	`0`	Maximum resolution steps (0 = unlimited)
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[NavResolveStep]

Branch Management¶

list_frontends¶

List available language frontends on the server.

Parameter	Type	Default	Description
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[GoCPGFrontendInfo]

list_branches¶

List CPG branches in a database.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[GoCPGBranchInfo]

switch_branch¶

Switch the active CPG branch in a database.

Parameter	Type	Default	Description
`branch_name`	`str`	required	Target branch name
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: None

prune_branches¶

Remove branches from the database that no longer exist in the git repository.

Parameter	Type	Default	Description
`input_path`	`str`	required	Source repository path
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: int (number of pruned branches)

list_submodules¶

List submodules tracked in a CPG database.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: list[GoCPGSubmoduleInfo]

prune_submodules¶

Remove submodule data that is no longer present in the repository.

Parameter	Type	Default	Description
`input_path`	`str`	required	Source repository path
`db_path`	`str`	required	DuckDB file path
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: int (number of pruned submodules)

Pattern Engine¶

scan¶

Run pattern rules against a CPG database. Server-streaming RPC with finding events.

Parameter	Type	Default	Description
`db_path`	`str`	required	DuckDB file path
`config`	`ScanConfig \\| None`	`None`	Scan configuration (overrides individual params)
`rule_dirs`	`list[str] \\| None`	`None`	Directories with YAML rule files
`rule_id`	`str \\| None`	`None`	Run a single rule by ID
`severity_filter`	`str \\| None`	`None`	Filter by severity level
`incremental`	`bool`	`False`	Incremental scan (changed files only)
`fix`	`bool`	`False`	Apply autofix suggestions
`dry_run`	`bool`	`False`	Show fixes without applying
`output_format`	`str \\| None`	`None`	Output format
`output_path`	`str \\| None`	`None`	Output file path
`domain_rules`	`bool`	`False`	Include domain-specific rules
`timeout`	`int \\| None`	`300`	RPC timeout (seconds)

Returns: GoCPGScanResult

validate_rule¶

Validate a YAML pattern rule file, optionally against test code. Unary RPC.

Parameter	Type	Default	Description
`rule_path`	`str`	required	Path to YAML rule file
`test_code`	`str \\| None`	`None`	Test code snippet
`test_lang`	`str \\| None`	`None`	Language of test code
`timeout`	`int \\| None`	`30`	RPC timeout (seconds)

Returns: dict[str, Any]

Transport Notes¶

GrpcTransport.check_health() is a client-side connectivity helper, not a public gRPC RPC. It uses ListFrontends as a lightweight probe and therefore is intentionally excluded from the RPC surface tracked by docs-sync.