@codacy/analysis-cli

Table of Contents

• Overview
• Installation
• Commands
• Usage
• upload — send analysis results to Codacy
• container-scan — scan a container image
• upload-sbom — upload a container image SBOM
• init --remote / update-config — repository token
• init --auto — stack-aware initialization
• Configuration file location
• Logging
• Container mode
• Managed tool versions
• Automatic update checks
• Proxy and TLS
• Supported tools
• File targeting
• Git-aware scoping
• Registering adapters

Overview

Thin CLI wrapper around @codacy/analysis-runner. Built with commander, provides the codacy command with analyze and init subcommands.

Installation

From npm

npm i -g @codacy/analysis-cli

From source

# From the repository root
pnpm install && pnpm build
cd packages/cli && pnpm link --global

To unlink later: pnpm uninstall -g @codacy/analysis-cli.

Commands

| Command | Description | | --------------------------------------- | -------------------------------------------------------------------------------------------------- | | analyze [path] | Run analysis on a repository, file, directory, or quoted glob | | discover [path] | Discover languages, frameworks, libraries, and notable files | | init | Initialize .codacy/codacy.config.json | | init --auto [filters] | Discover stack, select tools/patterns by detected frameworks | | update-config [path] | Update .codacy/codacy.config.json to the current stack, preserving edits (--reset regenerates) | | config (--merge\|--intersect\|--diff) | Combine two config files via set operations; result written to --dest | | info | Show auth status, system info, and registered tool availability | | upload <path> | Upload an analysis report (SARIF or JSON) to Codacy, attaching results to a commit | | container-scan <image> | Scan a container image for vulnerabilities (Trivy) | | upload-sbom <image> | Generate a container image SBOM with Trivy and upload it to Codacy | | login | Authenticate with the Codacy API and store credentials | | logout | Remove stored Codacy API credentials |

Codacy Cloud tools without a local analyzer ("cloud-only") are still tracked: init/update-config add them to the config, info shows them as Supported = No, and analyze lists them as Unsupported (never executed, never fails --fail-if-missing).

Usage

# Authenticate before using commands that require a Codacy API token
codacy-analysis login
codacy-analysis login --token <your-api-token>

# Remove stored credentials
codacy-analysis logout

# Run analysis on the current directory
codacy-analysis analyze

# Run analysis with text output (default) or other formats
codacy-analysis analyze --output-format sarif --output results.sarif

# Run only specific tools
codacy-analysis analyze --tool shellcheck-0 --tool ruff-0

# Analyze only staged files (pre-commit)
codacy-analysis analyze --staged

# Analyze files changed in the current branch
codacy-analysis analyze --diff

# Analyze files changed vs a specific base branch
codacy-analysis analyze --diff develop

# Analyze files in the current pull request
codacy-analysis analyze --pr

# Auto-install missing tool binaries
codacy-analysis analyze --install-dependencies

# Check which tools are available without running analysis
codacy-analysis analyze --inspect

# Fail immediately if any configured tool is missing
codacy-analysis analyze --fail-if-missing

# Run tools in parallel
codacy-analysis analyze --parallel-tools 4

# Auto-detect stack and select tools/patterns by detected frameworks
codacy-analysis init --auto

# Auto-init with only high-severity and security patterns
codacy-analysis init --auto Critical,High,Security

# Auto-init including non-default patterns for those filters
codacy-analysis init --auto AllCritical,AllSecurity

# Initialize from Codacy Cloud (also imports cloud-ignored files into the local config)
codacy-analysis init --remote gh myorg myrepo
codacy-analysis init --remote gh myorg myrepo --repository-token <repository-token>

# Update the local config to the current stack, preserving your edits
# (add --reset to regenerate from scratch instead)
codacy-analysis update-config

# Combine two config files via set operations (result written to --dest)
codacy-analysis config --merge --source .codacy/extra.json --dest .codacy/codacy.config.json
codacy-analysis config --intersect --source a.json --dest b.json
codacy-analysis config --diff --source baseline.json --dest .codacy/codacy.config.json

