codacy-analysis-cli

Codacy Analysis CLI

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

Codacy Analysis CLI（codacy-analysis）は、リポジトリの静的解析をローカルで実行します。コードを Codacy にプッシュすることなく、言語を検出し、ツールを選択して、issue を報告します。リモートの Codacy データを照会する Codacy Cloud CLI（codacy）とは別のツールです。

エージェントワークフローで構造化出力を使用する場合は、必ず --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 は、管理対象の場所を 2 つ使用します。

場所	スコープ	内容
.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 Lines 形式、10 MB でローテーション）

プロバイダーの値

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

解析ワークフロー

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 リポジトリから設定を再取得します。

update-config は --remote で初期化した設定にのみ使用してください。 --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 コマンドは、2 つの設定ファイルに対して集合演算を行い、ツールとパターンを結合します。実験用の設定をベースラインと調整する際に使用します。

# 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 のうち、必ず 1 つを指定してください。
• --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

出力には、検出された言語、フレームワーク、および該当するツールが一覧表示されます。どのツールとパターンを有効にするかを決める際に活用してください。

サポート対象ツールの一覧表示

ローカルの Analysis CLI で利用可能なツールを確認するには、info を使用します。

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 つを組み合わせると、終了コード 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

不足しているツールをインストールしてから、1 つのコマンドで分析を実行します。インストールされたバイナリは ~/.codacy/ に配置され、マシン全体を対象とするため、複数のリポジトリで再利用されます。

最終手段：手動インストール — 特定のツールで --install-dependencies が失敗した場合は、マシンに手動でインストールします（例：brew install shellcheck、pip install ruff）。ツールの詳細については、references/supported-tools.md を参照してください。

ステップ 4：分析を実行する

エージェント型ワークフローでは、常に --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

厳格モード

デフォルトでは、利用できないツールは通知なくスキップされます。実行は空の issues 配列を返して終了コード 0 で終わるため、スキャナーが一つも実行されていないスキャンも問題なしと見なされます。--fail-if-missing を指定すると、処理を中断します：

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

解析前に実行が停止し、errors[].kind == "UnavailableTools" で終了コード 2 を返します。終了コードは複数の意味に使われるため、終了コードではなく、この値で判定してください。

注意点が2つあります。このチェックの対象は、変更されたファイルに一致するものだけでなく、設定されているすべてのツールです（--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

1つのファイルに問題がないか確認する

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

設定変更後に再スキャンする

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

2つの設定を並べてテストする

# 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 です）
新しい言語を追加した後、設定が古いままです	新しいファイルを追加する前に初期化を実行しました	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 Lines 形式で ~/.codacy/logs/ に書き込まれます：

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

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

ツールの問題をトラブルシューティングする際、最も詳細な出力を得るには --log-level debug を使用してください。