CLI reference¶

Codefang ships two binaries: codefang, the analyzer engine, and uast, the Universal Abstract Syntax Tree parser. This page is the exhaustive reference for every command, sub-command, and flag. Every flag listed by codefang run --help is documented here and is read by the pipeline; a flag that is accepted but has no effect is a bug.

codefang¶

The main analysis binary. It runs static and history analyzers against source code and Git repositories.

Global flags¶

Global flags are accepted before or after the subcommand (codefang -q run … ≡ codefang run -q …).

codefang run¶

The primary entry point. Runs selected static and/or history analyzers on a codebase or repository.

codefang run [path] [flags]

If path is omitted the current directory (or the value of --path) is used.

Analyzer selection¶

Analyzer IDs follow a <category>/<name> convention. Globs are supported:

# Single analyzer
codefang run -a static/complexity .

# All static analyzers
codefang run -a 'static/*' .

# All history analyzers
codefang run -a 'history/*' .

# Multiple specific analyzers
codefang run -a static/complexity,history/burndown,history/devs .

# Everything
codefang run -a '*' .

Output flags¶

Which formats a selection accepts:

text is supported by the six history analyzers with a text renderer (sentiment, shotness, burndown, couples, devs, file-history); selecting any other history analyzer with --format text fails with serialization error for <Name>: unsupported format: text.

# Human-readable table
codefang run -a 'static/*' --format text .

# One summary line per history analyzer
codefang run -a 'history/*' --format compact .

# Interactive HTML charts
codefang run -a 'history/*' --format plot --output ./report .

# The report in a file instead of stdout
codefang run -a static/complexity --format json -o complexity.json .

# Unified time-series JSON
codefang run -a 'history/devs,history/sentiment' --format timeseries .

{
  "version": "codefang.run.v1",
  "metadata": { "...": "run provenance" },
  "analyzers": [
    { "id": "history/devs", "mode": "history", "report": { "...": "the devs report" } },
    { "id": "history/burndown", "mode": "history", "report": { "...": "the burndown report" } }
  ]
}

Path flags¶

Git history flags¶

These flags bound the history phase only — static analyzers read the working tree, so none of them affects a static run.

The window is selected newest-first (--limit 10 = the ten most recent commits, like git log -n 10) and then handed to the analyzers in chronological oldest-first order, because ticks, burndown line survival and author identity all depend on that order. --limit and --since compose: --since picks the window, --limit caps its newest end. --head is the single-commit window [HEAD] — the same window --limit 1 selects, so the two produce byte-identical reports for every analyzer and format.

The --since flag accepts these forms, in precedence order:

• Duration: 24h, 168h (one week), 1h30m — units are h/m/s only. There is no d or w unit and m means minutes, so a week is 168h, not 7d
• Date: 2025-01-01 (midnight UTC)
• RFC 3339: 2025-01-01T00:00:00Z
• Git revision: v1.2.0, HEAD~100, or a bare SHA — that commit's author time becomes the cutoff

The cutoff compares the commit's author time, and every commit authored at/after it is kept regardless of its position in the committer-time walk (a commit authored after the cutoff but committed before it is still included; one authored before the cutoff but committed after it is not).

# Everything authored in the last 168h (one week)
codefang run -a history/devs --since 168h .

# Since a specific date
codefang run -a history/burndown --since 2025-01-01 .

# Since a release tag
codefang run -a history/couples --since v1.2.0 .

# Only the latest 500 commits
codefang run -a history/couples --limit 500 .

# Hourly ticks
codefang run -a history/devs --tick-size 1 --format timeseries .

Language filtering¶

History phase — each changed file is classified with the full enry cascade over its basename and its blob content, so ambiguous extensions (.h, .m, .pl, .r) and extensionless scripts (shebang) resolve correctly; changes whose language is not in the set are dropped before any analyzer sees them.

