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.6.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.6.0
File Size Uploaded Provenance Actions
big_code_analysis_cli-2.6.0.tar.gz 5.9 MB With provenance Details for big_code_analysis_cli-2.6.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for big-code-analysis-cli 2.6.0
File Actions
big_code_analysis_cli-2.6.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for big_code_analysis_cli-2.6.0-py3-none-win_amd64.whl
big_code_analysis_cli-2.6.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.6.0-py3-none-manylinux_2_28_x86_64.whl
big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_aarch64.whl
big_code_analysis_cli-2.6.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for big_code_analysis_cli-2.6.0-py3-none-macosx_11_0_arm64.whl
big_code_analysis_cli-2.6.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for big_code_analysis_cli-2.6.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 49.2 MB

Release files / big_code_analysis_cli-2.6.0.tar.gz

Download URL big_code_analysis_cli-2.6.0.tar.gz
Size 5.9 MB
Tags Source
SHA-256 checksum
How to use checksums
1377d422560d95e66af30438bf415da1152ecd7eecf0d9c2635d5b80ccbe36d5
BLAKE2b-256 checksum
How to use checksums
bb3a91c402105d16a029c7044241c29e25b15700d04ff090f2a7c12e0fe5a067
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 17, 2026.

Transparency log

Release files / big_code_analysis_cli-2.6.0-py3-none-win_amd64.whl

Download URL big_code_analysis_cli-2.6.0-py3-none-win_amd64.whl
Size 8.9 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
e032658de1dbb58ddf7f44c7f08409e56785ae31dec032a71adbfd20f00ca571
BLAKE2b-256 checksum
How to use checksums
7f8adec4740049564cfbce9f66c3348ec8fa51b2ac480faf72fbfd39d1aa672d
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 17, 2026.

Transparency log

Release files / big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_x86_64.whl

Download URL big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_x86_64.whl
Size 8.7 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
94edcd3efe0111a6173b514ec001ae2bcf7dfa78081895bc3152723aff812940
BLAKE2b-256 checksum
How to use checksums
177ac43b884602198d6661ddcd9748b0b5c6e022ed6f4ca3bbf7b366833b69b9
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 17, 2026.

Transparency log

Release files / big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_aarch64.whl

Download URL big_code_analysis_cli-2.6.0-py3-none-manylinux_2_28_aarch64.whl
Size 8.4 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
62fbebd663e064a15eb08fdc3bef4c399263aae247961bc80df792e5caf22dd0
BLAKE2b-256 checksum
How to use checksums
bbee79bd17d82a15e52aa59ea65baaeabae4b9916db29a040136b536cbbeecf7
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 17, 2026.

Transparency log

Release files / big_code_analysis_cli-2.6.0-py3-none-macosx_11_0_arm64.whl

Download URL big_code_analysis_cli-2.6.0-py3-none-macosx_11_0_arm64.whl
Size 8.5 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
fc6174b0a68ae05e4640c1c7570eb40031d9fc1e23458243caee120271c88b57
BLAKE2b-256 checksum
How to use checksums
89db4c2ec1351ca53848a8bd00d7a88f4aaffbef67fb15f49223790f9af434a6
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 17, 2026.

Transparency log

Release files / big_code_analysis_cli-2.6.0-py3-none-macosx_10_12_x86_64.whl

Download URL big_code_analysis_cli-2.6.0-py3-none-macosx_10_12_x86_64.whl
Size 8.7 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
b57992fc02e538859305205d3fc8fd8251df6559c95d558290db280c805f6ed3
BLAKE2b-256 checksum
How to use checksums
3f2d3398833e8fa6124af40f89c123f42f0f42f8ad288fa9ad55ecc9f30563c4
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 17, 2026.

Transparency log

Security for big-code-analysis-cli 2.6.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.6.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 17, 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