diff --git a/README.md b/README.md index 4d3ca532..0996acf6 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,221 @@ -# codacy-cli-v2 +# Codacy CLI v2 -The Codacy CLI (version 2) is a command-line tool that supports analyzing code using tools like ESLint and uploading the results in SARIF format to Codacy. -The tool is invoked using the `codacy-cli` command, and provides two main commands: analyze and upload. +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8cae070168cf488db82478ba6505a005)](https://app.codacy.com/gh/codacy/codacy-cli-v2/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/8cae070168cf488db82478ba6505a005)](https://app.codacy.com/gh/codacy/codacy-cli-v2/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) -### Commands -- **`analyze` Command**: Runs ESLint analysis on the codebase. - - `--output, -o`: Output file for the results. - - `--tool, -t`: Specifies the tool to run analysis with (e.g., ESLint). - - `--format`: Output format (use 'sarif' for SARIF format to terminal). - - `--fix`: Automatically fixes issues when possible. +Codacy CLI (version 2) is a command-line tool for running code analysis and integrating with Codacy. If your repository exists in Codacy, you can sync your configuration to ensure consistency with your organization's standards. -- **`upload` Command With Project Token**: Uploads a SARIF file containing analysis results to Codacy. - - `--sarif-path, -s`: Path to the SARIF report. - - `--commit-uuid, -c`: Commit UUID. - - `--project-token, -t`: Project token for Codacy API. +You can also use Codacy CLI for local code analysis without a Codacy account, leveraging the linter configuration files found in your project's root or Codacy's suggested defaults. -- **`upload` Command With API Token**: Uploads a SARIF file containing analysis results to Codacy. - - `--sarif-path, -s`: Path to the SARIF report. - - `--commit-uuid, -c`: Commit UUID. - - `--api-token, -a`: User level token for Codacy API. - - `--provider, -p`: Provider name (e.g., gh, gl, bb). - - `--owner, -o`: Repository owner. - - `--repository, -r`: Repository name. +The CLI supports uploading analysis results (in [SARIF](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) format) to Codacy as well. -### Important Concepts +It is invoked using the `codacy-cli` command and provides several commands for project setup, analysis, and integration. -- **`.codacy/codacy.yaml`**: Configuration file to specify runtimes and tools versions for the CLI. - ```yaml - runtimes: - - node@22.2.0 - tools: - - eslint@8.57.0 - -- **`codacy-cli install`**: Command to install the specified node and eslint versions before running analysis. +--- -## Download +## Supported Platforms -### MacOS (brew) +- **macOS** +- **Linux** +- **Windows (via WSL only)** -To install `codacy-cli` using Homebrew: +> **Note:** Native Windows is not yet supported. For Windows, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/) and follow the Linux instructions inside your WSL terminal. + +--- + +## Installation + +### macOS (Homebrew) ```bash brew install codacy/codacy-cli-v2/codacy-cli-v2 ``` -### Linux +### Linux / Windows (WSL) -For Linux, we rely on the codacy-cli.sh script in the root. To download the CLI, run: +Run the following in your terminal (Linux or WSL): ```bash bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh) ``` -You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes: + +Or create an alias for convenience: ```bash alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)" ``` -## Installation +--- + +## CLI Commands + +### `init` — Bootstrap Project Configuration + +Bootstraps the CLI configuration in your project's folder. This command creates a `.codacy` directory containing a `codacy.yaml` file, which specifies the runtimes and tools that will be used and installed. + +- If you provide Codacy repository information (API token, provider, organization, repository), the configuration will be fetched from Codacy, ensuring consistency with your organization's standards. +- If no Codacy information is provided, all available tools will be included. For each tool, if a local configuration file exists in your project, it will be used; otherwise, Codacy's suggested defaults will be used. + +- **Local mode (local configuration files):** + ```bash + codacy-cli init + ``` +- **Remote mode (fetch configuration from Codacy):** + ```bash + codacy-cli init --api-token --provider --organization --repository + ``` + +**Flags:** +- `--api-token` (string): Codacy API token (optional; enables fetching remote config) +- `--provider` (string): Provider (`gh`, `gl`, `bb`), required with `--api-token` +- `--organization` (string): Organization name, required with `--api-token` +- `--repository` (string): Repository name, required with `--api-token` + +### `install` — Install Runtimes and Tools -Before running the analysis, install the specified tools: +Installs all runtimes and tools specified in `.codacy/codacy.yaml`: +- Downloads and extracts runtimes (Node, Python, Dart, Java, etc.) +- Installs tools (ESLint, Trivy, Pylint, PMD, etc.) using the correct package manager or direct download +- Handles platform-specific details +- Skips already installed components (e.g., Node, Python, Dart, Java, etc.) +- Shows a progress bar and reports any failures ```bash codacy-cli install ``` +- Optionally specify a custom registry: + ```bash + codacy-cli install --registry + ``` -## Run Analysis +### `analyze` — Run Code Analysis -To run ESLint and output the results to the terminal: +Runs all configured tools, or a specific tool, on your codebase. ```bash +# Run all tools +codacy-cli analyze + +# Run a specific tool (e.g., ESLint) codacy-cli analyze --tool eslint + +# Output results in SARIF format +codacy-cli analyze --tool eslint --format sarif + +# Store results as SARIF in a file +codacy-cli analyze -t eslint --format sarif -o eslint.sarif + +# Analyze a specific file with all configured tools +codacy-cli analyze path/to/file.js + +# Analyze a specific file with a specific tool (e.g., ESLint) +codacy-cli analyze --tool eslint path/to/file.js ``` -To output results in SARIF format to the terminal: +**Flags:** +- `--output, -o`: Output file for the results; if not provided, results will be printed to the console +- `--tool, -t`: Tool to run analysis with (e.g., eslint) +- `--format`: Output format (e.g., `sarif`) +- `--fix`: Automatically fix issues when possible + +### `upload` — Upload SARIF Results to Codacy + +Uploads a SARIF file containing analysis results to Codacy. ```bash -codacy-cli analyze --tool eslint --format sarif +# With project token +codacy-cli upload -s path/to/your.sarif -c -t + +# With API token +codacy-cli upload -s path/to/your.sarif -c -a -p -o -r ``` -To store the results as SARIF in a file: +**Flags:** +- `--sarif-path, -s`: Path to the SARIF report (required) +- `--commit-uuid, -c`: Commit UUID +- `--project-token, -t`: Project token for Codacy API +- `--api-token, -a`: User-level token for Codacy API +- `--provider, -p`: Provider name (e.g., gh, gl, bb) +- `--owner, -o`: Repository owner +- `--repository, -r`: Repository name + +### `update` — Update the CLI + +Fetches and installs the latest version of the CLI. ```bash -codacy-cli analyze -t eslint --format sarif -o eslint.sarif +codacy-cli update ``` -## Upload Results +### `version` — Show Version Information -To upload a SARIF file to Codacy: +Displays detailed version/build information for the CLI. ```bash -codacy-cli upload -s path/to/your.sarif -c your-commit-uuid -t your-project-token +codacy-cli version ``` -## Breaking Changes +--- + +## Configuration + +- **`.codacy/codacy.yaml`**: Main configuration file specifying runtimes and tool versions. +- **`.codacy/tools-configs/`**: Tool-specific configuration files (auto-generated or fetched from Codacy). + +--- -Some behaviors have changed with the new updates of the CLI. To rely on a specific version, you can add that version to your environment: +## Example Usage +```bash +# 1. Initialize project (local or remote) +codacy-cli init +# or +codacy-cli init --api-token --provider gh --organization my-org --repository my-repo + +# 2. Install all required runtimes and tools +codacy-cli install + +# 3. Run analysis (all tools or specific tool) +codacy-cli analyze +codacy-cli analyze --tool eslint + +# 4. Upload results to Codacy +codacy-cli upload -s eslint.sarif -c -t ``` -export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792" + +--- + +## Troubleshooting + +### WSL (Windows Subsystem for Linux) +- **Always use a WSL terminal** (e.g., Ubuntu on Windows) for all commands. +- Ensure you have the latest version of WSL and a supported Linux distribution installed. +- If you see errors related to missing Linux tools (e.g., `curl`, `tar`), install them using your WSL package manager (e.g., `sudo apt install curl tar`). + +### MacOS: Errors related to `docker-credential-osxkeychain` not found + +Install the docker credential helper: + +```bash +brew install docker-credential-helper ``` +--- + ## Example Repository -As an example, you can check https://github.com/troubleshoot-codacy/eslint-test-examples for a repository that has an action relying on this CLI. +See [eslint-test-examples](https://github.com/troubleshoot-codacy/eslint-test-examples) for a repository using this CLI in GitHub Actions. -## Troubleshooting +--- -#### Errors related to `docker-credential-osxkeychain` not found when running analysis +## Breaking Changes & Version Pinning -Install the docker credential helper. For example, in MacOS: +Some behaviors have changed with recent updates. To rely on a specific CLI version, set the following environment variable: ```bash -brew install docker-credential-helper +export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792" ``` + +Check the [releases](https://github.com/codacy/codacy-cli-v2/releases) page for all available versions. + +---