Static phase — the filter is applied by the ONE directory walk every static analyzer shares, before the UAST parser or raw-file analyzers see the file: the language globs are matched against the basename, so the parser's own language router remains the final authority for how a matched file is parsed. Both phases read the same langpath tables, so the flag value has one meaning across -a 'static/*', -a 'history/*', and -a '*' runs.

The static walk¶

Every static/* analyzer reads the same walk of the path you pass (a directory or a single file):

• directories are visited in lexical order, depth-first; .git and any directory carrying a CACHEDIR.TAG (Cargo's target/) are skipped; symlinked directories are never followed (a symlink loop cannot recurse and the walk cannot leave the root); symlinks to regular files are read;
• a file is admitted when the UAST parser supports its extension, its basename matches --languages, and its root-relative path passes the vendor / generated / --extra-excluded-prefixes policy;
• each admitted file is read once; a file larger than the parse size limit (--max-parse-file-size, default 8 MiB) or one that cannot be read is skipped with one stderr line (warning: skipped <path>: larger than the parse size limit (--max-parse-file-size) / : unreadable) for the whole run, however many analyzers are selected, and counted once in the end-of-run progress: skipped N unreadable/oversized/unparseable files line;
• a data file is not parsed by the function analyzers (static/complexity, static/halstead, static/cohesion, static/clones) or by the import analyzer (static/imports) when enry types it as data (Linguist's data type) and its UAST mapping cannot produce the nodes those analyzers look for (a function, or an import). The file is still reported, with zero results. Both checks are needed: SQL and GraphQL are data-typed but declare functions, and Protocol Buffers declare imports, so they are parsed. static/comments always parses, because comments in YAML, TOML, and INI files are counted;
• the generated-content marker (DO NOT EDIT, Code generated, @generated, … in the first 512 bytes) is applied to the bytes just read unless --include-generated;
• a single-file path analyzes that one file and stamps its name (a.go, never .) on every per-file entry and issue location.

static/composition is the designed exception: it exists to report vendored / generated / binary shares, so it classifies every regular file the walk reaches (reading only the first 8 KiB of each); only --languages and --extra-excluded-prefixes narrow it.

Language names are Linguist keys and common aliases resolve automatically:

# Canonical names (any case, whitespace is trimmed)
codefang run -a 'history/devs' --languages go,python,typescript .

# Aliases resolve via the Linguist tables
codefang run -a 'history/devs' --languages golang,js,ts .

# Unknown language fails fast instead of silently returning an empty report:
codefang run -a 'history/devs' --languages notalang .
# → Error: history --languages: unknown language: "notalang"
codefang run -a 'static/complexity' --languages notalang .
# → Error: static --languages: unknown language: "notalang"

Filename-only languages (e.g. Dockerfile, Makefile) are also supported:

codefang run -a 'history/devs' --languages dockerfile .

Vendor & generated exclusion¶

By default, Codefang excludes vendored dependencies and auto-generated files from analysis. This matches the convention of every major single-language analyser (go vet, eslint, ruff, rubocop, scalafix, phpcs, …) — vendor/generated code is noise for a code-quality report.

All three flags apply identically to both static and history phases: the history change filter reads the blob header for the generated-file marker exactly as the static walk reads the bytes of each admitted file.

# default: your own code only
codefang run -a '*' .

# include vendored deps (node_modules/, vendor/, …)
codefang run -a '*' --include-vendored .

# include everything
codefang run -a '*' --include-vendored --include-generated .

# skip extras the heuristics do not know about (e.g. Python venv, Rust target/)
codefang run -a '*' --extra-excluded-prefixes '.venv/,target/' .

Developer identity¶

By default an author is identified by either the lowercased email or the lowercased name, and a hit on one token registers the other: alice <a@x>, Alice Smith <a@x> and Alice Smith <a@y> are one developer. One identity detector serves every history analyzer, so devs, burndown, couples, file-history and anomaly agree on author ids.

# people.txt
Alice|alice@example.com|alice@other.org
Bob|bob@example.com

codefang run -a history/devs --people-dict people.txt .
codefang run -a history/devs --anonymize --format text .

Analyzer options¶

Configuration¶

Every key of the file — and its CODEFANG_* environment variable — sets the default of one flag; the precedence is explicit flag > environment

config file > compiled default. --config /dev/null runs with the compiled defaults only. Keys nothing reads are ignored with one warning: ignoring unsupported config keys: … line. See Configuration for the key → flag table.

codefang run -a history/anomaly --config ./ci.codefang.yaml .

No checkpoint store, incremental cache or trace exporter is linked into the binary, so the Go-era --checkpoint, --checkpoint-dir, --resume, --clear-checkpoint, --cache-dir, --no-cache and --debug-trace flags are removed; passing one fails as an unknown argument. A run always analyzes the whole requested window — bound it with --limit / --since.

Errors¶

Every user error prints Error: <message> to stderr, leaves stdout empty and exits 1:

A history --format text selection that includes an analyzer without a text renderer writes the header and the section name first, then fails with serialization error for <Name>: unsupported format: text.

codefang version¶

Prints codefang <version> (commit: <hash>, built: <date>):

• <version> — the crate version (or CF_VERSION / GIT_VERSION set at build time);
• <hash> — the commit the binary was built from: CF_COMMIT / GIT_COMMIT / GIT_HASH set at build time, else the HEAD of the checkout it was built in, else unknown;
• <date> — CF_DATE / SOURCE_DATE_EPOCH set at build time, else unknown (the build never reads the wall clock).

codefang version

The former codefang render <store-dir> subcommand only ever printed "not available" — there is no stored-report format to render from — and is removed; codefang run --format plot -o <dir> writes the HTML pages directly.

codefang completion <shell>¶

Generates the shell-completion script for bash, fish, powershell or zsh on stdout, from the live command tree (every flag on this page). --no-descriptions leaves the help texts out of the script.

codefang completion bash > ~/.local/share/bash-completion/completions/codefang

codefang mcp¶

Serves the Model Context Protocol over stdio (newline-delimited JSON-RPC) until the client closes stdin. It takes no flags and exposes three tools AI agents discover with tools/list and invoke with tools/call:

Each tool result is the report the CLI renders for the same input. See the MCP Integration guide for the tool reference.

uast¶

The UAST binary parses source files into a Universal Abstract Syntax Tree and provides querying, diffing, and exploration utilities. The root command has no flags of its own; every flag below belongs to its subcommand and is read by it (uast <command> --help lists the same set).

uast parse¶

Parse one or more source files into UAST format.

uast parse [files...] [flags]

With no files (and no --all), or for a - file argument, the source is read from stdin and parsed as Go unless -l names the language. With -o, every input's document is written to the one file, in input order.

# Parse a single file
uast parse main.go

# Parse all Go files, one compact document per line
uast parse -f compact *.go

# Force language detection
uast parse -l go main.c

# Read from stdin
cat main.go | uast parse -

# Save to file
uast parse -o output.json main.go

# Parse entire codebase
uast parse --all

uast query¶

Query UAST nodes using the functional DSL.

uast query <expression> [files...] [flags]

With neither files nor --input, or for a - file argument, the query runs over a UAST JSON tree read from stdin.

# Find the top-level functions (filter looks at the file's direct children)
uast query "filter(.type == 'Function')" main.go

# Find every function-role node anywhere in the tree, methods included
uast query 'rfilter(.roles has "Function")' main.go

# The name of every declaration in the tree
uast query "rmap(.props.name)" main.go

# Find exported items
uast query "filter(.roles has 'Exported')" *.go

# Count all nodes
uast query "reduce(count)" main.go

# Query from piped UAST JSON
uast parse main.go | uast query "filter(.type == 'Call')" -

# The same query over an --input file
uast query "filter(.type == 'Call')" -i main.go

# Count format
uast query -f count "filter(.type == 'Function')" main.go

# Interactive mode
uast query -t main.go

uast diff¶

Compare two files at the UAST structural level and report changes.

uast diff <file1> <file2> [flags]

# Unified diff output (default)
uast diff old.go new.go

# Summary of change types
uast diff -f summary old.go new.go

# Machine-readable JSON
uast diff -f json old.go new.go

# Save to file
uast diff -o changes.json -f json old.go new.go

uast explore¶

Start an interactive session for exploring the UAST structure of a file.

uast explore [file] [flags]

uast explore main.go

Available interactive commands:

uast analyze¶

Quick analysis shortcut that parses and analyzes source files in one step.

uast analyze [files...] [flags]

# Analyze a single file
uast analyze main.go

# Analyze all Go files as JSON
uast analyze -f json *.go

# Generate an HTML report
uast analyze -o report.html -f html *.go

uast validate¶

Validate a UAST JSON document against the UAST JSON Schema. Exit codes: 0 valid, 1 the document violates the schema, 2 an error (unreadable input, malformed JSON, unreadable schema).

uast validate <file.json|-> [flags]

# Validate a parsed tree against the embedded schema
uast parse -o tree.json main.go
uast validate tree.json

uast mapping¶

Grammar helpers for UAST mapping authors: summarize and classify a tree-sitter node-types.json, generate a .uastmap DSL skeleton from it, or dump the raw tree-sitter tree of source files.

uast mapping [files...] [flags]

# Classify a grammar's node types
uast mapping --node-types node-types.json --format json

# Generate a mapping skeleton
uast mapping --node-types node-types.json --generate --language go --extensions .go

# Dump the tree-sitter tree of a file
uast mapping --show-treesitter --language go main.go

uast completion <shell>¶

Generates the completion script for bash, zsh, fish or powershell on stdout, covering every subcommand and flag listed on this page.

uast version¶

Prints uast <version> (commit: <hash>, built: <date>).