diff --git a/.github/styles/config/vocabularies/Codacy/accept.txt b/.github/styles/config/vocabularies/Codacy/accept.txt index 8333378248..1a712e4dab 100644 --- a/.github/styles/config/vocabularies/Codacy/accept.txt +++ b/.github/styles/config/vocabularies/Codacy/accept.txt @@ -93,6 +93,7 @@ TSLint TSQLLint unassigns unfollow +unignore vacuumdb Visualforce VSCode diff --git a/docs/codacy-api/api-tokens.md b/docs/codacy-api/api-tokens.md index 5468f5147a..ab1fbd220b 100644 --- a/docs/codacy-api/api-tokens.md +++ b/docs/codacy-api/api-tokens.md @@ -9,6 +9,7 @@ Codacy provides **account** and **repository**-level API tokens that allow you t - [Upload coverage data](../coverage-reporter/index.md) to Codacy - Upload to Codacy the results of [running client-side analysis tools](../repositories-configure/local-analysis/client-side-tools.md) - [Authenticate when using the Codacy API](using-the-codacy-api.md#authenticating-requests) +- [Authenticate with the Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication) The sections below provide details about the two types of API tokens and instructions on how to generate and revoke them. diff --git a/docs/codacy-api/using-the-codacy-api.md b/docs/codacy-api/using-the-codacy-api.md index 51e2210f25..a2cf5a4e54 100644 --- a/docs/codacy-api/using-the-codacy-api.md +++ b/docs/codacy-api/using-the-codacy-api.md @@ -2,6 +2,9 @@ The Codacy API allows you to programmatically retrieve and analyze data from Codacy and perform a few configuration changes. +!!! tip + Looking for a higher-level interface? The [Codacy Cloud CLI](../codacy-cloud-cli/index.md) wraps the Codacy API with ready-to-use commands for managing repositories, issues, security findings, and pull requests from your terminal. + Codacy supports two API versions but we strongly recommend using the new API v3 when possible since it's the version being actively developed. Import the OpenAPI 2.0 definition provided below into your development tools to help bootstrap your integration with Codacy. diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md new file mode 100644 index 0000000000..5d77c37a37 --- /dev/null +++ b/docs/codacy-cloud-cli/index.md @@ -0,0 +1,228 @@ +--- +description: Install and use the Codacy Cloud CLI to manage your repositories, issues, security findings, pull requests, and tool configurations directly from your terminal. +--- + +# 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 [Codacy Skills](#install-the-codacy-skills) to interact with your Codacy data in plain language directly from your AI assistant. + +
+ +## Installation + +Install the CLI using npm: + +```bash +npm install -g @codacy/codacy-cloud-cli +``` + +Alternatively, you can build from source. See the [GitHub repository](https://github.com/codacy/codacy-cloud-cli) for instructions. + +## Authentication {: id="authentication"} + +Run `codacy login` and enter your API token when prompted. Codacy stores your credentials encrypted at `~/.codacy/credentials`. + +```bash +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. + +Get your API token under **My Account > Access Management > API Tokens** in Codacy. See [API tokens](../codacy-api/api-tokens.md) for details. + +To remove your stored credentials, run `codacy logout`. + +## Install the Codacy Skills {: id="install-the-codacy-skills"} + +The [Codacy Skills](https://github.com/codacy/codacy-skills) let your AI assistant interact with your Codacy data in plain language, without needing to remember command syntax: + +- "Show me the critical security findings in my org" +- "What issues were introduced in PR #42?" +- "Ignore all false positives in the last pull request" + +**Claude Code** (recommended): + +```bash +claude plugin marketplace add codacy/codacy-skills +claude plugin install codacy-skills@codacy +``` + +**Claude.ai**: download the skill folder, zip it, and upload it under **Settings > Capabilities > Skills**. + +If you use a different AI assistant, visit the [Codacy Skills repository](https://github.com/codacy/codacy-skills) to install the skills directly. + +## What you can do + +All commands follow the same pattern: + +```bash +codacy [repository] [options] +``` + +Where `` is `gh` (GitHub), `gl` (GitLab), or `bb` (Bitbucket). + +Use `--output json` on any command to get machine-readable output for scripting. + +### Manage your repositories + +```bash +# 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: + +```bash +# 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: + +```bash +codacy issues gh my-org my-repo --severities Critical --ignore --ignore-reason FalsePositive +``` + +Inspect a single issue and ignore or remove the ignore flag: + +```bash +codacy issue gh my-org my-repo --ignore --ignore-reason AcceptedUse +``` + +### Investigate security findings + +List findings for an organization or a specific repository, with optional filters: + +```bash +# 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: + +```bash +codacy findings gh my-org --statuses Overdue,DueSoon +``` + +### Inspect pull requests + +```bash +# 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 + +```bash +# 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: + +```bash +# 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: + +```bash +# 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](https://cli.github.com/) alongside the Codacy CLI to incorporate feedback from the [AI Reviewer](../repositories-configure/integrations/github-integration.md#ai-reviewer), which posts analysis summaries as PR comments: + +```bash +# 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. + +### 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: + +{% raw %} +```yaml +- 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 +``` +{% endraw %} + +From there, pipe the JSON output to `jq`, post results as PR comments with the [GitHub CLI](https://cli.github.com/), open issues, send Slack notifications — whatever fits your workflow. + +## See also + +- [Codacy Cloud CLI on GitHub](https://github.com/codacy/codacy-cloud-cli) +- [Codacy Skills on GitHub](https://github.com/codacy/codacy-skills) +- [API tokens](../codacy-api/api-tokens.md) +- [Using the Codacy API](../codacy-api/using-the-codacy-api.md) +- [GitHub integration and AI Reviewer](../repositories-configure/integrations/github-integration.md#ai-reviewer) diff --git a/docs/repositories/issues.md b/docs/repositories/issues.md index 3fc99029fb..037fab79fb 100644 --- a/docs/repositories/issues.md +++ b/docs/repositories/issues.md @@ -5,7 +5,7 @@ The **Issues page** lists all the issues that Codacy detected in your repository By default, the page lists the issues on the main branch of your repository but if you have [more than one branch enabled](../repositories-configure/managing-branches.md) you can use the drop-down list at the top of the page to display issues on other branches. !!! note - [You can use the Codacy API](../codacy-api/examples/obtaining-current-issues-in-repositories.md) to generate reports or obtain information about the current issues in your repositories in a more flexible way. + [You can use the Codacy API](../codacy-api/examples/obtaining-current-issues-in-repositories.md) to generate reports or obtain information about the current issues in your repositories in a more flexible way. You can also list, filter, and manage issues directly from your terminal with the [Codacy Cloud CLI](../codacy-cloud-cli/index.md). ![Issues page](images/issues.png) diff --git a/docs/repositories/pull-requests.md b/docs/repositories/pull-requests.md index ba3776b390..e0aad11c72 100644 --- a/docs/repositories/pull-requests.md +++ b/docs/repositories/pull-requests.md @@ -13,6 +13,9 @@ By default, the page lists open pull requests, but you can click the **Closed** Click a specific pull request to see detailed information about the code quality changes introduced by that pull request. +!!! tip + You can also inspect pull request analysis, view an annotated diff, and manage issues directly from your terminal using the [Codacy Cloud CLI](../codacy-cloud-cli/index.md). + ![Pull request detail](images/pull-requests-detail.png) The next sections describe each area of the pull request detail page. diff --git a/mkdocs.yml b/mkdocs.yml index eaeb837b5d..6a9c7d229e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -574,6 +574,8 @@ nav: - codacy-guardrails/codacy-guardrails-limitations.md - codacy-guardrails/codacy-guardrails-troubleshooting.md - codacy-guardrails/codacy-guardrails-faq.md + - Codacy Cloud CLI: + - codacy-cloud-cli/index.md - Codacy AI: - codacy-ai/codacy-ai.md - Repositories on Codacy: