codacy-analysis-cli

Codacy Analysis CLI

**术语表：**有关 Codacy 概念（问题、发现、严重性、覆盖率、工具、模式等）的统一定义，请参阅 glossary.md。

Codacy Analysis CLI（codacy-analysis）可在本地对代码库运行静态分析。它会检测语言、选择工具并报告问题，无需将代码推送到 Codacy。这与 Codacy Cloud CLI（codacy）是不同的工具，后者用于查询 Codacy 远程数据。

在 Agent 工作流中，结构化输出始终使用 --output-format json。

对于需要执行门禁检查的运行（提交前、PR 审查、CI），还要传入 --fail-if-missing，请参阅严格模式。

设置

# Install
npm i -g @codacy/analysis-cli

# Verify
codacy-analysis --help

身份验证（可选）

只有在使用 init --remote（从 Codacy 代码库获取配置）时才需要身份验证。本地分析无需身份验证。

# Option 1: Interactive login
codacy-analysis login

# Option 2: Token flag
codacy-analysis login --token <your-api-token>

# Option 3: Environment variable
export CODACY_API_TOKEN=<your-api-token>

# Obtain tokens: Codacy > My Account > Access Management
# Remove credentials
codacy-analysis logout

**共享会话：**Analysis CLI 和 Cloud CLI（codacy）共用 ~/.codacy/credentials 中的凭据。使用任一 CLI 登录或退出都会同时应用于两者，无需分别进行身份验证。

获取帮助

codacy-analysis --help
codacy-analysis <command> --help
# e.g. codacy-analysis analyze --help

文件系统约定

CLI 使用两个受管理的位置：

位置	范围	内容
.codacy/（代码库根目录中）	每个项目	codacy.config.json、generated/（工具配置）、.gitignore（自动创建）
~/.codacy/（主目录中）	整台机器	运行时环境、工具二进制文件、缓存、日志、凭据

**分析的代码库在 .codacy/ 之外绝不会被修改。**系统会自动创建 .codacy/.gitignore，以排除 generated/、日志和其他临时文件。

关键文件

• .codacy/codacy.config.json — 主配置：工具、模式、排除项、元数据。完整架构请参阅 references/config-format.md
• .codacy/generated/<ToolId>/ — 生成的工具专属配置（已加入 git 忽略）
• ~/.codacy/credentials — 存储的 API 令牌
• ~/.codacy/logs/ — 结构化日志（JSON 行格式，达到 10 MB 时轮换）

Provider 值

与 init --remote 搭配使用。CLI 值（gh、gl、bb）的完整表格请参阅术语表中的 Provider 部分。

分析工作流

Analysis Progress:
- [ ] Step 1: Initialize configuration
- [ ] Step 2: Inspect tool availability (dry-run)
- [ ] Step 3: Install missing dependencies
- [ ] Step 4: Run analysis
- [ ] Step 5: Interpret results

步骤 1：初始化配置

根据代码库的情况选择初始化模式：

代码库位于 Codacy 中，且你想使用其精确配置：

# Requires authentication (login or CODACY_API_TOKEN)
codacy-analysis init --remote <provider> <org> <repo>
# e.g. codacy-analysis init --remote gh my-org my-repo

代码库位于 Codacy 中，但你只需要合适的默认配置：

# No token needed — uses the public Codacy API for default patterns
codacy-analysis init --default

广泛的自动调优初始化（最大限度覆盖模式）：

# Initializes with all patterns matching the given severity/category filter
codacy-analysis init --auto "AllCritical,High,Warning,Minor,AllSecurity,ErrorProne,Performance,BestPractice,UnusedCode,Compatibility,Complexity,Comprehensibility,CodeStyle,Documentation"

--auto 标志会根据以逗号分隔的严重性和类别筛选条件，广泛选择模式。如果你想从最大覆盖范围开始，再根据分析数据减少噪声，请使用此选项。

代码库不在 Codacy 中（仅本地分析）：

# Detects languages and tools based on local files and config
codacy-analysis init

指定目录（不是当前目录）：

codacy-analysis init /path/to/repo

所有模式都会在代码库根目录中创建 .codacy/codacy.config.json（或创建传给 --config-file 的文件，参阅使用替代配置文件）。如果存在 .codacy.yaml（或 .codacy.yml），系统会自动将其中的 exclude_paths 合并到配置中。

更新现有配置

