codacy-cloud-cli

Codacy Cloud CLI

**术语表：**请参阅 glossary.md，了解 Codacy 概念（问题、发现项、严重性、覆盖率、工具、规则等）的通用定义。

Codacy Cloud CLI（codacy）是 Codacy Cloud 的命令行界面。用户希望与远程 Codacy 数据交互时，请使用它。它与 Codacy Analysis CLI（codacy-analysis）是不同的工具，后者会在本地运行静态分析。

设置

# Install
npm install -g @codacy/codacy-cloud-cli

# Authenticate — 3 options:
# 1. Set the `CODACY_API_TOKEN` environment variable
export CODACY_API_TOKEN=<token>
# 2. Use the `codacy login` command (interactive login)
codacy login
# 3. Use the `codacy login` command (with token input)
codacy login --token <token>
# Obtain tokens: Codacy > My Account > Access Management > Account API Tokens (https://app.codacy.com/account/access-management)

# Verify
codacy info

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

获取帮助

CLI 是最权威的信息来源。请始终使用 --help 查看可用命令、选项和当前行为：

codacy --help
codacy <command> --help
# e.g. codacy issues --help

对任何命令使用 --output json，即可获取机器可读的输出。

Provider 值

完整的 CLI 值（gh、gl、bb）列表，请参阅 术语表中的 Provider 部分。

自动检测仓库参数

在仓库内运行时，CLI 会根据 git 远程 origin URL 自动检测 provider、organization 和 repository。因此，大多数命令无需显式指定这些参数：

# Auto-detected (run inside the repo)
codacy issues
codacy repository
codacy pull-request 42

# Equivalent explicit form
codacy issues gh my-org my-repo
codacy repository gh my-org my-repo
codacy pull-request gh my-org my-repo 42

自动检测支持 GitHub、GitLab 和 Bitbucket 远程 URL。如果无法解析远程 URL（例如，使用非标准托管服务），请显式传入参数。为清晰起见，本文档中的示例均采用显式形式；但在仓库内运行时，推荐使用简写形式。

Codacy 数据的工作方式

• 数据反映 HEAD 提交——问题列表、覆盖率和安全发现项始终显示分支或拉取请求中最新分析提交的状态。不提供按文件或按行查看历史记录的功能。
• 配置更改不会立即生效——启用或禁用工具或规则、更改参数以及忽略问题，都要等到下一次分析后才会生效。这意味着需要通过 --reanalyze 触发重新分析，或等待推送下一次提交。
• 组织级标准会强制执行，且无法在仓库级覆盖——如果某条规则由组织级编码标准强制执行，则无法针对单个仓库更改其启用或禁用状态及参数。若要更改，必须在组织级更新该标准。

重新分析

在 repository 或 pull-request 命令中使用 --reanalyze-and-wait（-w），可触发重新分析并等待其完成。CLI 会记录基线、触发重新分析、每 10 秒轮询一次（最长 20 分钟），并按规则、严重性和类别报告问题差异及耗时信息。支持使用 --output json 输出机器可读的差异报告。

# Trigger reanalysis and wait for results (preferred)
codacy repository gh my-org my-repo --reanalyze-and-wait
codacy repository gh my-org my-repo -w -o json    # JSON delta report

# Fire-and-forget reanalysis (no waiting)
codacy repository gh my-org my-repo --reanalyze

使用 --reanalyze（不带 --and-wait）时，请通过不带 --reanalyze 重新运行命令来手动检查进度：

• **表格输出：**查看“Analysis”字段——"Reanalysis in progress..." 表示仍在运行；"Finished X ago" 表示已完成
• **JSON 输出：**比较 startedAnalysis 和 endedAnalysis 时间戳——当 startedAnalysis 晚于触发时间，且 endedAnalysis 晚于 startedAnalysis 时，表示已完成

命令参考

账户和仓库

# Authenticated user and organizations
codacy info

# List repositories in an organization
codacy repositories <provider> <org>
codacy repositories gh my-org --search my-repo

# Repository dashboard (metrics, PRs, issues overview)
codacy repository gh my-org my-repo
codacy repository gh my-org my-repo --add       # add to Codacy
codacy repository gh my-org my-repo --remove    # remove from Codacy
codacy repository gh my-org my-repo --follow    # follow repository
codacy repository gh my-org my-repo --unfollow  # unfollow repository
codacy repository gh my-org my-repo --reanalyze            # trigger reanalysis (fire-and-forget)
codacy repository gh my-org my-repo --reanalyze-and-wait   # trigger and wait for completion with delta report
codacy repository gh my-org my-repo --link-standard <id>   # link a coding standard
codacy repository gh my-org my-repo --unlink-standard <id> # unlink a coding standard

Issues（代码质量）

