codacy

Glossary: See glossary.md for shared definitions of Codacy concepts (issues, findings, severity, coverage, tools, patterns, etc.).

Codacy provides two CLI tools:

• Analysis CLI (codacy-analysis): Runs static analysis locally without pushing code to Codacy Cloud
• Cloud CLI (codacy): Queries remote Codacy data (repositories, issues, PRs, security findings)

Both share credentials at ~/.codacy/credentials. Logging in with either CLI applies to both.

When to Use

• User wants to analyze code locally without pushing to Codacy Cloud
• Need to run CLI-based linting (ESLint, Ruff, Semgrep, RuboCop)
• Scanning staged changes or setting up local Codacy tooling
• User wants to check code quality metrics on Codacy Cloud
• Need to inspect remote PR analysis results or browse vulnerabilities
• Enabling/disabling tools or searching patterns on Codacy Cloud
• Even if they just say "run codacy" or "check code quality"

Setup

# Install Analysis CLI (local analysis)
npm i -g @codacy/analysis-cli

# Install Cloud CLI (remote queries)
npm install -g @codacy/codacy-cloud-cli

# Verify
codacy-analysis --help
codacy --help

Authentication (optional for local, required for cloud)

# Option 1: Interactive login (shared by both CLIs)
codacy login

# Option 2: Token flag
codacy login --token <your-api-token>

# Option 3: Environment variable
export CODACY_API_TOKEN=<your-api-token>

# Obtain tokens: Codacy > My Account > Access Management
# Remove credentials
codacy logout

Shared session: Both CLIs share ~/.codacy/credentials. Logging in/out with either applies to both.

Local Analysis (Analysis CLI)

The Analysis CLI (codacy-analysis) runs static analysis locally. It detects languages, selects tools, and reports issues — without pushing code to Codacy.

Always use --output-format json for structured output in agentic workflows.

Analysis Workflow

1. Initialize configuration
2. Inspect tool availability (dry-run)
3. Install missing dependencies
4. Run analysis
5. Interpret results

Step 1: Initialize configuration

codacy-analysis init
# Or with remote config:
codacy-analysis init --remote --provider gh --organization my-org --repository my-repo

Step 2: Inspect tool availability

codacy-analysis analyze --inspect --output-format json

# See which tools are ready
codacy-analysis analyze --inspect --output-format json | jq '.capability.ready[] | {toolId, version}'

# See which tools are missing
codacy-analysis analyze --inspect --output-format json | jq '.capability.unavailable[] | {toolId, reason}'

Step 3: Install missing dependencies

codacy-analysis analyze --install-dependencies --output-format json

Step 4: Run analysis

codacy-analysis analyze --output-format json

Step 5: Interpret results

See references/analysis-interpret.md for details.

Cloud Queries (Cloud CLI)

The Cloud CLI (codacy) queries remote Codacy data. Auto-detects provider, organization, and repository from git remote.

# List issues
codacy issues

# Check repository status
codacy repository

# Inspect a pull request
codacy pull-request 42

# Trigger reanalysis and wait
codacy repository --reanalyze-and-wait

Use --output json on any command for machine-readable output.

How Codacy data works

• Data reflects the HEAD commit — issue lists, coverage, and security findings show the latest analyzed commit
• Configuration changes are not instant — enable/disable tools only take effect after next analysis
• Organization standards are enforced — cannot be overridden at repository level

Reanalysis

# Trigger reanalysis and wait for results (preferred)
codacy repository --reanalyze-and-wait
codacy repository -w -o json    # JSON delta report

# Fire-and-forget reanalysis
codacy repository --reanalyze

Filesystem conventions

The analyzed repository is never modified outside of .codacy/.

Common workflows

• Local analysis: See references/analysis-workflows.md
• Cloud queries: See references/cloud-workflows.md
• Cloud commands: See references/cloud-commands.md

Rationalizations

Red Flags

• Ignoring Codacy failures and pushing anyway.
• Suppressing issues as "FalsePositive" without verifying they actually are.
• Running codacy-analysis analyze without the --pr flag on a large codebase (may be slow).
• Using the issue hash for CLI suppressions (requires numeric resultDataId).
• Assuming configuration changes take effect immediately without reanalysis.

See Also

• static-analysis — Generic linter triage across any language
• code-review-assistant — PR review workflow

Troubleshooting

See references/analysis-troubleshooting.md for details.

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.