如果配置是通过 --remote 初始化的，而你想与 Codacy 远程配置重新同步：

codacy-analysis update-config

此操作会从初始化时使用的同一个 Codacy 代码库重新获取配置。

**仅对使用 --remote 初始化的配置使用 update-config。**对于使用 --default 或不带参数的 init 初始化的配置，update-config 会重新运行原始初始化模式，从而覆盖你对配置文件所做的任何手动修改。

使用替代配置文件

默认情况下，每条命令都会读取和写入 .codacy/codacy.config.json。向 init、analyze 和 update-config 传入 --config-file <path>，即可使用其他文件。这样可以并行保留多个配置并同时测试，而不会覆盖主配置：

# Create an alternative, broadly-tuned config in a separate file
codacy-analysis init --auto AllCritical,AllSecurity --config-file .codacy/auto-config.json

# Analyze using that config instead of the default
codacy-analysis analyze --config-file .codacy/auto-config.json --output-format json

# Regenerate it later using its original init mode (the mode is stored in the file)
codacy-analysis update-config --config-file .codacy/auto-config.json

--config-file 适用于 init（配置文件的创建位置）、analyze（运行时使用的配置）和 update-config（重新生成的配置）。所有命令的默认值均为 .codacy/codacy.config.json。

合并配置文件（config 命令）

config 命令会对两个配置文件执行集合操作，合并其中的工具和规则。可用它将实验性配置与基准配置协调一致：

# Merge — union of tools/patterns from source into dest
codacy-analysis config --merge --source .codacy/extra.json

# Intersect — keep only tools/patterns present in BOTH files
codacy-analysis config --intersect --source a.json --dest b.json

# Diff — keep tools/patterns in dest that are NOT in source (dest − source)
codacy-analysis config --diff --source baseline.json --dest .codacy/codacy.config.json

• 必须且只能指定 --merge、--intersect、--diff 中的一个。
• --source <path> 为只读（默认 .codacy/codacy.config.json）；--dest <path> 会被覆盖为操作结果（默认 .codacy/codacy.config.json）。
• 必须至少提供 --source / --dest 之一 — 它们不能同时回退到同一个默认文件。

--dest 会在原位置被覆盖。 如果需要保留目标配置，请将其指向临时文件（或先备份原文件）。

发现代码仓库技术栈

使用 discover 在初始化前自动检测代码仓库的语言、框架和库：

codacy-analysis discover --output-format json --output /tmp/codacy-discover.json

输出会列出检测到的语言、框架以及适用的工具。可据此确定要启用哪些工具和规则。

查看支持的工具

使用 info 查看本地 Analysis CLI 中可用的工具：

codacy-analysis info

此命令会列出 CLI 可在本地运行的所有工具。将其与 Codacy Cloud 中启用的工具进行比较，即可找出本地 CLI 无法运行的云端专用工具。

第 2 步：检查工具可用性（试运行）

运行分析前，检查哪些工具可用、哪些缺失：

codacy-analysis analyze --inspect --output-format json

此操作会生成能力报告，但不会运行任何分析。解析 JSON 输出：

# See which tools are ready
codacy-analysis analyze --inspect --output-format json | jq '.capability.ready[] | {toolId, version, installation}'

# See which tools are missing and how to fix them
codacy-analysis analyze --inspect --output-format json | jq '.capability.unavailable[] | {toolId, reason, remediation}'

重要： --inspect、--install-dependencies 和 --fail-if-missing 彼此互斥 — 任意组合其中两项都会以状态码 2 退出。请依次使用：先用 --inspect 检查就绪情况，再用 --install-dependencies 安装并运行，后续运行时使用 --fail-if-missing。

决策点：

• 如果所需工具都在 capability.ready 中 → 跳到第 4 步
• 如果工具在 capability.unavailable 中 → 继续第 3 步

第 3 步：安装缺失的依赖项

首选：使用 --install-dependencies — 在 .codacy/ / ~/.codacy/ 范围内安装工具，不影响机器上的其他部分：

codacy-analysis analyze --install-dependencies --output-format json

此命令会安装缺失的工具，然后运行分析。已安装的二进制文件会放到 ~/.codacy/（机器级目录，可供多个代码仓库重复使用）。

最后手段：手动安装 — 如果 --install-dependencies 对某个特定工具安装失败，请在机器上手动安装（例如，brew install shellcheck、pip install ruff）。工具详情请参阅 references/supported-tools.md。

