codacy-cloud-cli

Codacy Cloud CLI

用語集： Codacy の概念（issue、検出結果、重大度、カバレッジ、ツール、パターンなど）の共通定義については、用語集を参照してください。

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 を指定すると、機械可読な出力を取得できます。

プロバイダーの値

CLI の値（gh、gl、bb）の一覧については、用語集のプロバイダーのセクションを参照してください。

リポジトリパラメーターの自動検出

リポジトリ内で実行すると、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 コミットを反映します — issue の一覧、カバレッジ、セキュリティ検出結果には、ブランチまたはプルリクエストで最後に解析されたコミットの状態が常に表示されます。ファイル単位または行単位の履歴表示はありません。
• 設定変更はすぐには反映されません — ツールやパターンの有効化・無効化、パラメーターの変更、issue の無視は、次回の解析後に初めて反映されます。つまり、--reanalyze で再解析を実行するか、次のコミットがプッシュされるまで待つ必要があります。
• 組織の標準は適用され、リポジトリレベルで上書きできません — 組織レベルの Coding Standard によってパターンが適用されている場合、その有効・無効の状態やパラメーターはリポジトリごとに変更できません。変更するには、組織レベルで標準を更新する必要があります。

再解析

repository または pull-request コマンドで --reanalyze-and-wait（-w）を使用すると、再解析を実行し、完了するまで待機できます。CLI はベースラインを取得して再解析を実行し、10 秒ごとに最大 20 分間ポーリングした後、タイミング情報とともに、パターン、重大度、カテゴリごとの issue の差分を報告します。機械可読な差分レポートを取得するには、--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

--and-wait を指定せずに --reanalyze を使用する場合は、--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

課題（コード品質）

# 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 にも含まれます。これにより、脆弱性がどの関数に影響するかをユーザーに正確に伝え、依存関係をアップグレードするか、検出結果を 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 には影響しません。ローカル設定を Cloud に同期する方法は、--import コマンドのみです。

よくあるワークフロー

リポジトリ内の重大なセキュリティ問題を確認する：

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 を指定して問題／検出結果を無視してください。見つかった場合は、依存関係のアップグレードを推奨してください。

1つまたは複数のリポジトリにまたがる脆弱な依存関係を一度に監査する：

# 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 は、直接依存（パッケージが1つ）か推移的依存（パッケージが2つ以上。チェーンの最初のパッケージをアップグレードする）かを示します。dependencyChains 自体が存在しない場合、Codacy はインポートパスを解決できていないため、直接依存と決めつけず、不明として扱ってください。実際の package.json／ロックファイルのデータで確認した多数の推移的依存パッケージが、チェーンなしで表示されています。上記の各リポジトリについて、ローカルのチェックアウト内で一覧にある関数の呼び出しを検索し、リポジトリごとに、使用の有無、チェーンの状態、推奨事項を報告してください。その後、確認を待ってから、--ignore-reason NotExploitable を指定して無視するか、アップグレードを適用してください。