Skip to content

Latest commit

 

History

History
580 lines (416 loc) · 20.3 KB

cli.md

File metadata and controls

580 lines (416 loc) · 20.3 KB

CLI reference

Every command runs on the project given by --root (default: the current folder), written before the command name: cg --root ~/code/shop impact cancel_order. cg COMMAND --help prints the same text.

Values in Default apply when the option is left out. The JSON answers of the main commands are described in Formats.

Start here

start

Start here: index the project and show what to ask it, with ready commands.

cg [--root ROOT] start [-h] [--json] [--lang {en,it}]
Argument Meaning Default Values
--json print the machine-readable JSON answer
--lang LANG language of the guide (default: from the environment) en, it

locate

From the text of a request to the places to change, their callers and tests; no model calls.

cg [--root ROOT] locate [-h] [--limit LIMIT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--json] text
Argument Meaning Default Values
text the request, issue or stack trace, as text
--limit LIMIT candidate places to return, 1-10 5
--max-chars MAX_CHARS budget for the whole answer in characters, 512-16000 5000
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--json print the machine-readable JSON answer

search

Find the code for a request: full-text BM25 over names, paths, signatures and bodies, fused with the call graph.

cg [--root ROOT] search [-h] [--mode {hybrid,lexical}] [--limit LIMIT] [--depth {1,2,3}] [--min-conf {high,medium,low}] [--max-chars MAX_CHARS] [--json] query
Argument Meaning Default Values
query words to search; word roots and synonyms widen it when exact words miss
--mode MODE hybrid (text and graph, default) or lexical (text only) hybrid hybrid, lexical
--limit LIMIT results to return 10
--depth DEPTH graph steps from the best text matches, 1-3 2 1–3
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--max-chars MAX_CHARS budget for the whole answer in characters 9000
--json print the machine-readable JSON answer

impact

What breaks if this changes: callers up to a depth, each with its callsite, and the tests reached.

cg [--root ROOT] impact [-h] [--file] [--depth DEPTH] [--min-conf {high,medium,low}] [--limit LIMIT] [--json] target
Argument Meaning Default Values
target symbol, or a file path with --file
--file TARGET is a file: impact of every definition in it
--depth DEPTH caller levels to follow 3
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--limit LIMIT callers to show 40
--json print the machine-readable JSON answer

verify

Tests that reach a function or file, proposed and never run.

cg [--root ROOT] verify [-h] [--file] [--plan] [--min-conf {high,medium,low}] [--depth {1,2,3,4,5}] [--json] target
Argument Meaning Default Values
target symbol, or a file path with --file
--file TARGET is a file
--plan accepted for compatibility; verify always proposes tests and never runs them
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--depth DEPTH caller levels to follow 3 1–5
--json print the machine-readable JSON answer

review

What a change touched: signatures, calls and findings compared with a base, plus a test plan.

cg [--root ROOT] review [-h] [--base BASE] [--staged] [--baseline BASELINE] [--save-baseline SAVE_BASELINE] [--force] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--depth {1,2,3,4,5}] [--json] [--summary]
Argument Meaning Default Values
--base BASE Git revision to compare with, e.g. HEAD or main
--staged review only staged changes
--baseline BASELINE compare findings with a baseline file saved earlier
--save-baseline SAVE_BASELINE save the current findings to this file
--force overwrite the file given to --save-baseline
--max-chars MAX_CHARS budget for the whole answer in characters 20000
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--depth DEPTH caller levels for the test plan 3 1–5
--json print the machine-readable JSON answer
--summary with --json: a compact answer (base, counts, new findings, tests with commands, limits); text output is already a summary

Explore

find

Find definitions by name; * matches any characters.

cg [--root ROOT] find [-h] [--kind KIND] [--limit LIMIT] pattern
Argument Meaning Default Values
pattern name or qualified name, e.g. cancel_* or Order.cancel
--kind KIND only this kind: function, method, class, ...
--limit LIMIT results to show 40

show

One definition: file, lines, signature, callers and callees.

cg [--root ROOT] show [-h] symbol
Argument Meaning Default Values
symbol name or qualified name

callers

Direct callers of a function, each with its callsite.

cg [--root ROOT] callers [-h] [--min-conf {high,medium,low}] symbol
Argument Meaning Default Values
symbol name or qualified name
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low low high, medium, low

callees

Functions a function calls directly.

cg [--root ROOT] callees [-h] [--min-conf {high,medium,low}] symbol
Argument Meaning Default Values
symbol name or qualified name
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low low high, medium, low

path

Shortest call path from one function to another.

cg [--root ROOT] path [-h] [--min-conf {high,medium,low}] src dst
Argument Meaning Default Values
src calling function
dst called function
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low low high, medium, low

context

Source of a function with the callers, callees and tests an agent needs, within a budget.

