Skip to content

Codacy Cloud CLI#

The Codacy Cloud CLI gives you a fast terminal interface to your Codacy data. Add repositories, review issues, investigate security findings, inspect pull requests, and configure tools—all without opening a browser.

Pair it with the Codacy Skills to interact with your Codacy data in plain language directly from your AI assistant.

Installation#

Install the CLI using npm:

npm install -g @codacy/codacy-cloud-cli

Alternatively, you can build from source. See the GitHub repository for instructions.

Authentication#

The CLI accepts both account API tokens and repository API tokens.

Account API tokens#

Run codacy login and enter the token when prompted. Codacy stores your credentials encrypted at ~/.codacy/credentials. Get the token under My Account > Access Management > API Tokens in Codacy.

codacy login

For non-interactive environments such as CI/CD pipelines, set the CODACY_API_TOKEN environment variable instead. This takes precedence over stored credentials.

To remove your stored credentials, run codacy logout.

Repository API tokens#

Use the option --repository-token or set the CODACY_PROJECT_TOKEN environment variable. You can't use a repository API token with codacy login.

codacy issues gh my-org my-repo --repository-token <token>

Prefer a repository API token in CI/CD pipelines: unlike an account API token, it only grants access to a single repository. Because it authorizes a limited set of operations, commands outside that set fail immediately instead of contacting Codacy. The command codacy repository works, but omits the pull request and coverage data, listing what it skipped under unavailable in its JSON output.

When more than one credential is available, the CLI uses the first of the option --repository-token, CODACY_PROJECT_TOKEN, CODACY_API_TOKEN, and the credentials stored by codacy login.

Install the Codacy Skills#

The Codacy Skills let your AI assistant interact with your Codacy data in plain language, without needing to remember command syntax. The codacy-cloud-cli skill covers this CLI; five other skills cover local analysis, pull request review, configuration, and coverage.

For Claude Code:

claude plugin marketplace add codacy/codacy-skills
claude plugin install codacy-skills@codacy

See Codacy Skills for the other assistants.

What you can do#

All commands follow the same pattern:

codacy <command> <provider> <organization> [repository] [options]

Where <provider> is gh (GitHub), gl (GitLab), or bb (Bitbucket).

Use --output json on any command to get machine-readable output for scripting.

Manage your repositories#

# List repositories in an organization
codacy repositories gh my-org

# Get a full overview of a specific repository
codacy repository gh my-org my-repo

You can also add or remove repositories, follow/unfollow them, link coding standards, and request reanalysis. Use flags like --add, --remove, and --reanalyze on the same command.

Review code issues#

List and filter issues by severity, category, tool, author, or branch:

# List all issues
codacy issues gh my-org my-repo

# Filter by severity and category
codacy issues gh my-org my-repo --severities Critical,High --categories Security

# Filter by branch or author
codacy issues gh my-org my-repo --branch feature/my-feature --authors dev@example.com

# Show counts only
codacy issues gh my-org my-repo --overview

Ignore all issues matching your current filters in one step:

codacy issues gh my-org my-repo --severities Critical --ignore --ignore-reason FalsePositive

Inspect a single issue and ignore or remove the ignore flag:

codacy issue gh my-org my-repo <issueId> --ignore --ignore-reason AcceptedUse

Investigate security findings#

List findings for an organization or a specific repository, with optional filters:

# Organization-wide findings
codacy findings gh my-org

# Per-repository, filtered by severity
codacy findings gh my-org my-repo --severities Critical,High

# Filter by scan type
codacy findings gh my-org --scan-types SAST,Secrets
codacy findings gh my-org --scan-types SCA,IaC --severities High

Findings are tracked with statuses like Overdue, OnTrack, and DueSoon. Use --statuses to filter accordingly:

codacy findings gh my-org --statuses Overdue,DueSoon

Check affected functions on vulnerable dependencies#

For SCA issues and findings linked to an advisory (CVE or GHSA) where Codacy has identified the affected functions, issues, issue, findings, finding, and pull-request show that information alongside the regular output.

List and card views show a compact summary line:

codacy issues gh my-org my-repo

Vulnerable functions: Unmarshal, UnmarshalOptions.Unmarshal (+1 more)

Detail views (codacy issue, codacy pull-request ... --issue, and codacy finding when the finding has no linked Codacy issue) show the full block instead:

codacy issue gh my-org my-repo <issueId>

Vulnerable Functions (CVE-2024-24786)
Published: 2024-03-08

  • Unmarshal
  • UnmarshalOptions.Unmarshal

This information is also included when using --output json.

Note

Not every advisory lists specific affected functions — this section only appears when Codacy has identified them.

Manage container images#

List the container images with SBOMs uploaded to an organization, inspect an image's tags, upload an SBOM, and delete tags you no longer need. These commands require an account API token, because they read organization-level data.

Note

Available from Codacy Cloud CLI 1.12.1.

# List the images in an organization, with their latest tag
codacy images gh my-org

# List an image's tags, with environment, repository, and analysis dates
codacy image gh my-org my-service

# Show a single tag
codacy image gh my-org my-service --tag 1.2.3

Both commands return 100 results by default. Use --limit to raise that, up to 1000.

Upload an SBOM your pipeline already produced, in SPDX or CycloneDX format:

codacy image gh my-org my-service --tag 1.2.3 --upload ./sbom.json

# Record where the image runs and which repository it belongs to
codacy image gh my-org my-service --tag prod --upload ./sbom.json \
  --environment production --repository my-repo

