Migration: Flag CLI to Subcommand CLI

The CLI was restructured from a flat flag-style interface (one process, many mutually-exclusive --action flags) into a subcommand-style interface (bca <verb>). This page maps every old invocation to its replacement.

Why the change

The flag CLI overloaded --output-format with two unrelated meanings: per-file serialization (-O json/yaml/toml/cbor) and a post-walk aggregated report (-O markdown). It needed two clap ArgGroups plus runtime checks to police invalid combinations, and --top / --strip-prefix lived as global flags that only applied to one format. Future aggregated formats (e.g. HTML) would compound the fragility.

The subcommand CLI fixes the structure: bca metrics and bca ops emit per-file output; bca report <FORMAT> emits an aggregated report; each verb has its own scoped flag set.

Migration mapping

Old	New
`--metrics -O markdown` (+ `--top`, `--strip-prefix`)	`report markdown`
`--metrics -O json/yaml/toml/cbor`	`metrics -O json/yaml/toml/cbor`
`--metrics -O checkstyle/sarif/code-climate/clang-warning/msvc-warning`	`check --threshold ... --report-format <fmt> [--output FILE]`
`--ops -O ...`	`ops -O ...`
`--dump`	`dump`
`--find <NODE>`	`find -t <NODE> [-t <NODE>...]`
`--count <LIST>`	`count -t <NODE> [-t <NODE>...]`
`--function`	`functions`
`--comments [--in-place]`	`strip-comments [--in-place]`
`--preproc <FILE> <FILE>...` (producer)	`preproc -o <OUT>`
`--preproc <FILE>` (consumer)	`--preproc-data <FILE>` (per subcommand, after the verb)
`--list-metrics [MODE]`	`list-metrics [MODE]`
`--pr` (pretty)	`--pretty` (on `metrics` and `ops`)
`--ls`, `--le` (global)	`--line-start`, `--line-end` on `dump`/`find` (`--ls`/`--le` kept as deprecated aliases)
`-p`, `-I`, `-X`, `-j`, `-l`	scoped to the subcommand; pass them after the verb (`-w` stays universal)

Side-by-side examples

Aggregated markdown report

# OLD
big-code-analysis-cli \
    --metrics \
    --paths "$PWD" \
    --output-format markdown \
    --jobs $(nproc) \
    --top 20 \
    --strip-prefix "$PWD/"

# NEW
bca \
    report \
    --paths "$PWD" \
    --format markdown \
    --top 20 \
    --strip-prefix "$PWD/"

Per-file metric extraction

# OLD
big-code-analysis-cli --metrics --paths ./src --output-format json --output ./out/

# NEW (per-file tree: --output became --output-dir in 2.0)
bca metrics --paths ./src -O json --output-dir ./out/

Per-file ops extraction

# OLD: big-code-analysis-cli --ops --paths ./src -O json -o ./out/
# NEW: bca ops --paths ./src -O json --output-dir ./out/

AST dump

# OLD: big-code-analysis-cli --dump --paths ./file.rs
# NEW: bca dump --paths ./file.rs

Find / count nodes

# OLD: big-code-analysis-cli --find call_expression --paths ./src
# NEW: bca find --paths ./src -t call_expression

# OLD: big-code-analysis-cli --count if_statement,for_statement --paths ./src
# NEW: bca count --paths ./src -t if_statement -t for_statement

Note: count now takes one node type per positional argument (space separated) rather than one comma-separated string.

Function spans

# OLD: big-code-analysis-cli --function --paths ./src
# NEW: bca functions --paths ./src

Strip comments

# OLD: big-code-analysis-cli --comments --in-place --paths ./src
# NEW: bca strip-comments --paths ./src --in-place

Preproc data — producer

# OLD
big-code-analysis-cli --metrics --preproc a.h --preproc b.h \
    --paths ./src -o /tmp/p.json

# NEW
bca preproc --paths ./src -o /tmp/p.json

Preproc data — consumer

# OLD
big-code-analysis-cli --metrics --preproc /tmp/p.json \
    --paths ./src -O json -o ./out/

# NEW
bca metrics --paths ./src --preproc-data /tmp/p.json \
    -O json --output-dir ./out/

List metrics

# OLD: big-code-analysis-cli --list-metrics descriptions
# NEW: bca list-metrics descriptions

Migration hint at runtime

If you run a legacy invocation, the CLI prints a hint identifying the recognized old flags and their new equivalents before clap's own error. For example:

$ bca --metrics -O markdown
note: the CLI was restructured into subcommands. See migration.md for the full mapping.
  --metrics  ->  bca metrics
  -O markdown  ->  bca report markdown|html [--top N] [--strip-prefix P]
  Run `bca --help` for the new command list.

error: unexpected argument '--metrics' found

big-code-analysis Documentation