codeintel-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

codeintel CLI 使用指南

codeintel CLI User Guide

codeintel 是 Go 代码库智能索引工具（SSA 字段追溯），输出存 SQLite（

.codeintel/codeintel.db

）。仓库 module：

github.com/schaepher/codeintel

。

codeintel is an intelligent indexing tool for Go codebases (SSA field tracing), with output stored in SQLite (

.codeintel/codeintel.db

). Repository module:

github.com/schaepher/codeintel

构建与安装

Build and Installation

bash

undefined

bash

undefined

在 codeintel 仓库内构建

Build within the codeintel repository

go build -o codeintel ./cmd/codeintel

或安装到 GOBIN

Or install to GOBIN

make install

undefined

make install

undefined

命令速查

Command Quick Reference

bash

codeintel init --repo <path>               # 全量构建索引（须有 go.mod；go.work 根目录会提示进模块目录）
codeintel update --repo <path>             # 增量更新（git 检测变更文件，全量分析+增量写入）
codeintel serve --repo <path> --addr :8096 # 启动图探索 Web 服务（前端 AntV G6，端口默认 :8090）
codeintel query <sub> ... --repo <path>    # 查询（见下；全部子命令支持 --json / --compact）
codeintel export --repo <path> [--out x.json]  # 导出字段双层索引 JSON（字段→产生者/消费者）
codeintel export graph --type value-trace|callees|lifecycle --target <节点> [--format mermaid|dot] [--out file]
                                           # 图导出：value-trace 默认 mermaid（函数分组）、callees 默认 dot、
                                           # lifecycle 生命周期图（[存储]/[观测]/[读]/[写]+条件标注）
codeintel clean --repo <path> --force      # 删除索引（schema 变更后必须 clean + init 重建）
codeintel version

bash

codeintel init --repo <path>               # Full index build (requires go.mod; will prompt to enter module directory at go.work root)
codeintel update --repo <path>             # Incremental update (git detects changed files, full analysis + incremental write)
codeintel serve --repo <path> --addr :8096 # Start graph exploration Web service (frontend AntV G6, default port :8090)
codeintel query <sub> ... --repo <path>    # Query (see below; all subcommands support --json / --compact)
codeintel export --repo <path> [--out x.json]  # Export field double-layer index JSON (field → producer/consumer)
codeintel export graph --type value-trace|callees|lifecycle --target <node> [--format mermaid|dot] [--out file]
                                           # Graph export: value-trace defaults to mermaid (function grouping), callees defaults to dot,
                                           # lifecycle diagram ([storage]/[observation]/[read]/[write] + condition annotations)
codeintel clean --repo <path> --force      # Delete index (must clean + init rebuild after schema changes)
codeintel version

query 子命令

query Subcommands

子命令	用途	关键参数
`symbol <sym>`	符号详情（含调用者/被调用者）
`fields <func>`	函数字段读写摘要（direct_read/write + indirect_write）
`trace-backward <field> --func <func>`	字段产生点反向追溯	`--max-depth N` 默认 8
`trace-forward <field> --func <func>`	字段后续使用正向追踪	`--max-depth N`
`value-trace <nodeID>`	数据值全链（跨函数，函数上下文分组）	`--max-depth N`
`callers/callees <sym>`	调用者/被调用者	`--depth N` 默认 1
`impact <sym>`	影响分析	`--depth N` 默认 3
`summary <节点>`	跨层摘要：入口→计算→写入→消费主链（每步带 file:line）	`--format mermaid`

全部 query 子命令支持
```
--json
```
（结构化输出）与
```
--compact
```
（去缩进）
日志写入
```
.codeintel/codeintel.log
```
（与 db 同目录），stdout 只留查询结果
```
<sym>
```
接受 canonical ID（
```
symbol:go:<pkg>:<name>
```
，方法
```
(T).m
```
）或名称（多匹配时报错列出候选）

<field>

是类型限定路径（如

example.com/app/internal/agent.Config.APIKey

）

<nodeID>

是完整节点 ID（如