# List issues with optional filters
codacy issues gh my-org my-repo
codacy issues gh my-org my-repo --branch main --severities Critical,High
codacy issues gh my-org my-repo --categories Security
codacy issues gh my-org my-repo --tools eslint,semgrep        # filter by detecting tool
codacy issues gh my-org my-repo --limit 500                    # fetch up to N results (default 100, max 1000)

# Overview: totals grouped by category/severity/language
codacy issues gh my-org my-repo --overview                     # short flag: -O
codacy issues gh my-org my-repo -O -o json                     # JSON — includes per-pattern issue counts and false positive counts

--overview 输出包含：

• 误报数量，按模式统计，并标记为“非误报”／“可能的误报”
• 减少噪声的建议操作——识别出占所有问题 10% 以上，或达到每种模式平均数量 3 倍的问题模式，并为每种模式生成可直接运行的 codacy pattern 禁用命令。如果某个模式由编码标准强制执行或使用配置文件，建议会相应调整（例如，建议修改编码标准或配置文件）

# Full details for a single issue
codacy issue gh my-org my-repo <issueId>

# Ignore / unignore an issue
codacy issue gh my-org my-repo <issueId> --ignore
codacy issue gh my-org my-repo <issueId> --ignore --ignore-reason FalsePositive --ignore-comment "Not applicable here"
codacy issue gh my-org my-repo <issueId> --unignore

# Bulk-ignore all issues matching filters
codacy issues gh my-org my-repo --severities Minor --categories CodeStyle --ignore

筛选条件：--branch、--patterns、--severities（Critical、High、Medium、Minor）、--categories、--languages、--tools、--tags、--authors

忽略原因：AcceptedUse（默认）| FalsePositive | NotExploitable | TestCode | ExternalCode

**受影响的函数：**对于关联了已知受影响函数公告（CVE 或 GHSA）的 SCA 问题，issues／issue 会在常规输出旁显示这些函数——在列表／卡片视图中显示简洁的 Vulnerable functions: fn1, fn2 (+N more) 行，在 codacy issue 详情视图中显示包含发布日期的完整 Vulnerable Functions (<advisoryId>) 区块。如果存在，始终会包含在 --output json 中。利用此信息准确告知用户漏洞影响哪些函数，以便他们（或其编码 Agent）在决定升级依赖项或将问题标记为 NotExploitable 并忽略之前，检查代码是否实际调用了这些函数。

安全问题

# List findings
codacy findings gh my-org my-repo
codacy findings gh my-org                       # org-wide
codacy findings gh my-org my-repo --severities Critical,High
codacy findings gh my-org my-repo --statuses Overdue,DueSoon
codacy findings gh my-org my-repo --limit 500   # fetch up to N results (default 100, max 1000)

# Full details for a single finding (includes CVE data and, for SCA findings, affected functions)
codacy finding gh my-org my-repo <findingId>

# Ignore / unignore a finding
codacy finding gh my-org my-repo <findingId> --ignore
codacy finding gh my-org my-repo <findingId> --ignore --ignore-reason FalsePositive --ignore-comment "Verified safe"
codacy finding gh my-org my-repo <findingId> --unignore

筛选条件：--search、--severities（Critical、High、Medium、Low）、--statuses（Overdue、OnTrack、DueSoon、ClosedOnTime、ClosedLate、Ignored）、--categories、--scan-types、--dast-targets

忽略原因：AcceptedUse（默认）| FalsePositive | NotExploitable | TestCode | ExternalCode

上述 issues／issue 的受影响函数行为同样适用于 findings／finding（在列表中显示简洁行，在详情视图中显示完整区块）。

拉取请求

# PR summary (status, issues, coverage, changed files)
codacy pull-request gh my-org my-repo <prNumber>

# Annotated git diff with coverage and inline issues
codacy pull-request gh my-org my-repo <prNumber> --diff

# Full details for a specific issue within the PR
codacy pull-request gh my-org my-repo <prNumber> --issue <issueId>

# Ignore a specific issue in the PR
codacy pull-request gh my-org my-repo <prNumber> --ignore-issue <issueId>
codacy pull-request gh my-org my-repo <prNumber> --ignore-issue <issueId> --ignore-reason FalsePositive
codacy pull-request gh my-org my-repo <prNumber> --unignore-issue <issueId>

# Ignore all potential false positive issues in the PR at once
codacy pull-request gh my-org my-repo <prNumber> --ignore-all-false-positives

# Trigger reanalysis of PR HEAD commit
codacy pull-request gh my-org my-repo <prNumber> --reanalyze
codacy pull-request gh my-org my-repo <prNumber> --reanalyze-and-wait   # trigger and wait for completion

工具和模式

# List all tools (enabled/disabled)
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 eslint --disable
codacy tool gh my-org my-repo eslint --configuration-file true

# List patterns for a tool
codacy patterns gh my-org my-repo eslint
codacy patterns gh my-org my-repo eslint --enabled --categories Security
codacy patterns gh my-org my-repo pylint --search W0123

