@codacy/analysis-cli

Table of Contents

• Overview
• Installation
• Commands
• Usage
• upload — send analysis results to Codacy
• init --remote / update-config — repository token
• init --auto — stack-aware initialization
• Configuration file location
• Logging
• 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 | | 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

# 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>

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

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.

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.

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