symbol:go:...:(Manager).Run#m.cfg.APIKey.read@47

）

Subcommand	Purpose	Key Parameters
`symbol <sym>`	Symbol details (including callers/callees)
`fields <func>`	Function field read-write summary (direct_read/write + indirect_write)
`trace-backward <field> --func <func>`	Reverse trace of field production points	`--max-depth N` default 8
`trace-forward <field> --func <func>`	Forward trace of subsequent field usage	`--max-depth N`
`value-trace <nodeID>`	Full chain of data values (cross-function, grouped by function context)	`--max-depth N`
`callers/callees <sym>`	Callers/callees	`--depth N` default 1
`impact <sym>`	Impact analysis	`--depth N` default 3
`summary <node>`	Cross-layer summary: main chain of entry → compute → write → consume (each step with file:line)	`--format mermaid`

All query subcommands support
```
--json
```
(structured output) and
```
--compact
```
(no indentation)
Logs are written to
```
.codeintel/codeintel.log
```
(same directory as db), only query results are kept in stdout
```
<sym>
```
accepts canonical ID (
```
symbol:go:<pkg>:<name>
```
, method
```
(T).m
```
) or name (reports error and lists candidates if multiple matches)

<field>

is a type-qualified path (e.g.,

example.com/app/internal/agent.Config.APIKey

)

<nodeID>

is a complete node ID (e.g.,

symbol:go:...:(Manager).Run#m.cfg.APIKey.read@47

)

真实示例

Real-world Examples

以下以某 Go 仓库（module

example.com/app

，含 LLM 代理的

m.cfg.APIKey

字段）为例：

bash

undefined

Take a Go repository (module

example.com/app

, with the

m.cfg.APIKey

field of an LLM agent) as an example:

bash

undefined

1. 构建索引（首次或 schema 变更后）

1. Build index (first time or after schema changes)

codeintel init --repo <目标仓库>

codeintel init --repo <target-repo>

2. 函数字段读写摘要（验证后能看到 [direct_read]/[direct_write]/[indirect_write] 分组）

2. Function field read-write summary (after verification, you can see [direct_read]/[direct_write]/[indirect_write] groups)

codeintel query fields "(Manager).Run" --repo <目标仓库>

codeintel query fields "(Manager).Run" --repo <target-repo>

3. 字段使用方正向追踪

3. Forward trace of field users

codeintel query trace-forward example.com/app/internal/agent.Config.APIKey
--func "(Manager).Run" --repo <目标仓库>

codeintel query trace-forward example.com/app/internal/agent.Config.APIKey
--func "(Manager).Run" --repo <target-repo>

4. 数据值全链（跨函数）：先查节点 ID，再追踪

4. Full chain of data values (cross-function): first query node ID, then trace

sqlite3 <目标仓库>/.codeintel/codeintel.db
"SELECT id FROM nodes WHERE kind='field_access' AND json_extract(properties,'$.instance_path')='m.cfg.APIKey' LIMIT 1" codeintel query value-trace "<上面查到的ID>" --repo <目标仓库>

undefined

sqlite3 <target-repo>/.codeintel/codeintel.db
"SELECT id FROM nodes WHERE kind='field_access' AND json_extract(properties,'$.instance_path')='m.cfg.APIKey' LIMIT 1" codeintel query value-trace "<ID obtained above>" --repo <target-repo>

undefined

输出解读

Output Interpretation