cg [--root ROOT] context [-h] [--budget BUDGET] [--max-chars MAX_CHARS] [--json] [--profile {understand,change,debug,review}] [--line LINE] [--min-conf {high,medium,low}] symbol
Argument Meaning Default Values
symbol name or qualified name
--budget BUDGET budget in tokens (about 4 characters each) 2500
--max-chars MAX_CHARS budget in characters; overrides --budget
--json print the machine-readable JSON answer
--profile PROFILE what the context is for: understand, change, debug or review change understand, change, debug, review
--line LINE pick the definition that contains this line when the name is ambiguous
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low

source

A window of source around a line and Unicode column, checked against the index.

cg [--root ROOT] source [-h] [--line LINE] [--column COLUMN] [--max-chars MAX_CHARS] [--json] path
Argument Meaning Default Values
path file path inside the project
--line LINE line number 1
--column COLUMN Unicode column on that line 0
--max-chars MAX_CHARS characters of source to return 1200
--json print the machine-readable JSON answer

map

Modules of the project: size, dependencies between them and the most-called functions.

cg [--root ROOT] map [-h] [--depth DEPTH] [--limit LIMIT] [--min-conf {high,medium,low}] [--scope {all,production,tests}] [--json]
Argument Meaning Default Values
--depth DEPTH directory levels that make a module 2
--limit LIMIT modules, dependencies and hotspots to show 25
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--scope SCOPE all files, production only or tests only all all, production, tests
--json print the machine-readable JSON answer

flows

Functional map: declared purposes, their code references and witnessed direct links; technical candidates are separate.

cg [--root ROOT] flows [-h] [--limit LIMIT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--json] [query]
Argument Meaning Default Values
query (optional) words in the declared purpose or technical candidate name ``
--limit LIMIT declared nodes to return, 1-100 25
--max-chars MAX_CHARS budget for the whole JSON answer including its newline, 512-16000 12000
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--json accepted for compatibility; flows always returns structured JSON

architecture

Observations on the project structure and the resources it declares.

cg [--root ROOT] architecture [-h] [--json]
Argument Meaning Default Values
--json print the machine-readable JSON answer

features

Feature cards: groups of related code with their entry points.

cg [--root ROOT] features [-h] [--query QUERY] [--json]
Argument Meaning Default Values
--query QUERY only features matching these words ``
--json print the machine-readable JSON answer

prepare

Evidence package for changing a feature: places, impact and tests, within a budget.

cg [--root ROOT] prepare [-h] [--symbol SYMBOL] [--verify-symbol VERIFY_SYMBOL] [--intent INTENT] [--max-chars MAX_CHARS] [--min-conf {high,medium,low}] [--depth {1,2,3}] [--json] [feature]
Argument Meaning Default Values
feature (optional) feature name from features
--symbol SYMBOL start from this symbol instead of a feature
--verify-symbol VERIFY_SYMBOL also plan tests for this symbol (repeatable)
--intent INTENT what the change should do, in words ``
--max-chars MAX_CHARS budget for the whole answer in characters 12000
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low medium high, medium, low
--depth DEPTH caller levels to follow 2 1–3
--json print the machine-readable JSON answer

explore

Open the local dashboard in the browser.

cg [--root ROOT] explore [-h] [--workspace WORKSPACE] [--port PORT] [--no-open]
Argument Meaning Default Values
--workspace WORKSPACE folder the dashboard may choose projects from ~
--port PORT local port; 0 picks a free one 0
--no-open print the URL without opening the browser

export

Write an offline interactive HTML page of the call graph.

cg [--root ROOT] export [-h] [--output OUTPUT] [--symbol SYMBOL] [--depth {1,2,3,4,5}] [--min-conf {high,medium,low}] [--max-nodes MAX_NODES] [--max-edges MAX_EDGES] [--force]
Argument Meaning Default Values
--output OUTPUT .html path inside the root (default: .code-graph/explore.html) .code-graph/explore.html
--symbol SYMBOL export only the neighbourhood of this symbol
--depth DEPTH steps around --symbol 2 1–5
--min-conf MIN_CONF lowest edge confidence to follow: high, medium or low low high, medium, low
--max-nodes MAX_NODES stop above this many nodes 5000
--max-edges MAX_EDGES stop above this many edges 50000
--force replace an existing HTML file

Index and maintenance

index

Build or refresh the index (only files whose content changed are re-parsed).

cg [--root ROOT] index [-h] [--full]
Argument Meaning Default Values
--full rebuild every file instead of only the changed ones

stats

Size of the index: files, lines, definitions, calls and edges by confidence.

cg [--root ROOT] stats [-h] [--json]
Argument Meaning Default Values
--json print the machine-readable JSON answer

check

Static candidates for defects: wrong argument counts, missing methods, call cycles between files, PHP name clashes.