第 4 步：运行分析

在 Agent 工作流中，始终使用 --output-format json。

分析整个代码仓库

codacy-analysis analyze --output-format json

分析指定文件或路径

# Single file (positional argument)
codacy-analysis analyze ./src/main.py --output-format json

# Multiple files by path or glob (--files flag)
codacy-analysis analyze --files src/a.py src/b.py --output-format json

# Glob pattern (always quote to prevent shell expansion)
codacy-analysis analyze --files "src/**/*.ts" --output-format json

# Subdirectory
codacy-analysis analyze ./src/api/ --output-format json

限定使用指定工具

工具 ID 区分大小写。完整列表请参阅 references/supported-tools.md。

# Single tool
codacy-analysis analyze --tool Ruff --output-format json

# Multiple tools
codacy-analysis analyze --tool Ruff --tool Bandit --output-format json

# Combine with file targeting
codacy-analysis analyze --tool ESLint9 --files "src/**/*.ts" --output-format json

使用替代配置文件运行

默认情况下，analyze 会读取 .codacy/codacy.config.json。传入 --config-file <path> 即可使用其他配置运行 — 适合并排比较配置（请参阅使用替代配置文件）：

codacy-analysis analyze --config-file .codacy/auto-config.json --output-format json

基于 Git 的范围限定

只分析发生更改的代码，而不是整个代码库。这通常是门禁检查，因此请包含 --fail-if-missing（严格模式）：

# Only files staged for commit
codacy-analysis analyze --staged --fail-if-missing --output-format json

# Changes relative to the current branch's merge base (uncommitted + committed)
codacy-analysis analyze --diff --fail-if-missing --output-format json

# Changes in a pull request (compares against the PR's target branch)
codacy-analysis analyze --pr --fail-if-missing --output-format json

这些标志可与 --tool、--files 及所有其他分析选项配合使用。与 --files 结合时，将使用两者的交集（同时匹配 Git 范围和文件筛选条件的文件）。

性能调优

# Run up to 4 tools in parallel
codacy-analysis analyze --parallel-tools 4 --output-format json

# Increase timeout for slow tools (default: 600000ms = 10 min)
codacy-analysis analyze --tool-timeout 600000 --output-format json

严格模式

默认情况下，不可用的工具会被静默跳过：运行仍以 0 退出，且 issues 数组为空，因此没有运行任何扫描器的扫描看起来也像是干净的。--fail-if-missing 会将其设为硬性中止条件：

codacy-analysis analyze --fail-if-missing --output-format json

分析开始前运行即会停止，并以 2 退出，且 errors[].kind == "UnavailableTools"。应根据此项匹配，而不是根据退出代码，因为退出代码的含义不止一种。

有两点需要注意：此检查涵盖所有已配置的工具，而不仅是与更改文件匹配的工具（可通过 --tool <id> 缩小范围）；此外，它不会发现没有启用任何工具的配置——这种情况下仍会以 0 退出。

详情见：references/trustworthy-results.md。

将输出保存到文件

codacy-analysis analyze --output-format json --output results.json

调试

# Verbose logging to stderr
codacy-analysis analyze --log-level debug --output-format json

# Disable log file writing (e.g., in CI)
codacy-analysis analyze --no-log --output-format json

第 5 步：解读结果

JSON 输出包含完整的 AnalysisResult。完整架构请参阅 references/output-format.md。

解析速查：

# Count issues by severity
codacy-analysis analyze --output-format json | jq '.issues | group_by(.severity) | map({severity: .[0].severity, count: length})'

# Get critical/high issues only
codacy-analysis analyze --output-format json | jq '[.issues[] | select(.severity == "Error" or .severity == "High")]'

# Issues grouped by file
codacy-analysis analyze --output-format json | jq '.issues | group_by(.filePath) | map({file: .[0].filePath, count: length})'

# Check for tool errors
codacy-analysis analyze --output-format json | jq '.errors'

# Per-tool summary
codacy-analysis analyze --output-format json | jq '.toolResults | map({toolId, status, issueCount, durationMs})'

报告“没有问题”之前

只有在工具确实运行过的情况下，空的 issues 数组才有意义：

codacy-analysis analyze --fail-if-missing --output-format json \
  | jq '{blocked: [.errors[].kind], executed: [.toolResults[].toolId], skipped: [.capability.unavailable[].toolId]}'

