@codacy/analysis-cli

Table of Contents

• Overview
• Installation
• Commands
• Usage
• Logging
• 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 | | init | Initialize .codacy/codacy.config.json | | login | Authenticate with the Codacy API and store credentials | | logout | Remove stored Codacy API credentials |

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

# Initialize from Codacy Cloud
codacy-analysis init --remote gh myorg myrepo

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.

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

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