Skip to main content

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 are report, vcs, and init (--paths only; init scaffolds into --dir) and diff (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 default auto uses the effective CPU count (--num-jobs is 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). --warning is a deprecated alias.
  • --no-skip-generated: disable auto-skip of files marked as generated (see Skipping generated code).
  • --report-skipped: log a skipped (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 with bca 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)

Source distribution for big-code-analysis-cli 2.5.0
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)

Table of built distributions (wheels) for big-code-analysis-cli 2.5.0
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page