# Full details for a specific pattern (description, parameters, severity, category)
codacy pattern gh my-org my-repo eslint no-unused-vars

# Enable, disable, or configure a pattern
codacy pattern gh my-org my-repo eslint no-unused-vars --enable
codacy pattern gh my-org my-repo eslint no-unused-vars --disable
codacy pattern gh my-org my-repo eslint max-len --parameter max=120

# Enable or disable all patterns matching specific filters
codacy patterns gh my-org my-repo eslint --categories Security --severities Critical,High --enable-all
codacy patterns gh my-org my-repo pylint --categories CodeStyle --severities Minor --disable-all

配置文件和编码标准感知：

• 当工具使用本地配置文件（--configuration-file true）时，codacy patterns 会跳过获取托管模式（这些模式不适用）
• 当某个模式由编码标准强制执行时，--enable／--disable 会拒绝操作，并提示强制执行该模式的标准。请改为在组织级别更新编码标准，或先从代码仓库中解除该标准的关联（codacy repository ... --unlink-standard <id>）

模式搜索提示：Codacy 模式 ID 由工具前缀和原始 ID 组成。使用原始 ID 配合 --search 查找模式：

codacy patterns gh my-org my-repo semgrep --search HttpGetHTTPRequest
codacy patterns gh my-org my-repo pylint --search W0123

导入配置

# Import tool and pattern configuration from a local config file
codacy tools gh my-org my-repo --import                          # imports from .codacy/codacy.config.json (default path)
codacy tools gh my-org my-repo --import ./custom-config.json     # imports from a custom path
codacy tools gh my-org my-repo --import -y                       # skip confirmation prompt
codacy tools gh my-org my-repo --import --force -y               # unlink coding standard first, then import

--import 标志会读取本地 .codacy/codacy.config.json（或指定路径），并将工具和模式配置应用到 Codacy Cloud 代码仓库。使用 -y（--skip-approval）跳过交互式确认。使用 --force 在导入前解除代码仓库与编码标准的关联；当组织级标准阻止模式更改时，必须使用此选项。

导入行为：

• 导入时保留仅限云端的工具——只修改本地支持的工具；仅限云端的工具（例如 SonarSharp、Codacy ScalaMeta Pro）会保留现有的启用／禁用状态
• 正确处理配置文件模式——当工具使用本地配置文件时，导入会跳过重置其托管模式（这些模式不适用）
• 导入失败时显示结构化的 API 错误详情，包括发生冲突的工具／模式及原因

注意：.codacy/codacy.config.json 文件仅用于本地分析。将其提交到代码仓库不会影响 Codacy Cloud。--import 命令是将本地配置同步到 Cloud 的唯一方式。

常见工作流

检查仓库中的关键安全问题：

codacy findings gh my-org my-repo --severities Critical,High

审查 PR 引入的内容：

codacy pull-request gh my-org my-repo 42
codacy pull-request gh my-org my-repo 42 --diff

了解特定问题：

codacy issue gh my-org my-repo <issueId>   # includes pattern docs and code context

触发重新分析并等待结果：

codacy repository gh my-org my-repo --reanalyze-and-wait
codacy repository gh my-org my-repo -w -o json    # JSON delta report with issue changes by pattern/severity/category

识别并减少噪声：

codacy issues gh my-org my-repo --overview        # see false positive counts and suggested actions to reduce noise

检查易受攻击的依赖项是否确实可达：

codacy issue gh my-org my-repo <issueId>          # or: codacy finding gh my-org my-repo <findingId>

如果输出包含 Vulnerable Functions 块，请在仓库中搜索对这些函数的调用（包括重新导出和包装函数）。如果找不到任何调用，请使用 --ignore-reason NotExploitable 忽略该问题／发现项；否则建议升级依赖项。

一次审计一个或多个仓库中的易受攻击依赖项：

# one repo
codacy findings gh my-org my-repo --scan-types SCA --output json

# multiple repos
for repo in my-repo-one my-repo-two; do
  codacy findings gh my-org "$repo" --scan-types SCA --output json
done | jq -s '{findings: (map(.findings) | add)}'

仅保留 advisoryInformation.vulnerableFunctions 为非空数组的发现项——该字段有时会存在但为空，这表示无法进行可达性检查。对于每项，dependencyChains 会说明它是 Direct（单个包）还是 Transitive（2 个或更多包——链中的第一个包是需要升级的包）；如果完全缺少 dependencyChains，则表示 Codacy 尚未解析导入路径，应将其视为未知，而不是假定为 Direct——许多传递依赖包（经真实 package.json／锁文件数据验证）都没有依赖链信息。对于上面列出的每个仓库，请在本地检出目录中搜索对所列函数的调用，然后按仓库逐一报告——是否使用、依赖链状态和建议——并等待确认后再使用 --ignore-reason NotExploitable 忽略任何内容或应用升级。