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

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.1
File Size Uploaded Provenance Actions
big_code_analysis_cli-2.5.1.tar.gz 5.7 MB With provenance Details for big_code_analysis_cli-2.5.1.tar.gz

Built distributions (wheels)

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

Total release size: 48.3 MB

Release files / big_code_analysis_cli-2.5.1.tar.gz

Download URL big_code_analysis_cli-2.5.1.tar.gz
Size 5.7 MB
Tags Source
SHA-256 checksum
How to use checksums
48a00744cfb8c5eb4c94bc7d8426131fa1b4fc7c78419572ce5e6c2229e6ba09
BLAKE2b-256 checksum
How to use checksums
f2eb829f8a7dbef642024c070c593f6c256b1ac194b1f407e1f45c5d5eabce3d
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.1-py3-none-win_amd64.whl

Download URL big_code_analysis_cli-2.5.1-py3-none-win_amd64.whl
Size 8.8 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
68a7501f99199905b7daac22838539aab2e0e62e48afce47170391bdd39a6ec8
BLAKE2b-256 checksum
How to use checksums
80132520c7c34a7b1997844d6e93527e0494fd900b9f608331c6b13f3a3589f5
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.1-py3-none-manylinux_2_28_x86_64.whl

Download URL big_code_analysis_cli-2.5.1-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
e9c817b907736339beb124e31f3a79b479b19cde5fda6fb3643fecbb4a4b1b76
BLAKE2b-256 checksum
How to use checksums
f3801e7e14fee045468efe7275b1042b317850b623293def1d04843a1a76d7aa
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.1-py3-none-manylinux_2_28_aarch64.whl

Download URL big_code_analysis_cli-2.5.1-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
3e7224c2d9424bc3cc7b388a3c2885f6757106f7bd08213077654ad36e65cbc4
BLAKE2b-256 checksum
How to use checksums
e17c405cc0c992aeb84bd43c017241e449207d095bb52b4cdedf53e351b5bf61
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.1-py3-none-macosx_11_0_arm64.whl

Download URL big_code_analysis_cli-2.5.1-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
e9c2561fd225871fa36c9805dc1d35442a18e2dc2ebbbaddc1408d0ec49ee5a2
BLAKE2b-256 checksum
How to use checksums
e1269576c82d1420a1dda06973d16df03422e19ce8dc00a8f206c0a0c454c8d1
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.1-py3-none-macosx_10_12_x86_64.whl

Download URL big_code_analysis_cli-2.5.1-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
e584d607be7a99f59f95fe01b3943d137887ce05e3a5faa6037982fee594ea5d
BLAKE2b-256 checksum
How to use checksums
f91dab21058e5f5b4940f4673ee074e570fc9b95aa29acc5aed4baf67af7b86f
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.1

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