# Use a custom config file location (defaults to .codacy/codacy.config.json)
codacy-analysis init --auto --config-file .codacy/auto-config.json
codacy-analysis analyze --config-file .codacy/auto-config.json

# Run as the engine inside a Codacy tool container (see "Container mode")
codacy-analysis analyze . --codacyrc /.codacyrc --tool Ruff

# Discover languages, frameworks, and libraries in the repository
# (honors .codacy.yaml exclude_paths, so the reported stack matches what gets analyzed)
codacy-analysis discover

# Discover with JSON output
codacy-analysis discover --output-format json

# Save discovery results to a file
codacy-analysis discover -f json -o discovery.json

# Discover without applying .codacy.yaml exclude_paths (see the raw scan)
codacy-analysis discover --no-exclude

# Show auth status, system info, and tool availability
codacy-analysis info

# Upload an analysis report (SARIF or JSON) produced by `analyze` to Codacy
codacy-analysis analyze . --output-format sarif --output results.sarif
codacy-analysis upload results.sarif --repository-token <repository-token>
codacy-analysis upload results.json --repository gh myorg myrepo --commit <sha>

# Scan a container image, and upload its SBOM to Codacy
codacy-analysis container-scan myorg/app:v1.2.0
codacy-analysis upload-sbom myorg/app:v1.2.0 -p gh -o myorg -r myrepo

upload — send analysis results to Codacy

Uploads a report produced by analyze (either --output-format sarif or json) to Codacy, attaching its issues to a commit. Only reports produced by this CLI are supported — they already carry Codacy pattern IDs, so no extra mapping is needed.

codacy-analysis upload <path> [options]

| Option | Description | | ------------------------------------------ | -------------------------------------------------------------------- | | -c, --commit <sha> | Commit the results attach to. Defaults to the current git HEAD. | | -t, --repository-token <token> | Repository token. Or set CODACY_PROJECT_TOKEN. | | -r, --repository <provider> <org> <repo> | Account-token mode target. Falls back to the init --remote config. |

Auth modes (mutually exclusive):

• Repository token — pass -t <token> (or set CODACY_PROJECT_TOKEN). The upload is scoped by commit only.
• Account token — uses the token from codacy-analysis login / CODACY_API_TOKEN, plus the repository coordinates from -r <provider> <org> <repo> (or, when omitted, the provider/organization/repositoryName stored by init --remote).

