big-code-analysis-cli
bca is the command-line front end for the
big-code-analysis library.
It analyzes source code and emits per-file structured metrics,
aggregated reports, threshold checks, AST dumps, and node lookups. The
full reference is the
user guide.
Migrating from the flag-style CLI? The CLI is now subcommand-driven. See the migration guide for old-form -> new-form mappings of every flag.
Installation
From PyPI (pip)
Install a prebuilt wheel on Linux, macOS, or Windows without a Rust toolchain:
pip install big-code-analysis-cli # installs the `bca` command on PATH
bca --version
The distribution name
and the command name differ on purpose: you
pip install big-code-analysis-cli, but the installed executable is
bca. The bca name on PyPI belongs to an unrelated project, and
big-code-analysis is this project's importable library bindings
(pip install big-code-analysis), a different deliverable.
The wheel ships the full all-languages grammar set. A single
py3-none-<platform> wheel covers every CPython 3.x (and PyPy) on that
platform. Prebuilt wheels are published for Linux (manylinux_2_28
x86_64 / aarch64), macOS (x86_64 / arm64), and Windows
(x86_64); other platforms fall back to a source build.
From crates.io (Cargo)
cargo install big-code-analysis-cli
From source
cd big-code-analysis-cli/
cargo build --release
Usage
bca [OPTIONS] <COMMAND> [COMMAND OPTIONS]
The command picks what to do; its options describe what to walk
(paths, includes and excludes, parallelism, language overrides) and how
to format the result. Input-selection and walker-tuning flags are
scoped to the subcommand that consumes them and must be written
after the subcommand token. Only -w / --warnings and
--report-skipped are universal and accepted in any position.
Commands
| Command | Purpose |
|---|---|
metrics |
Per-file metric output (-O cbor/csv/json/toml/yaml, --output-dir DIR). |
ops |
Per-file operand/operator output (same formats as metrics). |
report <FORMAT> |
Aggregated report (markdown or html). |
check |
Check per-function metrics against thresholds; exits 2 on threshold violations. |
dump |
AST dump to stdout (--line-start/--line-end to scope a range). |
find -t <NODE>... |
Find nodes of one or more types, one -t/--type per type (--line-start/--line-end to scope a range). |
count -t <NODE>... |
Count nodes of one or more types, one -t/--type per type. |
functions |
List functions/methods and their spans. |
strip-comments |
Remove comments from source files (--in-place or --output FILE). |
preproc |
Build preprocessor-data JSON for C/C++ analysis. |
list-metrics [names|descriptions] |
List computable metrics. |
vcs [commit|trend] |
Rank files by change-history risk; score one commit; sample a trend. |
init |
Scaffold bca.toml, .bcaignore, and .bca-baseline.toml. |
diff |
Compare two metric-output runs (or --since <ref> against the working tree). |
diff-baseline |
Diff two .bca-baseline.toml files. |
exemptions |
List everything the check gate skips: markers, [check.exclude] globs, baseline entries. |
Run bca <COMMAND> --help for command-specific options.
Walking options
The walking subcommands (metrics, ops, report, check, dump,
find, count, functions, strip-comments, preproc, exemptions,
init, diff, and the bare vcs ranking) accept these input-selection
and walker-tuning flags, written after the subcommand. A flag passed
to a subcommand that never consumes it is a hard usage error (exit 1),
not a silent no-op.
-p, --paths <FILE>...: input files or directories. Most walking subcommands also accept paths positionally (bca metrics src/); the exceptions arereport,vcs, andinit(--pathsonly;initscaffolds into--dir) anddiff(its positionals are the two result sets).-I, --include <GLOB>: include files matching pattern (repeatable).-X, --exclude <GLOB>: exclude files matching pattern (repeatable).-j, --jobs <N|auto>: worker threads; the defaultautouses the effective CPU count (--num-jobsis a deprecated alias).-l, --language <LANG>: force a language instead of inferring. Accepts a language name (rust) or extension (rs); unknown values error out.-w, --warnings: print warnings (skipped files, unrecognized languages).--warningis a deprecated alias.--no-skip-generated: disable auto-skip of files marked as generated (see Skipping generated code).--report-skipped: log askipped (generated): <path>line to stderr for every file the generated-code detector excludes.--preproc-data <FILE>: consume an existing preproc JSON during C/C++ analysis. Build one withbca preproc.
-w / --warnings and --report-skipped are the only universal options;
they are accepted in any position, before or after the subcommand.
Building with a subset of languages
The shipped bca binary compiles in every supported
tree-sitter grammar. The
big-code-analysis-cli crate pins the library's all-languages feature
set explicitly, so passing --no-default-features or a custom
--features list to cargo build -p big-code-analysis-cli does not
drop grammars from the resulting binary. Feature selection on the CLI
crate is not honoured: dropping a grammar silently from a user-facing
binary would surface as "language X stopped working" rather than as a
build error (#252).
To ship a reduced grammar set, embed the big-code-analysis library in
your own Rust code and select features in your own Cargo.toml. The
library's per-language Cargo features chapter lists
the features and gives a worked example.
Examples
Per-file JSON metrics:
bca metrics --paths ./src -O json --output-dir ./out/
Aggregated markdown quality report:
bca report --format markdown --paths "$PWD" --jobs $(nproc) \
--top 20 --strip-prefix "$PWD/"
AST dump for one file:
bca dump ./file.rs
List all metrics with one-line descriptions:
bca list-metrics descriptions
Skipping generated code
Generated files inflate metrics for code no human will refactor. By
default, bca scans the first ~50 lines / 5 KiB of each file for a
generated-code marker and skips matches before parsing.
Recognized markers (case-insensitive):
@generated: a marker emitted by code generators.DO NOT EDIT: a marker used by Go's generated-code convention and other generators.GENERATED CODE: Lizard's marker, recognized for compatibility.
A marker phrase that appears only deep in the file body (past the scan window) does not trigger the skip.
To analyze everything, pass --no-skip-generated. To audit which files
were excluded, pass --report-skipped; the CLI logs
skipped (generated): <path> to stderr for each file.
Metadata
Release files for big-code-analysis-cli 2.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| big_code_analysis_cli-2.5.0.tar.gz | 5.7 MB | With provenance | Details for big_code_analysis_cli-2.5.0.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| big_code_analysis_cli-2.5.0-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for big_code_analysis_cli-2.5.0-py3-none-win_amd64.whl |
| big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_x86_64.whl | Python 3 | none | Linux glibc 2.28+ x86-64 | Details for big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_x86_64.whl |
| big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_aarch64.whl | Python 3 | none | Linux glibc 2.28+ ARM64 | Details for big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_aarch64.whl |
| big_code_analysis_cli-2.5.0-py3-none-macosx_11_0_arm64.whl | Python 3 | none | macOS 11.0+ ARM64 | Details for big_code_analysis_cli-2.5.0-py3-none-macosx_11_0_arm64.whl |
| big_code_analysis_cli-2.5.0-py3-none-macosx_10_12_x86_64.whl | Python 3 | none | macOS 10.12+ x86-64 | Details for big_code_analysis_cli-2.5.0-py3-none-macosx_10_12_x86_64.whl |
Total release size: 48.3 MB
Release files / big_code_analysis_cli-2.5.0.tar.gz
| Download URL | big_code_analysis_cli-2.5.0.tar.gz |
|---|---|
| Size | 5.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aef1f6b5edc30a1e05d67303b22a8bcc2457f3079f77e9078d45ba9cc63969b2
|
|
BLAKE2b-256 checksum How to use checksums |
44b55e8e6e6cea3548d6b8f36179cff5adcd28526f83a11275b41dc1fd9ca550
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / big_code_analysis_cli-2.5.0-py3-none-win_amd64.whl
| Download URL | big_code_analysis_cli-2.5.0-py3-none-win_amd64.whl |
|---|---|
| Size | 8.8 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
58ca6ede6c04087d598c3cc1f8544593502fef78577ab968bbe19af1a8d34ab7
|
|
BLAKE2b-256 checksum How to use checksums |
b0cadf325404ab30501098e19c640422b8a27badf5f3b9573163c65ed3287ed3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_x86_64.whl
| Download URL | big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 8.6 MB |
| Tags | Linux glibc 2.28+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
e6f1216d800255bbe23d7f7362c793035db9bfb72659fdf04bf69c8fd453e549
|
|
BLAKE2b-256 checksum How to use checksums |
7f83844ff872e62326dedc0c01f13307543730c439d41ad12ffbe2a06c91fd29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_aarch64.whl
| Download URL | big_code_analysis_cli-2.5.0-py3-none-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 8.2 MB |
| Tags | Linux glibc 2.28+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
fb141800a23a6658c40eca20b521ffdbc7b962f111fd0b3c0fd38e10986c22de
|
|
BLAKE2b-256 checksum How to use checksums |
00a74d8ece24c1c98a3ee1157ae2abd0c250795157f7ba0b3fddd08801131213
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / big_code_analysis_cli-2.5.0-py3-none-macosx_11_0_arm64.whl
| Download URL | big_code_analysis_cli-2.5.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.4 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
660b28f342f58c5a4b2be9fcbe6186a776028b1fd9bca5e253fc72eee66a06a9
|
|
BLAKE2b-256 checksum How to use checksums |
5461ec685cb7cb5f33d184c6b1d2306e93424e3887f9d3480fb99f89cb2c0c01
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / big_code_analysis_cli-2.5.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | big_code_analysis_cli-2.5.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 8.6 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
cda6db03e265135ed94a8ca4955f7d4a37c079723d5c96dd17137ad12c78f416
|
|
BLAKE2b-256 checksum How to use checksums |
13b177c07b0860fddd6f575154f5babe11c57f25b35758f927e77d3b4bbc7435
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for big-code-analysis-cli 2.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for big_code_analysis_cli-2.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.