CLI Reference

Usage

symtrace [REPO_PATH] [COMMIT_A] [COMMIT_B] [OPTIONS]
symtrace lint [PATH] [OPTIONS]
symtrace tui [REPO_PATH] [COMMIT_A] [COMMIT_B] [OPTIONS]
symtrace merge-driver <BASE_FILE> <OURS_FILE> <THEIRS_FILE> <TARGET_PATH>
symtrace git-diff-driver <PATH> <OLD_FILE> <OLD_HEX> <OLD_MODE> <NEW_FILE> <NEW_HEX> <NEW_MODE>

Positional Arguments

All positional arguments are optional and feature intelligent default resolution:

Argument	Default	Description
REPO_PATH	.	Path to local Git repository (or -r / --repo flag)
COMMIT_A	HEAD~1	Older commit ref, tag, branch, or commit hash
COMMIT_B	Working Tree	Newer commit ref, tag, branch, or commit hash (defaults to working tree, or HEAD if --staged is used)

Options & Flags

Flag	Short	Default	Description
--compact		off	Force micro-compact inline token diff output for small edits (1–3 lines)
--full-headers / --verbose		off	Force full structural banners, timing diagnostics, and blast radius tables
--format <FMT>		ansi	Output format: ansi, json, jsonl, markdown, html, sarif, prompt
--stat	-s	off	Output high-level semantic summary table across modified files
--check		off	Exit code 1 if structural logic changes exist (CI / pre-commit guard)
--name-only		off	List only changed file paths containing structural AST changes
--staged / --cached		off	Compare staged index changes against COMMIT_A
--logic-only		off	Ignore comments and whitespace-only modifications
--json		off	Alias for --format json
--path <GLOB>	-p		Filter changed files matching glob pattern (e.g. "src/**/*.rs")
--color <WHEN>		auto	Terminal color output mode (auto, always, never). Respects NO_COLOR
--no-pager		off	Disable piping terminal output to $PAGER
--config <PATH>			Custom configuration file path (.symtracerc / symtrace.toml)
--no-incremental		off	Disable incremental AST parsing and cache reuse
--max-file-size <BYTES>		5242880 (5 MiB)	Skip files larger than specified byte size
--max-ast-nodes <N>		200000	Skip files exceeding specified AST node count
--max-recursion-depth <N>		2048	Maximum AST parser recursion depth
--parse-timeout-ms <MS>		2000 (2s)	Per-file Tree-sitter parse timeout in milliseconds (0 = disabled)
--help	-h		Print help message
--version	-V		Print version information

Subcommands

lint

Declarative AST semantic linter evaluating custom Tree-sitter .scm rules with automated CI thresholds:

symtrace lint [PATH] [OPTIONS]

Subcommand Flag	Default	Description
PATH	.	Target path or directory to lint
--queries-dir <DIR>	.symtrace/queries	Custom directory containing .scm rule files
--max-warnings <N>	0	Maximum allowed warnings before non-zero CI exit code
--format <FMT>	cli	Linter output format (cli, json, sarif)

See Custom Query DSL & Linter Guide →.

tui

Launch the interactive terminal workspace with split-pane refactor navigation and call graph visualization:

symtrace tui [REPO_PATH] [COMMIT_A] [COMMIT_B] [OPTIONS]

See Interactive TUI Inspector Guide →.

merge-driver

Native 3-way AST merge driver for resolving Git rebases and merge conflicts:

symtrace merge-driver <BASE_FILE> <OURS_FILE> <THEIRS_FILE> <TARGET_PATH>

See 3-Way AST Merge Driver Guide →.

git-diff-driver

Repo context-aware integration driver for native git diff commands:

symtrace git-diff-driver <PATH> <OLD_FILE> <OLD_HEX> <OLD_MODE> <NEW_FILE> <NEW_HEX> <NEW_MODE>

See Native Git Diff Driver Guide →.

Exit Codes

Exit Code	Meaning
0	Clean execution: no structural changes detected (when --check is enabled), 0 linter rule violations (or within max-warnings limit), or clean 3-way AST merge
1	Structural logic changes detected (when --check is set), linter rule violations exceeded threshold (symtrace lint), or merge conflicts written
130	Execution interrupted by user (Ctrl+C)