Set CODACY_RESULTS_API_BASE_URL to target a self-hosted Codacy (defaults to https://api.codacy.com/2.0).

container-scan — scan a container image

Scans a container image for known vulnerabilities with Trivy and reports them through the same output formats as analyze. Replaces cli-v2's container-scan. The image may be local (Docker, containerd, Podman) or in a registry; Trivy is installed into ~/.codacy/tools/Trivy on first use.

codacy-analysis container-scan <image> [options]

| Option | Description | | ------------------------------ | --------------------------------------------------------------------------------------- | | -f, --output-format <format> | text (default), json or sarif. | | -o, --output <file> | Write the report to a file; a summary still goes to the terminal. | | --severity <list> | Severities to report: UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL. Default HIGH,CRITICAL. | | --pkg-types <list> | os (distribution packages), library (language packages in the image). Default os. | | --ignore-unfixed [bool] | Skip vulnerabilities with no released fix. Default true. | | --no-ignore-unfixed | Also report vulnerabilities with no released fix. | | --log-level <level> | debug, info (default), warn, error. |

Defaults match cli-v2 on purpose. HIGH/CRITICAL, OS packages and --ignore-unfixed are what cli-v2 hard-coded, so moving a CI job over does not change what it reports or when it fails. --ignore-unfixed stays on by default for the same reason; cli-v2's --ignore-unfixed=false spelling is still accepted.

Each finding's location is Trivy's scan target — the OS layer (nginx:1.25 (debian 12.5)) or the manifest inside the image a language package came from — at line 1, since an image has no source lines. Findings carry the CVE as sourceId, exactly like repository Trivy findings.

Exit codes: 0 no vulnerabilities, 1 vulnerabilities found, 2 error — an invalid image reference (rejected before anything is spawned), a failed Trivy install, or a failed scan such as an image that cannot be found.

upload-sbom — upload a container image SBOM

Generates an SBOM for a container image with Trivy and uploads it to Codacy's organization image-SBOM endpoint in one step, for vulnerability tracking in Codacy. Replaces cli-v2's upload-sbom with the same flags.

codacy-analysis upload-sbom <image> -p <provider> -o <organization> [options]

| Option | Description | | --------------------------- | -------------------------------------------------------------------------------- | | -p, --provider <provider> | Git provider: gh, gl or bb. Required. | | -o, --organization <org> | Organization name on the provider. Required. | | -a, --api-token <token> | Account API token. Defaults to CODACY_API_TOKEN, then codacy-analysis login. | | -r, --repository <repo> | Codacy repository to associate the image with. | | -t, --tag <tag> | Tag to record. Defaults to the reference's own tag, else latest. | | -e, --environment <env> | Where the image is deployed, e.g. production. | | --format <format> | cyclonedx (default, smaller) or spdx-json. |

A digest reference (app@sha256:…) is recorded with the digest as its tag, and combining one with --tag is an error, since the digest already pins the image. The SBOM is written to a private temporary directory that is removed after the upload, whether it succeeded or not. Only an account token works — the endpoint has no repository-token mode. Set CODACY_API_BASE_URL to target a self-hosted Codacy.

Exit codes: 0 uploaded, 2 any failure (invalid input, failed install, failed SBOM generation, or a rejected upload — the API's status and message are printed).

init --remote / update-config — repository token

Fetching a remote config accepts a repository token or an account token:

| Option | Description | | ---------------------------- | ------------------------------------------------ | | --repository-token <token> | Repository token. Or set CODACY_PROJECT_TOKEN. |

No short flag — -t already means --tool on analyze and --repository-token on upload, and a short form here would either collide with one of those or add a third, inconsistent meaning.

Auth modes (mutually exclusive, same precedence upload uses):

• Repository token — pass --repository-token <token> (or set CODACY_PROJECT_TOKEN). Wins outright if given — scoped to one repository, no login required, and never silently overridden by an ambient account token. The token must belong to the repository named by <provider> <org> <repo>.
• Account token — codacy-analysis login / CODACY_API_TOKEN, used only when no repository token is available.

At least one is required.

init --auto — stack-aware initialization

The --auto flag discovers your repository's languages, frameworks, and libraries, then selects tools and patterns tailored to the detected stack. Framework-specific patterns (e.g., React, Django, Rails) are only enabled when the corresponding dependency is found in your package manifests.

Basic usage

# Detect everything, use default pattern selection
codacy-analysis init --auto

Filter patterns

Pass comma-separated filters to narrow the enabled patterns by severity and/or category:

# Only high-severity and security patterns
codacy-analysis init --auto Critical,High,Security

# Only error-prone patterns at Warning level and above
codacy-analysis init --auto Warning,ErrorProne

Available filters

| Type | Values | | -------- | ------------------------------------------------------------------------- | | Severity | Info/Minor, Warning/Medium, High, Error/Critical | | Category | Security, ErrorProne, CodeStyle, BestPractice, Performance, ... |

Filters are OR-combined within severity and category, then AND-combined across types.

Include non-default patterns

By default, only patterns marked as enabled: true are candidates. Prefix a filter with All to also include non-default patterns:

# All Critical patterns, including those not enabled by default
codacy-analysis init --auto AllCritical

# All Security patterns regardless of default status
codacy-analysis init --auto AllSecurity

# Combine: all critical + all security patterns
codacy-analysis init --auto AllCritical,AllSecurity

How it works

1. Reads .codacy.yaml exclude paths first, so every step below sees the same file set analyze will (see Excludes and discovery)
2. Runs discover to detect languages, frameworks, and libraries
3. Selects tools that support the detected languages, and that have at least one non-excluded file matching their own file patterns
4. For each tool, filters patterns using framework-aware mappings (e.g., Qwik patterns only enable when @builder.io/qwik is detected, i18next patterns only when i18next is a dependency)
5. Applies severity/category filters if provided
6. Records the exclude paths on the generated config

Excludes and discovery

Discovery is exclude-aware: the global exclude_paths in .codacy.yaml are applied before languages, frameworks, and libraries are detected, and per-engine exclude_paths are applied when deciding whether a specific tool has any files to analyze.

This matters for repositories whose only files in a given language sit in an excluded path — per-language test fixtures being the common case. Without it, init --auto would detect (say) Ruby from test/fixtures/sample.rb, enable RuboCop, and analyze would then hand RuboCop zero files.

update-config re-reads .codacy.yaml on every run (so edits to it are picked up) and additionally honors the excludes already recorded in codacy.config.json — including ones you hand-wrote and ones synced from Codacy Cloud's ignored-files list.

Updating an auto config

update-config is incremental by default: it re-runs auto-init with the same filters, then merges the result into your current config so your edits survive — disabled patterns stay disabled, tuned parameters and custom excludes are kept — while tools/patterns for newly-detected languages/frameworks are added and those whose stack element disappeared are removed (a tool left with no enabled patterns is dropped).

# Incremental update: pull in new stack items, keep your customizations
codacy-analysis update-config

# Regenerate from scratch, discarding local edits
codacy-analysis update-config --reset

This relies on a committed baseline snapshot written next to the config (codacy.config.baseline.json) that records the generator's last output; if it is missing, an additive merge is used instead (with a warning that disabled patterns may reappear). Configs created with init --remote are always fully re-synced from Codacy Cloud (cloud is authoritative).

Configuration file location

init, analyze, and update-config accept --config-file <path> to read or write the Codacy configuration file at a custom location instead of the default .codacy/codacy.config.json. The path is resolved relative to the current working directory (or may be absolute), consistent with -o/--output.

| Flag | Description | Default | | ---------------------- | ---------------------------------------------------------------- | ---------------------------- | | --config-file <path> | Path to the Codacy config file (relative to the CWD or absolute) | .codacy/codacy.config.json |

This lets you keep one config (e.g. synced from Codacy Cloud) while testing a variant side-by-side:

# Initialize and analyze using a custom config location
codacy-analysis init --auto --config-file .codacy/auto-config.json
codacy-analysis analyze --config-file .codacy/auto-config.json

# Regenerate that same custom config later
codacy-analysis update-config --config-file .codacy/auto-config.json

Combining configs with config

The config command performs set operations on the tools and patterns of two config files and writes the result to the destination (the source is read-only). Exactly one operation is required; --source/--dest default to .codacy/codacy.config.json (at least one must be given explicitly).

| Flag | Result | | ------------- | ---------------------------------------------------------------------- | | --merge | Union of tools, and per-tool union of patterns | | --intersect | Only tools present in both, and per-tool only patterns present in both | | --diff | dest − source — tools/patterns in dest that are not in source |

Notes: if either side runs a tool from its native config file, merge/intersect keep the config file for that tool; when a pattern is on both sides, merge/intersect keep the source's parameters; intersect/diff drop tools left with nothing to run.

codacy-analysis config --merge --source .codacy/extra.json
codacy-analysis config --intersect --source a.json --dest b.json
codacy-analysis config --diff --source baseline.json --dest .codacy/codacy.config.json

Logging

Logs are written to ~/.codacy/logs/ (JSON lines) and to stderr (human-readable).

Log levels

| Level | Description | | --------- | ---------------------------------------------------------------- | | debug | Most verbose — tool invocations, config resolution, file routing | | info | Default — progress milestones, tool start/finish, summary | | warning | Non-blocking issues — missing optional config, skipped tools | | error | Failures only — tool crashes, parse errors, missing dependencies |

Flags

| Flag | Description | Default | | --------------------- | ------------------------------------------------------------- | --------------- | | --log-level <level> | Set minimum log level (debug, info, warning, error) | info | | --no-log | Disable file logging (stderr output still respects log level) | logging enabled |

# Verbose output for debugging
codacy-analysis analyze --log-level debug

# Quiet — only errors
codacy-analysis analyze --log-level error

# Disable log files (e.g. in CI)
codacy-analysis analyze --no-log

Log files rotate at 10 MB, keeping the 5 most recent files.

Container mode

analyze --codacyrc <path> runs the CLI as the analysis engine inside a Codacy per-tool Docker image, in place of the single-purpose codacy-<tool> adapters.

# What a per-tool image's CMD looks like
codacy-analysis analyze . --codacyrc /.codacyrc --tool Ruff

--codacyrc implies --runner container, which changes several things at once:

| Flag | Description | Default | | --------------------- | -------------------------------------------------------------------------- | -------------- | | --codacyrc <path> | Read Codacy's analysis configuration from this file (resolved against CWD) | — | | --runner container | Container execution profile (implied by --codacyrc) | local | | -f, --output-format | Defaults to container (JSONL) under this profile | text locally |

• Exit codes follow the engine contract: 0 = success including when issues were found, 1 = the tool failed, 2 = timeout. Codacy reads any other non-zero as a failed analysis, so findings must not be reported as 1.
• Nothing is installed. --install-dependencies is rejected: the image ships its tools pinned, and the sandbox has no network.
• Nothing is written to the source directory. No .codacy/, no baseline, no log files; generated tool configs go to a per-run temp directory.
• .codacyrc's files list is the file set, not a filter over git ls-files — absent means "discover normally", [] means "analyze nothing", and a non-empty list is used verbatim. Git is only needed for the first of those.
• TIMEOUT_SECONDS (default 900) is a whole-run budget, and DEBUG raises the log level; both are read only under this profile, and logging stays on stderr.

init --container materializes the same configuration as a file so it can be inspected. It is for debugging only — it writes into the repository, which the production path never does.

Comparing against a Codacy tool image

--emit-codacyrc [path] writes the .codacyrc describing the run it is attached to — the file list after routing, the pattern set after resolution, in the engine's own vocabulary. Because it comes from the run rather than being recomputed, feeding it to the corresponding Codacy image analyzes exactly the same files with exactly the same rules, so anything left in the diff is a real difference between the two engines.

| Flag | Description | Default | | ------------------------ | -------------------------------------------------------- | ------------- | | --emit-codacyrc [path] | Write the .codacyrc for this run; resolved against CWD | ./.codacyrc |

# Our side, plus the .codacyrc that produced it
codacy-analysis analyze . --tool Ruff --emit-codacyrc -f container -o ours.jsonl

# Their side, same configuration. The image tag comes from /api/v3/tools
# (`dockerImage`); `--platform` is needed on Apple Silicon, as the images are
# published for linux/amd64 only.
docker run --rm --platform linux/amd64   -v "$(pwd)":/src -v "$(pwd)/.codacyrc":/.codacyrc   codacy/codacy-ruff:0.0.10 > theirs.jsonl

diff <(jq -cS . < ours.jsonl | sort) <(jq -cS . < theirs.jsonl | sort)

Worth knowing:

• The flag changes nothing else about the run. Analysis continues, stdout stays byte-identical, and the path is announced on stderr — so it can be added to any invocation, including one whose stdout is being parsed.
• Pin a single tool with --tool. .codacyrc carries one files list shared by every entry in tools[], so emitting for several tools gives their union, which is a superset for each one alone. Every consumer re-routes within it, so this is correct but no longer exact.
• The emitted file is not gitignored, so ./.codacyrc shows up as untracked.
• Nothing is written when the run never reaches routing (--inspect, a tool that could not run, nothing to analyze); the CLI says so rather than leaving a stale file in place.
• Combining it with --codacyrc is a legitimate round-trip; pointing both at the same file is rejected.

Managed tool versions

Adapters pin the tool version Codacy's cloud analyzer runs, because patterns.json is generated against it. Tools the CLI installed under ~/.codacy are therefore reinstalled automatically when a CLI upgrade moves a pin (before analysis, not gated on --install-dependencies, never fatal on failure, skipped for --runner container and --inspect). Tools installed on your system are never modified — analyze and info report them as outdated, needs <version> instead.

That applies whether the old install reports a stale version or reports nothing at all: adapters whose artifact name embeds the version (checkstyle-13.9.0-all.jar, pmd-bin-7.26.0/) say "not installed" after a bump while the previous artifact is still on disk, and those are reinstalled too. Only installs the CLI created are repaired — a tool you never installed still needs --install-dependencies, so a plain analyze never starts an unexpected download.

Generated tool configs are filtered against the rules the installed binary knows, so a codacy.config.json written before a version bump still analyses.

Automatic update checks

When a newer version is published to npm, the CLI prints a one-time "update available" notice on stderr. It never auto-updates — that is the CLI binary, which your package manager owns, not the managed tools described above.

The notice only appears with --output-format text in an interactive terminal — it is suppressed for json/sarif/container output, when piped, in CI, and under npx/npm scripts, so it can never corrupt machine-readable stdout. The version lookup runs in a non-blocking background process (at most once a day).

Opt out with CODACY_DISABLE_UPDATE_CHECK=1, NO_UPDATE_NOTIFIER=1, or the --no-update-notifier flag.

Proxy and TLS

All outbound HTTP (Codacy API calls and tool/runtime downloads) honors the standard proxy environment variables — set them once and every command routes accordingly.

| Variable | Purpose | | -------------------------------------------------------- | -------------------------------------------------------------- | | HTTPS_PROXY / HTTP_PROXY (or lowercase) | Proxy URL for HTTPS / HTTP requests | | NO_PROXY / no_proxy | Comma-separated hosts that bypass the proxy (*, .suffix) | | SSL_CERT_FILE / NODE_EXTRA_CA_CERTS | PEM CA bundle to trust (e.g. a corporate SSL-inspection proxy) | | CODACY_CLI_INSECURE / NODE_TLS_REJECT_UNAUTHORIZED=0 | Disable TLS verification (last resort; warns on stderr) |

export HTTPS_PROXY=http://proxy.corp:8080
export NO_PROXY=app.codacy.com,.internal
export SSL_CERT_FILE=/path/to/corporate-ca.pem   # prefer trusting the CA over disabling TLS

A misconfigured CA bundle fails fast with a clear error. These names match the Codacy MCP server, VSCode extension, and Go CLI, so the same environment drives all of them.

Library consumers of @codacy/analysis-runner can call configureProxy(overrides?) once at startup or pass proxy on AnalyzeOptions (same settings as the env vars).

The "update available" check uses a separate network stack that does not honor these variables; behind a strict proxy, disable it with CODACY_DISABLE_UPDATE_CHECK=1.

Supported tools

| Tool | ID | Languages | Strategy | | ------------ | --------------- | -------------------------------------- | -------- | | Jackson | jackson | JSON | Native | | markdownlint | markdownlint | Markdown | Library | | ShellCheck | shellcheck | Shell | CLI | | Hadolint | Hadolint | Dockerfile | CLI | | Ruff | Ruff | Python | CLI | | Cppcheck | cppcheck | C, C++ | CLI | | Trivy | Trivy | Multi-language | CLI | | Opengrep | Semgrep | 30+ languages | CLI | | Stylelint | Stylelint | CSS, SCSS, Less | Library | | Spectral | spectral | OpenAPI, AsyncAPI | Library | | ESLint 8 | ESLint8 | JS, TS, JSX, TSX | Library | | ESLint 9 | ESLint9 | JS, TS, JSX, TSX, Vue | Library | | Flawfinder | flawfinder | C, C++ | CLI | | Bandit | Bandit | Python | CLI | | Pylint | PyLintPython3 | Python | CLI | | Checkov | Checkov | Terraform, CloudFormation, K8s, Docker | CLI | | Lizard | Lizard | 30+ languages | CLI | | Checkstyle | Checkstyle | Java | CLI | | PMD 7 | PMD7 | Java, Apex, Visualforce | CLI | | detekt | detekt | Kotlin | CLI | | Reek | Reek | Ruby | CLI | | Brakeman | Brakeman | Ruby (Rails) | CLI | | RuboCop | RuboCop | Ruby | CLI | | Biome | Biome | JS, TS, CSS | CLI | | Revive | Revive | Go | CLI | | SwiftLint | SwiftLint | Swift | CLI | | SQLint | SQLint | SQL | CLI | | SQLFluff | SQLFluff | SQL | CLI | | Scalastyle | ScalaStyle | Scala | CLI | | Agentlinter | Agentlinter | AI agent configs | CLI | | PMD 6 | PMD | Java, Apex, Visualforce | CLI | | Prospector | Prospector | Python | CLI | | dartanalyzer | dartanalyzer | Dart | CLI |

Use --tool <id> to restrict analysis to specific tools (repeatable):

codacy-analysis analyze --tool ruff --tool bandit
codacy-analysis analyze --tool eslint9

File targeting

The CLI supports several ways to scope analysis to specific files.

Analyze a single file

Pass a file path as the positional argument. The CLI detects it is a file, finds the git repository root, and restricts analysis to that file.

codacy-analysis analyze ./src/main.py

Analyze a subdirectory

Pass a subdirectory path. The CLI finds the git root (so .codacy/codacy.config.json is still found) and restricts analysis to files under that subdirectory.

codacy-analysis analyze ./src/api/

Analyze a glob

Pass a quoted glob as the positional argument. The CLI recognizes the glob, finds the git root, and matches it against tracked files (same engine as --files). Quote it so your shell doesn't expand it — this is also what makes it work on Windows, where the shell never expands globs.

codacy-analysis analyze "src/**/*.ts"

Target files with --files

Use --files to pass paths or globs. It accepts multiple values in a single invocation and can also be repeated.

# Multiple explicit files
codacy-analysis analyze --files src/a.py src/b.py

# Quoted glob — the CLI expands it against tracked files via minimatch
codacy-analysis analyze --files "src/**/*.ts"

# Unquoted glob — the shell expands it before the CLI sees it, but the CLI
# collects all expanded paths thanks to the variadic option
codacy-analysis analyze --files **/*.rs

# Combine repeated --files with other flags
codacy-analysis analyze --files "**/*.py" --files "**/*.rs" --tool ruff-0

Shell expansion gotcha

When using globs without quotes, your shell (zsh/bash) expands them first:

• --files **/*.rs works if matching files exist — the shell expands and the CLI receives all expanded paths.
• --files *.rs fails in zsh if no .rs files exist in the current directory, because zsh's default nomatch option raises an error before the CLI runs.

To pass a glob pattern literally (let the CLI match it), always quote it:

# Recommended: quoted glob, works regardless of CWD contents
codacy-analysis analyze --files "**/*.rs"

# Also works: shell expands, CLI collects all expanded paths
codacy-analysis analyze --files **/*.rs

Git-aware scoping

Analyze only the files that matter — changed in a branch, staged for commit, or part of a PR. These flags are mutually exclusive and can be combined with --files for further narrowing.

Analyze staged files

# Perfect for pre-commit hooks
codacy-analysis analyze --staged

Analyze branch changes

# Auto-detects default branch (origin/main or origin/master)
codacy-analysis analyze --diff

# Specify a base branch explicitly
codacy-analysis analyze --diff develop

Analyze pull request files

# Uses gh CLI if available, falls back to git merge-base
codacy-analysis analyze --pr

Combine with --files

When both a git scope and --files are provided, the result is the intersection — only files that match both the git scope and the file patterns are analyzed.

# Only TypeScript files changed in the current branch
codacy-analysis analyze --diff --files "src/**/*.ts"

Registering adapters

Adapter registration lives in the preset package @codacy/analysis-adapters, not in the CLI. At startup src/index.ts calls its registerBuiltinAdapters(), which registers every built-in tool (and the cloud-only descriptors) into the runner's registry. The same preset is used by other embedders (VSCode, MCP).

When adding a new adapter, wire it into the preset — see packages/adapters/CLAUDE.md and packages/tools/CLAUDE.md (step 6):

1. Add the workspace dependency to packages/adapters/package.json
2. Add an entry to builtinAdapterEntries in packages/adapters/src/index.ts
3. Rebuild: pnpm build