cg [--root ROOT] check [-h] [--limit LIMIT] [--json] [--include-diagnostics]
Argument Meaning Default Values
--limit LIMIT findings to show 60
--json print the machine-readable JSON answer
--include-diagnostics also list parser and analysis diagnostics

dead

Definitions nothing calls in the graph, with a verdict on how sure that is.

cg [--root ROOT] dead [-h] [--all] [--limit LIMIT]
Argument Meaning Default Values
--all also show ambiguous and unverified candidates
--limit LIMIT candidates to show 60

catalog

API catalog: check (what the index uses that the catalog does not know) or validate.

cg [--root ROOT] catalog [-h] [--json] [--limit LIMIT] {check,validate}
Argument Meaning Default Values
catalog_command check or validate check, validate
--json print the machine-readable JSON answer
--limit LIMIT entries to show 40

selftest

Run the built-in parser and call-resolution checks.

cg [--root ROOT] selftest [-h]

No options.

Agents

mcp

MCP server on stdio for Codex, Claude Code and other clients (read-only tools).

cg [--root ROOT] mcp [-h]

No options.

change

Guided change with agents: plan, approval, isolated edit, tests and a review by the other model.

cg [--root ROOT] change [-h] ACTION ...
Action What it does
new open a change from an intent; nothing runs yet
list changes in this project and their state
show state, plan, tests and review of a change
plan ask the author for a plan grounded in the graph
approve approve the plan and the exact test command; the tests run once now as the baseline
edit let the author edit in its isolated worktree
verify re-index, run the approved tests on the edit, compare with the baseline and review the diff statically
review ask the reviewer to read the diff
integrate bring the reviewed change into its branch, or merge it with --merge
discard drop a change that is not integrated: its worktree and branch are removed, the archive is kept
cancel stop the step that is running

change new

Open a change from an intent; nothing runs yet.

cg [--root ROOT] change new [-h] --intent INTENT --author {codex,claude} --reviewer {codex,claude} [--allow-dirty] [--budget-usd BUDGET_USD]
Argument Meaning Default Values
--intent INTENT what the change should do, in words required
--author AUTHOR model that plans and edits required codex, claude
--reviewer REVIEWER model that reviews; normally the other one required codex, claude
--allow-dirty start although the checkout has uncommitted changes
--budget-usd BUDGET_USD spending cap passed to Claude when it is the author or reviewer

change list

Changes in this project and their state.

cg [--root ROOT] change list [-h]

No options.

change show

State, plan, tests and review of a change.

cg [--root ROOT] change show [-h] id
Argument Meaning Default Values
id change id, as printed by new and list

change plan

Ask the author for a plan grounded in the graph.

cg [--root ROOT] change plan [-h] [--yes] id
Argument Meaning Default Values
id change id, as printed by new and list
--yes Confirm starting the agent and sending context to its provider

change approve

Approve the plan and the exact test command; the tests run once now as the baseline.

cg [--root ROOT] change approve [-h] --test-argv TEST_ARGV [--no-tests-reason NO_TESTS_REASON] id
Argument Meaning Default Values
id change id, as printed by new and list
--test-argv TEST_ARGV test command as a JSON list of arguments, never a shell string required
--no-tests-reason NO_TESTS_REASON why an empty test command is acceptable

change edit

Let the author edit in its isolated worktree.

cg [--root ROOT] change edit [-h] [--yes] [--feedback FEEDBACK] id
Argument Meaning Default Values
id change id, as printed by new and list
--yes Confirm starting the agent and sending context to its provider
--feedback FEEDBACK what to change in a new edit round

change verify

Re-index, run the approved tests on the edit, compare with the baseline and review the diff statically.

cg [--root ROOT] change verify [-h] id
Argument Meaning Default Values
id change id, as printed by new and list

change review

Ask the reviewer to read the diff.

cg [--root ROOT] change review [-h] [--yes] [--same-client-reason SAME_CLIENT_REASON] id
Argument Meaning Default Values
id change id, as printed by new and list
--yes Confirm starting the agent and sending context to its provider
--same-client-reason SAME_CLIENT_REASON why the reviewer may be the same model as the author

change integrate

Bring the reviewed change into its branch, or merge it with --merge.

cg [--root ROOT] change integrate [-h] [--merge] [--force-reason FORCE_REASON] id
Argument Meaning Default Values
id change id, as printed by new and list
--merge merge into the base branch instead of leaving a branch
--force-reason FORCE_REASON why to integrate although the review or the tests block it

change discard

Drop a change that is not integrated: its worktree and branch are removed, the archive is kept.

cg [--root ROOT] change discard [-h] id
Argument Meaning Default Values
id change id, as printed by new and list

change cancel

Stop the step that is running.

cg [--root ROOT] change cancel [-h] id
Argument Meaning Default Values
id change id, as printed by new and list