@codacy/analysis-cli

Table of Contents

• Overview
• Installation
• Commands
• Usage
• Configuration file location
• Logging
• Automatic update checks
• Supported tools
• File targeting
• 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, or directory | | 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] | Regenerate .codacy/codacy.config.json using its original init mode | | 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 | | 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

# Regenerate the local config using whichever mode it was first created with
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
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

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

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. Runs discover to detect languages, frameworks, and libraries
2. Selects tools that support the detected languages
3. 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)
4. Applies severity/category filters if provided
5. Respects .codacy.yaml exclude paths if present

Updating an auto config

# Re-runs auto-init with the same filters that were originally used
codacy-analysis update-config

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.

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 |

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/

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

All tool adapters must be imported and registered in src/index.ts:

import myAdapter from "@codacy/tools-my-tool-0";
registerAdapter(myAdapter);

When adding a new adapter:

1. Add the workspace dependency to package.json
2. Import and register in src/index.ts
3. Rebuild: pnpm build