fields 摘要：
```
[direct_read]
```
读字段、
```
[direct_write]
```
写字段、
```
[indirect_write]
```
经别名/调用闭包间接写（如
```
m.mu :55 m.mu.Lock()
```
）。摘要表按字段 UNIQUE 去重（同一字段多处访问只列首行），明细在图节点里
value-trace：
```
【函数名】
```
分组 + 缩进树，
```
←
```
产生链（反向）、
```
→
```
使用链（正向），边类型（data_flows_to/argument/returns/phi_operand）、
```
[读]/[写]
```
标记与行号
读链中间层（如
```
m.cfg.APIKey
```
的内层
```
m.cfg
```
）标记为 read 而非 write；
```
[]T{...}
```
字面量初始化不产元素节点
路径条件：追溯行可带
```
[条件: ...]
```
（if/类型分支/env，查询期计算）
动态派发：symbol 接口类型展示候选实现（
```
[register 0.9]
```
/
```
[enum 0.7]
```
+ 注册点）
持久化：SQL 写映射为
```
users.name
```
虚拟节点（字段→表.列，经 value-trace 可见）
全局溯源：全局变量跨函数共享节点（
```
var.<name>
```
），value-trace 可达初始化表达式
跨层摘要：
```
query summary <节点>
```
输出生命周期主链（entry/compute/write/consume）

fields summary:
```
[direct_read]
```
reads fields,
```
[direct_write]
```
writes fields,
```
[indirect_write]
```
writes indirectly via aliases/call closures (e.g.,
```
m.mu :55 m.mu.Lock()
```
). The summary table deduplicates by field UNIQUE (only the first line is listed for multiple accesses to the same field), details are in graph nodes
value-trace: grouped by
```
【function name】
```
+ indented tree,
```
←
```
production chain (reverse),
```
→
```
usage chain (forward), edge types (data_flows_to/argument/returns/phi_operand),
```
[read]/[write]
```
markers and line numbers
Intermediate layers of read chains (e.g., inner layer
```
m.cfg
```
of
```
m.cfg.APIKey
```
) are marked as read instead of write;
```
[]T{...}
```
literal initialization does not generate element nodes
Path conditions: trace lines may include
```
[condition: ...]
```
(if/type branch/env, calculated during query)
Dynamic dispatch: symbol interface types show candidate implementations (
```
[register 0.9]
```
/
```
[enum 0.7]
```
+ registration points)
Persistence: SQL writes are mapped to
```
users.name
```
virtual nodes (field → table.column, visible via value-trace)
Global traceability: global variables share nodes across functions (
```
var.<name>
```
), value-trace can reach initialization expressions
Cross-layer summary:
```
query summary <node>
```
outputs the main lifecycle chain (entry/compute/write/consume)

验证与注意事项

Verification and Notes

改动验证矩阵：
```
make test
```
（单元）、
```
make it
```
（集成，需 scip-go）、
```
make e2e
```
（playwright 22 项，端口 8096，用
```
E2E_REPO=<仓库>
```
指定验证仓库）
schema 无自动迁移（user_version=2）：改 schema 后验证仓库须
```
clean --force
```
+
```
init
```
重建，否则报版本不匹配
每次改完并验证完后要
```
git push
```
（用户约定）
日志：zap + OTel 写入
```
.codeintel/codeintel.log
```
（main 粗解析 --repo 传入 Setup）； --verbose 的 debug 日志也在文件里；stdout 仅查询结果

坑：

pkill -f "codeintel-e2e serve"

会匹配自身命令行自杀（用

pgrep -x codeintel-e2e

+ kill）

索引查询无网络依赖；构建需
```
go
```
与可选的
```
scip-go
```
（缺失时 scip 适配器降级跳过）

Change verification matrix:
```
make test
```
(unit),
```
make it
```
(integration, requires scip-go),
```
make e2e
```
(22 playwright cases, port 8096, specify verification repository with
```
E2E_REPO=<repo>
```
)
No automatic schema migration (user_version=2): after schema changes, verification repositories must run
```
clean --force
```
+
```
init
```
to rebuild, otherwise version mismatch error will occur
Push to git after each modification and verification (user agreement)
Logs: zap + OTel writes to
```
.codeintel/codeintel.log
```
(main rough parsing --repo passed to Setup); debug logs with --verbose are also in the file; stdout only contains query results
Pitfall:
```
pkill -f "codeintel-e2e serve"
```
will match its own command line and kill itself (use
```
pgrep -x codeintel-e2e
```
+ kill)
Index query has no network dependencies; build requires
```
go
```
and optional
```
scip-go
```
(scip adapter degrades and skips if missing)