executed 为空表示没有扫描任何内容——这是未经验证，而不是干净。对于干净的结果，务必注明运行过的工具。

退出代码：

• 0 — 未发现问题 — 只有在 toolResults 非空时才可信
• 1 — 发现问题
• 2 — 执行错误：严格模式下存在不可用工具、标志冲突、--diff 基准无效或工具崩溃（请检查 errors[].kind）。绝不表示结果干净。

常见工作流

快速扫描不在 Codacy 中的代码库

codacy-analysis init
codacy-analysis analyze --install-dependencies --output-format json

仅扫描更改的文件（例如提交前）

这是门禁检查，因此请包含 --fail-if-missing：

# Staged files only (pre-commit check)
codacy-analysis analyze --staged --fail-if-missing --output-format json

# All changes on the current branch
codacy-analysis analyze --diff --fail-if-missing --output-format json

# Changes in a pull request
codacy-analysis analyze --pr --fail-if-missing --output-format json

退出代码 2 表示检查未运行，而不是代码干净：安装缺失的工具（使用 --install-dependencies，单独运行），然后重试。仅在探索性扫描时省略 --fail-if-missing。

在本地复现 Codacy 远程分析

codacy-analysis login --token <token>
codacy-analysis init --remote gh my-org my-repo
codacy-analysis analyze --install-dependencies --output-format json

检查单个文件是否存在问题

codacy-analysis analyze ./src/main.py --output-format json

配置更改后重新扫描

codacy-analysis update-config
codacy-analysis analyze --output-format json

并排测试两种配置

# Baseline config (default location) plus an experimental, broader config
codacy-analysis init
codacy-analysis init --auto AllCritical,AllSecurity --config-file .codacy/experimental.json

# Run each independently and compare the results
codacy-analysis analyze --output-format json --output baseline-results.json
codacy-analysis analyze --config-file .codacy/experimental.json --output-format json --output experimental-results.json

# Promote the extra tools/patterns from the experiment into the baseline
codacy-analysis config --merge --source .codacy/experimental.json --dest .codacy/codacy.config.json

仅运行专注于安全的工具

codacy-analysis analyze --tool Bandit --tool Brakeman --tool Trivy --tool Semgrep --tool Checkov --output-format json

分析 Ruby 项目

codacy-analysis analyze --tool RuboCop --tool Reek --tool Brakeman --output-format json

故障排查

问题	原因	解决方法
Tool X not found / 工具处于 unavailable 状态	未安装工具二进制文件	使用 --install-dependencies 运行；如果失败，请手动安装该工具
分析没有生成结果	未启用任何工具，或没有匹配的文件	重新运行 codacy-analysis init，或检查 .codacy/codacy.config.json 是否已配置工具
检测到的工具有误	语言检测未识别出某些文件	使用 --tool <id> 强制指定工具
工具超时	分析大型代码库耗时过长	增大 --tool-timeout <ms>（默认值为 600000）
添加新语言后配置过时	添加新文件之前就运行了 init	运行 codacy-analysis update-config
初始化时出现 Config already exists	.codacy/codacy.config.json 已存在	改用 update-config，或先删除 .codacy/codacy.config.json
远程初始化因身份验证错误而失败	API 令牌缺失或无效	运行 codacy-analysis login 或设置 CODACY_API_TOKEN
对 ~/.codacy/ 的权限错误	目录所有权不匹配	检查权限：ls -la ~/.codacy/
Inspect 显示工具为 bundled，但工具运行失败	捆绑的库工具存在依赖问题	检查 --log-level debug 输出；可能需要运行 npm rebuild
结果与 Codacy Cloud 不同	工具版本或模式配置不同	使用 init --remote 同步配置；检查 Inspect 输出中的工具版本
退出码为 2，且 errors[].kind == "UnavailableTools"	严格模式下有工具无法运行	运行 --install-dependencies，或使用 --tool <id> 限定工具
结果干净，但没有扫描任何内容	没有为已更改的文件启用工具	检查 toolResults 是否非空；重新运行 init

查看日志

日志以 JSON 行格式写入 ~/.codacy/logs/：

# View latest log
cat ~/.codacy/logs/*.log | jq .

# Filter for errors
cat ~/.codacy/logs/*.log | jq 'select(.level == "error")'

排查工具问题时，使用 --log-level debug 可获取最详细的输出。