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.
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.
The CLI supports uploading analysis results (in SARIF format) to Codacy as well.
It is invoked using the codacy-cli command and provides several commands for project setup, analysis, and integration.
- macOS
- Linux
- Windows (via WSL only)
Note: Native Windows is not yet supported. For Windows, use Windows Subsystem for Linux (WSL) and follow the Linux instructions inside your WSL terminal.
brew install codacy/codacy-cli-v2/codacy-cli-v2Run the following in your terminal (Linux or WSL):
bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)Or create an alias for convenience:
alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)"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):
codacy-cli init
-
Remote mode (fetch configuration from Codacy):
codacy-cli init --api-token <token> --provider <gh|gl|bb> --organization <org> --repository <repo>
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
Resets the Codacy configuration files and tool-specific configurations. This command overwrites existing configuration with either local default configurations or repository-specific configurations from Codacy.
# Reset to local default configurations
codacy-cli config reset
# Reset to repository-specific configurations from Codacy
codacy-cli config reset --api-token <token> --provider <gh|gl|bb> --organization <org> --repository <repo>Behavior:
- Local mode: Creates default configurations for all available tools
- Remote mode: Fetches and applies repository-specific configurations from Codacy
- Prevents accidental mode switching (remote to local requires explicit flags)
- Overwrites existing
.codacy/codacy.yamland tool configurations - Creates or updates
.codacy/.gitignorefile
Flags: Same as init command (api-token, provider, organization, repository)
Scans a project directory to detect programming languages and automatically configures appropriate static analysis tools. This command updates both languages-config.yaml and codacy.yaml with relevant tools for detected languages.
# Discover languages in current directory
codacy-cli config discover .
# Discover languages in specific project path
codacy-cli config discover /path/to/projectFeatures:
- Automatically detects file extensions and maps them to programming languages
- Updates
.codacy/tools-configs/languages-config.yamlwith discovered languages - Enables relevant tools in
codacy.yamlbased on detected languages - Creates tool-specific configuration files for discovered tools
- Works in both local and cloud modes
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
codacy-cli install- Optionally specify a custom registry:
codacy-cli install --registry <url>
Runs all configured tools, or a specific tool, on your codebase.
# 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.jsFlags:
--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
Uploads a SARIF file containing analysis results to Codacy.
# With project token
codacy-cli upload -s path/to/your.sarif -c <commit-uuid> -t <project-token>
# With API token
codacy-cli upload -s path/to/your.sarif -c <commit-uuid> -a <api-token> -p <provider> -o <owner> -r <repository>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
Fetches and installs the latest version of the CLI.
codacy-cli updateDisplays detailed version/build information for the CLI.
codacy-cli version.codacy/codacy.yaml: Main configuration file specifying runtimes and tool versions..codacy/tools-configs/: Tool-specific configuration files (auto-generated or fetched from Codacy).
# 1. Initialize project (local or remote)
codacy-cli init
# or
codacy-cli init --api-token <token> --provider gh --organization my-org --repository my-repo
# 2. (Optional) Discover languages and configure tools automatically
codacy-cli config discover .
# 3. Install all required runtimes and tools
codacy-cli install
# 4. Run analysis (all tools or specific tool)
codacy-cli analyze
codacy-cli analyze --tool eslint
# 5. Upload results to Codacy
codacy-cli upload -s eslint.sarif -c <commit-uuid> -t <project-token>- 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).
Install the docker credential helper:
brew install docker-credential-helperSee eslint-test-examples for a repository using this CLI in GitHub Actions.
Some behaviors have changed with recent updates. To rely on a specific CLI version, set the following environment variable:
export CODACY_CLI_V2_VERSION="1.0.0-main.133.3607792"Check the releases page for all available versions.