From 1f6c6e02c0574db3bd70ed38c88fbfdbfe66cf0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 10 Sep 2026 14:57:20 +0100 Subject: [PATCH 1/3] docs: add Codacy Analysis CLI page under Codacy CLIs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a reference page for @codacy/analysis-cli (the codacy-analysis command), which had no page of its own — its install and init steps lived inside the Codacy Guardrails getting-started page, and other pages linked to that anchor. Every command, flag, and environment variable on the page is checked against CLI 0.23.0 (codacy-analysis --help, codacy-analysis info, and the README from the package tarball). Behaviors that neither the help output nor the README states correctly were verified by running the CLI: - exit codes are 0 no issues / 1 issues found / 2 invalid flag combination; an unavailable tool, even with --fail-if-missing, still exits 0, so --fail-if-missing does not fail a CI job - --inspect, --install-dependencies and --fail-if-missing are a three-way mutual exclusion, not two-way - analyze reads the excludes recorded in codacy.config.json, never .codacy.yaml directly, so editing that file changes nothing until init or update-config runs - config --merge keeps the destination's metadata.source, so merging a --remote config into an --auto one stays incremental under update-config The page links the npm package rather than the source repository, which is private. Repoints the references that pointed at the Guardrails anchor or at npm, and cross-links the Codacy Cloud CLI and Codacy Skills pages. Co-Authored-By: Claude Opus 5 --- docs/codacy-analysis-cli/index.md | 341 ++++++++++++++++++ docs/codacy-cloud-cli/index.md | 1 + .../codacy-guardrails-faq.md | 2 +- .../codacy-guardrails-getting-started.md | 4 +- .../codacy-guardrails-troubleshooting.md | 2 +- docs/codacy-skills/index.md | 6 +- .../local-analysis/client-side-tools.md | 2 +- .../local-analysis/running-eslint.md | 2 +- mkdocs.yml | 1 + 9 files changed, 352 insertions(+), 9 deletions(-) create mode 100644 docs/codacy-analysis-cli/index.md diff --git a/docs/codacy-analysis-cli/index.md b/docs/codacy-analysis-cli/index.md new file mode 100644 index 0000000000..e1b9a9127b --- /dev/null +++ b/docs/codacy-analysis-cli/index.md @@ -0,0 +1,341 @@ +--- +description: Install and use the Codacy Analysis CLI to run Codacy's analyzers on your own machine, scope analysis to changed files, and upload the results to Codacy. +--- + +# Codacy Analysis CLI + +The Codacy Analysis CLI runs Codacy's analyzers locally. It detects your stack, configures the tools that fit it, reports issues in your terminal, and optionally uploads the results to Codacy. Your code never leaves your machine unless you run [`upload`](#upload-results-to-codacy). + +Pair it with the [Codacy Skills](../codacy-skills/index.md) to run local analysis in plain language from your AI assistant. + +!!! note + The Codacy Analysis CLI (`codacy-analysis`) and the [Codacy Cloud CLI](../codacy-cloud-cli/index.md) (`codacy`) are different tools. Use `codacy-analysis` to run analyzers on your machine, and `codacy` to query the data Codacy already holds. + +## Requirements + +- Node.js 20 or later +- git — the CLI resolves paths against the repository root, and the [git-aware flags](#scope-the-analysis) read your branch and staging area + +## Installation + +The CLI is published on npm and installs the same way on macOS, Linux, and Windows: + +```bash +npm i -g @codacy/analysis-cli +``` + +The Codacy IDE extension bundles its own copy of the analyzer and doesn't put the `codacy-analysis` command on your `PATH`. Install the package above if you want to run the CLI yourself, and see [Codacy Guardrails](../codacy-guardrails/codacy-guardrails-getting-started.md) for the extension. + +To confirm the install and see which analyzers are available on your machine, with the version and origin of each: + +```bash +codacy-analysis info +``` + +## Authentication {: id="authentication"} + +Local analysis works without authentication. You only need a token to pull a repository's configuration from Codacy with [`init --remote`](#configure-your-repository), or to [upload results](#upload-results-to-codacy). + +Run `codacy-analysis login` and enter an [account API token](../codacy-api/api-tokens.md#account-api-tokens) when prompted. Get the token under **My Account > Access Management > API Tokens** in Codacy. + +```bash +codacy-analysis login +``` + +For non-interactive environments such as CI/CD pipelines, set the `CODACY_API_TOKEN` environment variable instead. To remove your stored credentials, run `codacy-analysis logout`. + +The Codacy Analysis CLI and the [Codacy Cloud CLI](../codacy-cloud-cli/index.md) share the same credentials at `~/.codacy/credentials`, so a single login covers both. + +A [repository API token](../codacy-api/api-tokens.md#repository-api-tokens) works for the three commands that accept one — `init --remote`, `update-config`, and `upload`. Prefer it in CI/CD pipelines, because it only grants access to a single repository, and it wins over an account token when both are available: + +```bash +codacy-analysis init --remote gh my-org my-repo --repository-token +``` + +{% include-markdown "../assets/includes/api-token-warning.md" %} + +## Codacy Self-hosted + +Point the CLI at your own instance with `CODACY_API_BASE_URL`. The `upload` command talks to a different endpoint from the rest of the CLI and reads its own variable, so set both: + +```bash +export CODACY_API_BASE_URL= +export CODACY_RESULTS_API_BASE_URL= +``` + +## Configure your repository {: id="configure-your-repository"} + +`init` writes `.codacy/codacy.config.json`, which records the tools and patterns that run. `analyze` reads it, so run `init` once per repository before analyzing. + +Which mode you pick decides where the configuration comes from: + +```bash +# Detect languages from the tool configuration files already in the repository +codacy-analysis init + +# Detect the stack and select patterns per detected framework +codacy-analysis init --auto + +# Same, narrowed to specific severities and categories +codacy-analysis init --auto Critical,High,Security + +# Add Codacy's default patterns on top — no token needed +codacy-analysis init --default + +# Fetch the configuration of a repository on Codacy, so local results match it +codacy-analysis init --remote gh my-org my-repo +``` + +The modes are mutually exclusive. `init --remote` takes your provider (`gh` for GitHub, `gl` for GitLab, or `bb` for Bitbucket), organization, and repository name, and needs [authentication](#authentication); the others don't. If you want both the stack `--auto` detects and the rules your repository enforces on Codacy, see [analyzing against your stack and your Codacy Cloud rules](#merge-auto-and-remote). + +Alongside it, `init` writes `codacy.config.baseline.json`, which records what the generator last produced, and a `.codacy/.gitignore` that keeps the derived `generated/` folder out of version control. Commit both JSON files so your team analyzes against the same configuration. + +To bring an existing configuration up to date with your current stack: + +```bash +codacy-analysis update-config +``` + +By default this is incremental: patterns you disabled stay disabled and your parameters and excludes survive, while tools and patterns for newly detected languages and frameworks are added. Add `--reset` to regenerate from scratch and discard your edits. Configurations created with `init --remote` are always re-synced in full, because Codacy Cloud is authoritative for them. + +!!! note + `init` and `update-config` read the `exclude_paths` in your [Codacy configuration file](../repositories-configure/codacy-configuration-file.md) and record them in `codacy.config.json`, which is where `analyze` reads them from. Editing `.codacy.yaml` on its own doesn't change what `analyze` covers — run `update-config` afterward. + +## Run an analysis + +With the configuration in place, analyze the repository: + +```bash +codacy-analysis analyze +``` + +Some analyzers ship inside the npm package; the rest are downloaded on demand. `--install-dependencies` fetches the missing ones into `~/.codacy`, where they're reused across every repository on the machine, and then runs the analysis: + +```bash +codacy-analysis analyze --install-dependencies +``` + +To see which analyzers are ready and which are missing without running anything, use `--inspect`: + +```bash +codacy-analysis analyze --inspect +``` + +`--inspect`, `--install-dependencies`, and `--fail-if-missing` are mutually exclusive — passing two of them exits `2` without analyzing. + +`analyze` prints text by default. Use `--output-format` for machine-readable output, and `--output` to write it to a file: + +```bash +codacy-analysis analyze --output-format json +codacy-analysis analyze --output-format sarif --output results.sarif +``` + +The command exits `0` when it finds no issues and `1` when it finds issues, which is what makes it usable as a gate in CI. An invalid combination of flags exits `2`. + +A tool the CLI can't run is reported as unavailable and the rest of the analysis continues. `--fail-if-missing` adds an explicit error to the report for those tools, but it doesn't change the exit code, so it doesn't by itself fail a job. + +### Restrict to specific tools + +`--tool` is repeatable and matches the tool IDs recorded in `.codacy/codacy.config.json`. Only tools listed there run: + +```bash +codacy-analysis analyze --tool ESLint9 --tool Ruff +``` + +The IDs are case-sensitive and don't always match the tool's display name — Pylint is `PyLintPython3`, and Opengrep is `Semgrep`. Run `codacy-analysis info` for the full table of names, IDs, and versions. + +### Scope the analysis {: id="scope-the-analysis"} + +Analyze a single file, a subdirectory, or a glob by passing it as the argument. Quote globs so your shell doesn't expand them first: + +```bash +codacy-analysis analyze ./src/main.py +codacy-analysis analyze ./src/api/ +codacy-analysis analyze "src/**/*.ts" +``` + +`--files` takes several paths or globs at once and can be repeated: + +```bash +codacy-analysis analyze --files src/a.py src/b.py +codacy-analysis analyze --files "**/*.py" --files "**/*.rs" +``` + +The git-aware flags scope the run to what changed. They're mutually exclusive: + +```bash +# Files in the git staging area — the flag to use in a pre-commit hook +codacy-analysis analyze --staged + +# Files changed against the default branch, or against a base branch you name +codacy-analysis analyze --diff +codacy-analysis analyze --diff develop + +# Files in the current pull request +codacy-analysis analyze --pr +``` + +Combining a git flag with `--files` analyzes the intersection of the two. + +### Tune the run + +```bash +# Run up to four tools at a time +codacy-analysis analyze --parallel-tools 4 + +# Raise the per-tool timeout in milliseconds +codacy-analysis analyze --tool-timeout 1800000 + +# Log every tool invocation to stderr +codacy-analysis analyze --log-level debug +``` + +Logs are written to `~/.codacy/logs/` as JSON lines and rotate at 10 MB. Add `--no-log` to disable file logging, which is worth doing in CI. + +## Upload results to Codacy {: id="upload-results-to-codacy"} + +`upload` sends a report produced by `analyze` to Codacy and attaches its issues to a commit. Only reports from this CLI are accepted, because they already carry Codacy pattern IDs. + +```bash +codacy-analysis analyze --output-format sarif --output results.sarif +codacy-analysis upload results.sarif --repository-token +``` + +The commit defaults to your current git `HEAD`. Pass `--commit` to attach the results elsewhere. + +With an account API token instead of a repository API token, name the repository as well. `upload` falls back to the coordinates stored by `init --remote` when you omit them: + +```bash +codacy-analysis upload results.sarif --repository gh my-org my-repo --commit +``` + +!!! tip + For Codacy to wait for these results before it resumes analyzing your commits, enable **Run analysis on your build server** on your repository **Settings**, tab **General**, **Repository analysis on your server**. + +## Inspect your stack + +`discover` reports the languages, frameworks, libraries, and notable files the CLI finds, which is what `init --auto` bases its selection on: + +```bash +codacy-analysis discover +codacy-analysis discover --output-format json +``` + +It applies your `exclude_paths` by default. Add `--no-exclude` to see the unfiltered scan. + +## Combine configuration files + +`config` performs set operations on the tools and patterns of two configuration files and writes the result to the destination, leaving the source untouched. Use it to keep a configuration synced from Codacy Cloud while testing a variant beside it: + +```bash +# Union of both files +codacy-analysis config --merge --source .codacy/extra.json + +# Only what both files have in common +codacy-analysis config --intersect --source a.json --dest b.json + +# What the destination has and the source doesn't +codacy-analysis config --diff --source baseline.json --dest .codacy/codacy.config.json +``` + +Exactly one operation is required, and `--source` and `--dest` can't both fall back to the same default file. `init`, `analyze`, and `update-config` all accept `--config-file ` to read or write a configuration outside the default location. + +## Common workflows + +### Analyze against your stack and your Codacy Cloud rules {: id="merge-auto-and-remote"} + +`init --auto` and `init --remote` answer different questions. `--auto` picks tools and patterns from what it finds in the repository, down to the framework: React patterns switch on only when React is a dependency. `--remote` gives you the rules your repository already enforces on Codacy Cloud, including ones no local configuration file mentions. Neither set contains the other, so choosing one means giving something up. + +`config` lets you keep both. Write the Codacy Cloud configuration to a second file, then fold it into the detected one: + +```bash +codacy-analysis init --auto +codacy-analysis init --remote gh my-org my-repo --config-file .codacy/remote.json +codacy-analysis config --merge --source .codacy/remote.json +``` + +`--merge` writes the union of the two to `.codacy/codacy.config.json` and reports what came out: + +```text +✔ merge complete: 16 tool(s), 1793 pattern(s) written to .codacy/codacy.config.json +``` + +Swap `--merge` for `--intersect` to go the other way and keep only what both configurations agree on. That lands well below either input, and it's the direction to take when a merge reports more than you're willing to act on. + +The merged file keeps `source: auto` in its metadata, so [`update-config`](#configure-your-repository) still works on it: newly detected tools are added, and the patterns you merged in from Codacy Cloud stay put. + +!!! note + Merging copies the Codacy Cloud rules once. `update-config` re-reads your stack, but it doesn't go back to Codacy for a configuration whose `source` is `auto` — so when the rules change on Codacy Cloud, re-run `init --remote --config-file .codacy/remote.json` and merge again. + +### Scan a repository that isn't on Codacy + +No token, no account, and nothing leaves the machine: + +```bash +codacy-analysis init --auto +codacy-analysis analyze --install-dependencies +``` + +### Check your own changes before you commit + +```bash +codacy-analysis analyze --staged +``` + +This exits `1` when it finds anything, which is all a pre-commit hook needs to block the commit. Add `--tool` to keep the hook to the analyzers that matter for the files you touch. + +### Reproduce what Codacy Cloud sees + +```bash +codacy-analysis login +codacy-analysis init --remote gh my-org my-repo +codacy-analysis analyze --install-dependencies +``` + +Here `update-config` re-syncs the configuration in full rather than incrementally, because Codacy Cloud is authoritative for it. Local edits to the file are discarded, which is the trade for staying in step with the UI. + +## Run behind a proxy + +All outbound requests — Codacy API calls and analyzer downloads alike — honor the standard proxy variables: + +```bash +export HTTPS_PROXY=http://proxy.corp:8080 +export NO_PROXY=app.codacy.com,.internal +export SSL_CERT_FILE=/path/to/corporate-ca.pem +``` + +Trust your organization's CA through `SSL_CERT_FILE` or `NODE_EXTRA_CA_CERTS` rather than disabling TLS verification. A misconfigured bundle fails with an explicit error. + +The update-available check uses a separate network stack that ignores these variables. Behind a strict proxy, turn it off with `CODACY_DISABLE_UPDATE_CHECK=1`. + +## Use the CLI in CI + +Install the CLI as a step and pass a repository API token as a secret: + +{% raw %} +```yaml +- name: Install Codacy Analysis CLI + run: npm i -g @codacy/analysis-cli + +- name: Analyze and upload + env: + CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }} + run: | + codacy-analysis init --remote gh ${{ github.repository_owner }} my-repo + codacy-analysis analyze --install-dependencies --no-log \ + --output-format sarif --output results.sarif + codacy-analysis upload results.sarif +``` +{% endraw %} + +To gate a pull request on the analysis rather than only reporting it, drop the `upload` step and let the exit code of `analyze --diff` fail the job. + +## See also + +- [Codacy Analysis CLI on npm](https://www.npmjs.com/package/@codacy/analysis-cli) +- [Codacy Cloud CLI](../codacy-cloud-cli/index.md) +- [Codacy Skills](../codacy-skills/index.md) +- [Codacy Guardrails](../codacy-guardrails/codacy-guardrails-getting-started.md) +- [Supported languages and tools](../getting-started/supported-languages-and-tools.md) +- [Codacy configuration file](../repositories-configure/codacy-configuration-file.md) +- [API tokens](../codacy-api/api-tokens.md) diff --git a/docs/codacy-cloud-cli/index.md b/docs/codacy-cloud-cli/index.md index 2f48f7cefc..daa88d2d16 100644 --- a/docs/codacy-cloud-cli/index.md +++ b/docs/codacy-cloud-cli/index.md @@ -289,6 +289,7 @@ From there, pipe the JSON output to `jq`, post results as PR comments with the [ ## See also - [Codacy Cloud CLI on GitHub](https://github.com/codacy/codacy-cloud-cli) +- [Codacy Analysis CLI](../codacy-analysis-cli/index.md) - [Codacy Skills](../codacy-skills/index.md) - [API tokens](../codacy-api/api-tokens.md) - [Using the Codacy API](../codacy-api/using-the-codacy-api.md) diff --git a/docs/codacy-guardrails/codacy-guardrails-faq.md b/docs/codacy-guardrails/codacy-guardrails-faq.md index 6ad532921c..d254a59322 100644 --- a/docs/codacy-guardrails/codacy-guardrails-faq.md +++ b/docs/codacy-guardrails/codacy-guardrails-faq.md @@ -34,7 +34,7 @@ Codacy Guardrails isn't a large language model, but an IDE extension that uses a ## When I change some analysis configuration in the UI, is it automatically applied to Guardrails? Not immediately, but you don't have to do anything special either. For a repository connected to Codacy Cloud, Guardrails re-syncs your local configuration in the background whenever you add a new file to the repository, pulling a fresh copy of your patterns from Codacy Cloud. Changes you make in the UI are picked up on that next sync. -To force the sync right away, you can run the standalone [Codacy Analysis CLI](codacy-guardrails-getting-started.md#install-cli) in your repository: +To force the sync right away, you can run the standalone [Codacy Analysis CLI](../codacy-analysis-cli/index.md) in your repository: ``` bash npm i -g @codacy/analysis-cli diff --git a/docs/codacy-guardrails/codacy-guardrails-getting-started.md b/docs/codacy-guardrails/codacy-guardrails-getting-started.md index de5e4117a0..ee4505b6d1 100644 --- a/docs/codacy-guardrails/codacy-guardrails-getting-started.md +++ b/docs/codacy-guardrails/codacy-guardrails-getting-started.md @@ -73,7 +73,7 @@ It will create a folder in your local repository called **.codacy** with all nee - `codacy.config.json` and `codacy.config.baseline.json`: which built-in scanners and rules run on your repository - `generated/`: the per-scanner configuration files derived from them at analysis time -These files belong to the [Codacy Analysis CLI](https://www.npmjs.com/package/@codacy/analysis-cli) that the extension bundles, and the extension writes and updates them for you. To change which rules run, [customize them on Codacy Cloud](codacy-guardrails-how-to-configure-rules.md) rather than editing these files. +These files belong to the [Codacy Analysis CLI](../codacy-analysis-cli/index.md) that the extension bundles, and the extension writes and updates them for you. To change which rules run, [customize them on Codacy Cloud](codacy-guardrails-how-to-configure-rules.md) rather than editing these files. !!! note Commit `codacy.config.json` and `codacy.config.baseline.json` so your team analyzes against the same configuration. The CLI already keeps the `generated/` subfolder out of version control for you, via a `.codacy/.gitignore` file. @@ -109,7 +109,7 @@ You can later generate the instructions manually from the Guardrails section of #### Download -The Codacy Analysis CLI is distributed as an npm package and installs the same way on macOS, Linux, and Windows: +The Codacy Analysis CLI is distributed as an npm package and installs the same way on macOS, Linux, and Windows. See [Codacy Analysis CLI](../codacy-analysis-cli/index.md) for its full command reference. ```bash npm i -g @codacy/analysis-cli diff --git a/docs/codacy-guardrails/codacy-guardrails-troubleshooting.md b/docs/codacy-guardrails/codacy-guardrails-troubleshooting.md index f3eaa41eef..3cbe5029bc 100644 --- a/docs/codacy-guardrails/codacy-guardrails-troubleshooting.md +++ b/docs/codacy-guardrails/codacy-guardrails-troubleshooting.md @@ -4,7 +4,7 @@ ### Diagnosing local analysis issues -Whenever local analysis or Guardrails scanning isn't behaving as expected, the standalone [Codacy Analysis CLI](codacy-guardrails-getting-started.md#install-cli) can tell you the state of your setup: your authentication status, your system information, and every analysis tool it knows about, along with whether each one is installed locally. +Whenever local analysis or Guardrails scanning isn't behaving as expected, the standalone [Codacy Analysis CLI](../codacy-analysis-cli/index.md) can tell you the state of your setup: your authentication status, your system information, and every analysis tool it knows about, along with whether each one is installed locally. The IDE extension bundles its own copy of the analyzer and doesn't put the `codacy-analysis` command on your `PATH`, so install the CLI first: diff --git a/docs/codacy-skills/index.md b/docs/codacy-skills/index.md index 3d0ba68df4..1f3685fb40 100644 --- a/docs/codacy-skills/index.md +++ b/docs/codacy-skills/index.md @@ -12,9 +12,9 @@ The skills are open source under the MIT license and live in the [`codacy/codacy | Skill | What it does | Needs | |---|---|---| -| `codacy-cloud-cli` | Queries repositories, issues, security findings, pull requests, tools, and patterns on Codacy Cloud | Codacy Cloud CLI | +| `codacy-cloud-cli` | Queries repositories, issues, security findings, pull requests, tools, and patterns on Codacy Cloud | [Codacy Cloud CLI](../codacy-cloud-cli/index.md) | | `codacy-code-review` | Adds Codacy issues, security findings, coverage, and duplication to a pull request review | Both CLIs | -| `codacy-analysis-cli` | Runs static analysis locally, without sending your code to Codacy | Codacy Analysis CLI | +| `codacy-analysis-cli` | Runs static analysis locally, without sending your code to Codacy | [Codacy Analysis CLI](../codacy-analysis-cli/index.md) | | `configure-codacy` | Discovers your project's stack, enables the tools and patterns that fit it, and cuts noise from the results | Both CLIs | | `configure-codacy-cloud` | Tunes the configuration of a repository already analyzed on Codacy, without running local analysis | Both CLIs | | `setup-coverage` | Detects your test framework and CI, then adds what's missing to generate and upload coverage reports | A repository on Codacy | @@ -35,7 +35,7 @@ npm install -g @codacy/analysis-cli Then authenticate. Run `codacy login` and paste an [account API token](../codacy-api/api-tokens.md#account-api-tokens), or set the `CODACY_API_TOKEN` environment variable for non-interactive environments. Both CLIs read the same credentials from `~/.codacy/credentials`, so a single login covers both. -See [Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication) for the full set of authentication options, including repository API tokens. +See [Codacy Cloud CLI](../codacy-cloud-cli/index.md#authentication) and [Codacy Analysis CLI](../codacy-analysis-cli/index.md#authentication) for the full set of authentication options, including repository API tokens. ## Install the skills diff --git a/docs/repositories-configure/local-analysis/client-side-tools.md b/docs/repositories-configure/local-analysis/client-side-tools.md index 241e4f4cc1..57270bd264 100644 --- a/docs/repositories-configure/local-analysis/client-side-tools.md +++ b/docs/repositories-configure/local-analysis/client-side-tools.md @@ -13,7 +13,7 @@ Codacy supports client-side tools in two ways: The legacy Codacy Analysis CLI automatically fetches the code pattern settings that you define on the Codacy UI and applies them when running the tools. !!! note - This is a separate, older tool from the [Codacy Analysis CLI](../../codacy-guardrails/codacy-guardrails-getting-started.md#install-cli) (`@codacy/analysis-cli`, the `codacy-analysis` command) that powers Codacy Guardrails and [running ESLint locally](running-eslint.md). The tools listed below don't have an equivalent on the newer CLI yet. + This is a separate, older tool from the [Codacy Analysis CLI](../../codacy-analysis-cli/index.md) (`@codacy/analysis-cli`, the `codacy-analysis` command) that powers Codacy Guardrails and [running ESLint locally](running-eslint.md). The tools listed below don't have an equivalent on the newer CLI yet. - **Standalone tools:** Codacy provides auxiliary converters that parse the output of third-party tools and convert to a format that you then upload to Codacy. You must download, configure, and run the third-party tools yourself. diff --git a/docs/repositories-configure/local-analysis/running-eslint.md b/docs/repositories-configure/local-analysis/running-eslint.md index 1196375b05..e489d34619 100644 --- a/docs/repositories-configure/local-analysis/running-eslint.md +++ b/docs/repositories-configure/local-analysis/running-eslint.md @@ -18,7 +18,7 @@ To run ESLint as a [client-side tool](client-side-tools.md): ## Manual configuration -Install the Codacy Analysis CLI and initialize the repository. Initialization writes `.codacy/codacy.config.json`, which `analyze` requires: pulling it from Codacy Cloud with `init --remote` means the local run uses the same ESLint patterns as your repository's **Code patterns** page. +Install the [Codacy Analysis CLI](../../codacy-analysis-cli/index.md) and initialize the repository. Initialization writes `.codacy/codacy.config.json`, which `analyze` requires: pulling it from Codacy Cloud with `init --remote` means the local run uses the same ESLint patterns as your repository's **Code patterns** page. ```bash npm i -g @codacy/analysis-cli diff --git a/mkdocs.yml b/mkdocs.yml index 2250f1d5b7..dcef065eea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -769,6 +769,7 @@ nav: - codacy-api/examples/uploading-dast-results.md - codacy-api/examples/triggering-dast-scans.md - Codacy CLIs: + - codacy-analysis-cli/index.md - codacy-cloud-cli/index.md - Codacy Skills: - codacy-skills/index.md From 2053d398163e82ef3e4bc7280bc5e88895c41982 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 10 Sep 2026 15:12:47 +0100 Subject: [PATCH 2/3] docs: restructure the Analysis CLI page around the task, not the commands The page had 13 top-level sections ranging from 4 to 90 lines, so the "On this page" nav read as a flat list of equal-looking entries for things that were not equal. The sibling Codacy Cloud CLI page has 6, nesting its capabilities as ### under one ##. Three changes: - Requirements now carries the path to a first analysis, branching on whether the repository is on Codacy. That question was previously answered in section 10 of 13, after nine sections of reference. - init modes are led by a recommendation instead of presented as a flat five-way menu with no default: init --remote when the repository is on Codacy, init --auto when it is not, with the two narrower modes after them. - Common workflows keeps only the recipes that compose commands the body cannot show on their own: the --auto plus Codacy Cloud merge, and CI. The other three restated the command sections and are gone, absorbed into Requirements and Scope the analysis. Also merges Inspect your stack with Combine configuration files, and Codacy Self-hosted with Run behind a proxy. No content dropped: every command, environment variable, and verified behavior from the previous revision is still present, and all five explicit anchors are unchanged, including the #authentication one that docs/codacy-skills/index.md links to. Co-Authored-By: Claude Opus 5 --- docs/codacy-analysis-cli/index.md | 146 ++++++++++++++++-------------- 1 file changed, 77 insertions(+), 69 deletions(-) diff --git a/docs/codacy-analysis-cli/index.md b/docs/codacy-analysis-cli/index.md index e1b9a9127b..4a8edc0c12 100644 --- a/docs/codacy-analysis-cli/index.md +++ b/docs/codacy-analysis-cli/index.md @@ -16,6 +16,27 @@ Pair it with the [Codacy Skills](../codacy-skills/index.md) to run local analysi - Node.js 20 or later - git — the CLI resolves paths against the repository root, and the [git-aware flags](#scope-the-analysis) read your branch and staging area +From there, what you run depends on one thing: whether the repository is already on Codacy. + +**If your repository is on Codacy**, pull its configuration down. Local results then match what Codacy reports on your pull requests, which is usually the reason for running the CLI at all: + +```bash +npm i -g @codacy/analysis-cli +codacy-analysis login +codacy-analysis init --remote gh my-org my-repo +codacy-analysis analyze --install-dependencies +``` + +**If it isn't**, let the CLI detect your stack and pick the rules. No token, no account, and nothing leaves your machine: + +```bash +npm i -g @codacy/analysis-cli +codacy-analysis init --auto +codacy-analysis analyze --install-dependencies +``` + +The rest of this page covers each of those steps on its own, and the flags worth knowing once the first run works. + ## Installation The CLI is published on npm and installs the same way on macOS, Linux, and Windows: @@ -54,54 +75,61 @@ codacy-analysis init --remote gh my-org my-repo --repository-token {% include-markdown "../assets/includes/api-token-warning.md" %} -## Codacy Self-hosted +## Choose which rules run {: id="configure-your-repository"} -Point the CLI at your own instance with `CODACY_API_BASE_URL`. The `upload` command talks to a different endpoint from the rest of the CLI and reads its own variable, so set both: +`init` writes `.codacy/codacy.config.json`, which records the tools and patterns that run. `analyze` reads it, so run `init` once per repository before analyzing. The modes below are mutually exclusive: each one is a different answer to where the configuration comes from. + +Alongside it, `init` writes `codacy.config.baseline.json`, which records what the generator last produced, and a `.codacy/.gitignore` that keeps the derived `generated/` folder out of version control. Commit both JSON files so your team analyzes against the same configuration. + +### If your repository is on Codacy + +`init --remote` fetches the configuration Codacy already holds, so local analysis applies the same code patterns and coding standards as your pull requests: ```bash -export CODACY_API_BASE_URL= -export CODACY_RESULTS_API_BASE_URL= +codacy-analysis init --remote gh my-org my-repo ``` -## Configure your repository {: id="configure-your-repository"} +It takes your provider — `gh` for GitHub, `gl` for GitLab, or `bb` for Bitbucket — then your organization and repository name, and it needs [authentication](#authentication). -`init` writes `.codacy/codacy.config.json`, which records the tools and patterns that run. `analyze` reads it, so run `init` once per repository before analyzing. +If you want the rules Codacy enforces as well as the tools the CLI detects locally, you can have both: see [analyzing against your stack and your Codacy Cloud rules](#merge-auto-and-remote). -Which mode you pick decides where the configuration comes from: +### If your repository isn't on Codacy -```bash -# Detect languages from the tool configuration files already in the repository -codacy-analysis init +`init --auto` discovers your languages and frameworks and selects patterns to match, enabling framework-specific rules only when it finds the corresponding dependency. This is the mode to reach for: -# Detect the stack and select patterns per detected framework +```bash codacy-analysis init --auto +``` + +Narrow it with comma-separated severities and categories when a full run reports more than you want to act on: -# Same, narrowed to specific severities and categories +```bash codacy-analysis init --auto Critical,High,Security +``` -# Add Codacy's default patterns on top — no token needed -codacy-analysis init --default +Two narrower modes exist for cases `--auto` doesn't fit. Bare `init` configures only the tools that already have a configuration file in the repository, and `init --default` adds Codacy's default patterns from the public API, which needs no token: -# Fetch the configuration of a repository on Codacy, so local results match it -codacy-analysis init --remote gh my-org my-repo +```bash +codacy-analysis init +codacy-analysis init --default ``` -The modes are mutually exclusive. `init --remote` takes your provider (`gh` for GitHub, `gl` for GitLab, or `bb` for Bitbucket), organization, and repository name, and needs [authentication](#authentication); the others don't. If you want both the stack `--auto` detects and the rules your repository enforces on Codacy, see [analyzing against your stack and your Codacy Cloud rules](#merge-auto-and-remote). - -Alongside it, `init` writes `codacy.config.baseline.json`, which records what the generator last produced, and a `.codacy/.gitignore` that keeps the derived `generated/` folder out of version control. Commit both JSON files so your team analyzes against the same configuration. +### Keep the configuration current -To bring an existing configuration up to date with your current stack: +As your stack changes, bring the configuration along with it: ```bash codacy-analysis update-config ``` -By default this is incremental: patterns you disabled stay disabled and your parameters and excludes survive, while tools and patterns for newly detected languages and frameworks are added. Add `--reset` to regenerate from scratch and discard your edits. Configurations created with `init --remote` are always re-synced in full, because Codacy Cloud is authoritative for them. +By default this is incremental: patterns you disabled stay disabled and your parameters and excludes survive, while tools and patterns for newly detected languages and frameworks are added. Add `--reset` to regenerate from scratch and discard your edits. + +Configurations created with `init --remote` are always re-synced in full, because Codacy Cloud is authoritative for them. Local edits to those are discarded, which is the trade for staying in step with the UI. !!! note `init` and `update-config` read the `exclude_paths` in your [Codacy configuration file](../repositories-configure/codacy-configuration-file.md) and record them in `codacy.config.json`, which is where `analyze` reads them from. Editing `.codacy.yaml` on its own doesn't change what `analyze` covers — run `update-config` afterward. -## Run an analysis +## Analyze With the configuration in place, analyze the repository: @@ -109,7 +137,7 @@ With the configuration in place, analyze the repository: codacy-analysis analyze ``` -Some analyzers ship inside the npm package; the rest are downloaded on demand. `--install-dependencies` fetches the missing ones into `~/.codacy`, where they're reused across every repository on the machine, and then runs the analysis: +Some analyzers ship inside the npm package; the rest are downloaded on demand. On a first run, use `--install-dependencies`, which fetches the missing ones and then runs the analysis. They go to `~/.codacy`, so every repository on the machine reuses them: ```bash codacy-analysis analyze --install-dependencies @@ -123,6 +151,8 @@ codacy-analysis analyze --inspect `--inspect`, `--install-dependencies`, and `--fail-if-missing` are mutually exclusive — passing two of them exits `2` without analyzing. +### Read the results + `analyze` prints text by default. Use `--output-format` for machine-readable output, and `--output` to write it to a file: ```bash @@ -164,7 +194,7 @@ codacy-analysis analyze --files "**/*.py" --files "**/*.rs" The git-aware flags scope the run to what changed. They're mutually exclusive: ```bash -# Files in the git staging area — the flag to use in a pre-commit hook +# Files in the git staging area codacy-analysis analyze --staged # Files changed against the default branch, or against a base branch you name @@ -175,7 +205,7 @@ codacy-analysis analyze --diff develop codacy-analysis analyze --pr ``` -Combining a git flag with `--files` analyzes the intersection of the two. +`--staged` is the one to put in a pre-commit hook: it exits `1` when it finds anything, which is all the hook needs to block the commit. Combining a git flag with `--files` analyzes the intersection of the two, which keeps a hook down to the analyzers that matter for the files you touch. ### Tune the run @@ -212,7 +242,7 @@ codacy-analysis upload results.sarif --repository gh my-org my-repo --commit +export CODACY_RESULTS_API_BASE_URL= ``` -Here `update-config` re-syncs the configuration in full rather than incrementally, because Codacy Cloud is authoritative for it. Local edits to the file are discarded, which is the trade for staying in step with the UI. - -## Run behind a proxy - All outbound requests — Codacy API calls and analyzer downloads alike — honor the standard proxy variables: ```bash @@ -308,28 +338,6 @@ Trust your organization's CA through `SSL_CERT_FILE` or `NODE_EXTRA_CA_CERTS` ra The update-available check uses a separate network stack that ignores these variables. Behind a strict proxy, turn it off with `CODACY_DISABLE_UPDATE_CHECK=1`. -## Use the CLI in CI - -Install the CLI as a step and pass a repository API token as a secret: - -{% raw %} -```yaml -- name: Install Codacy Analysis CLI - run: npm i -g @codacy/analysis-cli - -- name: Analyze and upload - env: - CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }} - run: | - codacy-analysis init --remote gh ${{ github.repository_owner }} my-repo - codacy-analysis analyze --install-dependencies --no-log \ - --output-format sarif --output results.sarif - codacy-analysis upload results.sarif -``` -{% endraw %} - -To gate a pull request on the analysis rather than only reporting it, drop the `upload` step and let the exit code of `analyze --diff` fail the job. - ## See also - [Codacy Analysis CLI on npm](https://www.npmjs.com/package/@codacy/analysis-cli) From ebd8653ce65fb1486bafd3b064069fc31f8fe495 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A1udia?= Date: Thu, 10 Sep 2026 15:28:00 +0100 Subject: [PATCH 3/3] docs: move the build-server tip to the CI section The tip closed the Upload results to Codacy section, where it read as a footnote to the account-token example rather than as a setting anyone needs to touch. It belongs with the pipeline that does the uploading, so it now sits directly under the workflow snippet in Use the CLI in CI. Reworded "these results" to "the uploaded results", since the pronoun no longer has the upload commands immediately above it. Co-Authored-By: Claude Opus 5 --- docs/codacy-analysis-cli/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/codacy-analysis-cli/index.md b/docs/codacy-analysis-cli/index.md index 4a8edc0c12..865abb7ae6 100644 --- a/docs/codacy-analysis-cli/index.md +++ b/docs/codacy-analysis-cli/index.md @@ -239,9 +239,6 @@ With an account API token instead of a repository API token, name the repository codacy-analysis upload results.sarif --repository gh my-org my-repo --commit ``` -!!! tip - For Codacy to wait for these results before it resumes analyzing your commits, enable **Run analysis on your build server** on your repository **Settings**, tab **General**, **Repository analysis on your server**. - ## Inspect and combine configurations `discover` reports the languages, frameworks, libraries, and notable files the CLI finds, which is what `init --auto` bases its selection on: @@ -315,6 +312,9 @@ Install the CLI as a step and pass a repository API token as a secret: ``` {% endraw %} +!!! tip + For Codacy to wait for the uploaded results before it resumes analyzing your commits, enable **Run analysis on your build server** on your repository **Settings**, tab **General**, **Repository analysis on your server**. + To gate a pull request on the analysis rather than only reporting it, drop the `upload` step and let the exit code of `analyze --diff` fail the job. ## Network and Codacy Self-hosted