The file is checked before the request, so a wrong path or an empty file fails immediately.

Delete a single tag, or the whole image:

# One tag
codacy image gh my-org my-service --tag 1.2.3 --delete

# Every tag of the image
codacy image gh my-org my-service --delete

Keep container image tags under the organization limit#

An organization can hold 1000 image tags in total. Once it reaches that limit, Codacy stops accepting image tags it hasn't seen before, so a pipeline that uploads a new tag on every release stops being scanned. See how tagging affects your findings.

--keep-latest deletes the older tags of an image, keeping the most recently uploaded ones. Run it as the cleanup step of a release pipeline, before the upload, so that the space is freed before the new tag needs it:

# Show what would be deleted, delete nothing
codacy image gh my-org my-service --delete --keep-latest 10 --dry-run

# Delete, without prompting — for CI
codacy image gh my-org my-service --delete --keep-latest 10 --skip-confirmation

Deletes run one at a time and continue past failures, so a partial cleanup still frees space. Under --output json the command emits a single object listing the tags in deleted and the ones that failed in failures, and exits non-zero if any tag failed.

Important

The organization limit counts image-and-tag pairs, while --keep-latest applies per image. Keeping 10 tags across 212 images is 2120 tags against a limit of 1000. The command warns when the number you ask for would exceed the limit across every image in the organization, and says what the limit allows per image instead.

List and filter pull requests#

# List open pull requests (default)
codacy pull-requests gh my-org my-repo

# Filter by title or author handle, and by base branch
codacy pull-requests gh my-org my-repo --search "fix flaky" --base main

# List closed pull requests instead
codacy pull-requests gh my-org my-repo --state closed

pull-requests (alias prs) mirrors the Pull Requests page filters: --search/-q matches the title or author handle, and --base/-B matches the pull request's base branch.

Inspect pull requests#

# Get the full analysis summary
codacy pull-request gh my-org my-repo 42

# View an annotated diff with new issues and coverage changes
codacy pull-request gh my-org my-repo 42 --diff

# Ignore all false positives in bulk
codacy pull-request gh my-org my-repo 42 --ignore-all-false-positives

# Trigger reanalysis of the HEAD commit
codacy pull-request gh my-org my-repo 42 --reanalyze

Configure tools and patterns#

# List all tools and see which are enabled
codacy tools gh my-org my-repo

# Enable or disable a tool
codacy tool gh my-org my-repo eslint --enable
codacy tool gh my-org my-repo pylint --disable

# Import tool configuration from .codacy/codacy.config.json
codacy tools gh my-org my-repo --import

Bulk-enable or bulk-disable patterns, or set a parameter on a specific pattern:

# Bulk-enable or bulk-disable by category or severity
codacy patterns gh my-org my-repo eslint --categories Security --enable-all
codacy patterns gh my-org my-repo eslint --severities Minor --disable-all

# Set a parameter on a specific pattern
codacy pattern gh my-org my-repo eslint max-len --enable --parameter max=120

Note

Tool and pattern changes take effect after the next analysis. Use --reanalyze on the repository or pull request command to trigger one immediately.

Example workflows#

Terminal-first PR review#

Before merging, check the full analysis of a pull request (issues, coverage delta, and security findings) without leaving the terminal:

# See the PR summary
codacy pull-request gh my-org my-repo 42

# See an annotated diff with new issues inline
codacy pull-request gh my-org my-repo 42 --diff

Combine with the GitHub CLI and AI Reviewer#

Use the GitHub CLI alongside the Codacy CLI to incorporate feedback from the AI Reviewer, which posts analysis summaries as PR comments:

# Read AI Reviewer comments on the PR
gh pr view 42 --comments

# Cross-reference with the Codacy annotated diff
codacy pull-request gh my-org my-repo 42 --diff

Feed both outputs to Claude Code (with the Codacy skill installed) to decide what to fix and apply it directly.

Audit affected functions across one or multiple repositories#

The affected functions shown for a single finding tell you whether one vulnerable dependency is reachable. To check vulnerable dependencies across one or multiple repositories at once, install the Codacy Skills. The codacy-cloud-cli skill already knows how to pull SCA findings for one or more repositories, tell direct from transitive dependencies apart, and check whether the affected functions are actually used.

With the skill installed and local checkouts of the repositories you want to cover, ask your assistant directly, for example:

Audit vulnerable dependencies in <repo-one> and <repo-two>. For every SCA finding where Codacy has identified affected functions, tell me whether the dependency is direct or transitive, search my local checkout for calls to those functions, and report back per repository — used/not used, chain status, and your recommendation — before ignoring anything as NotExploitable or applying an upgrade.

Note

Only include repositories you have checked out locally — the assistant can't verify reachability for a repository it can't search. It's also a signal, not a guarantee: review the recommendation before upgrading a dependency or ignoring a finding.

Use the CLI in CI#

The CLI works in any CI environment. Set CODACY_API_TOKEN as a secret and install the CLI as a step:

- name: Install Codacy Cloud CLI
  run: npm install -g @codacy/codacy-cloud-cli

- name: Run Codacy CLI
  env:
    CODACY_API_TOKEN: ${{ secrets.CODACY_API_TOKEN }}
  run: codacy issues gh ${{ github.repository_owner }} my-repo --output json

From there, pipe the JSON output to jq, post results as PR comments with the GitHub CLI, open issues, send Slack notifications — whatever fits your workflow.

See also#

Was this page helpful?

Your feedback helps us improve the documentation.

Edit this page on GitHub Contact support