コンテンツにスキップ

CLIコマンド

pyfltrのサブコマンド・主要オプション・出力形式・コーディングエージェント連携を扱うリファレンス。 導入手順ははじめにを参照。

サブコマンド

pyfltrはサブコマンドで動作モードを指定する。

pyfltr <subcommand> [files and/or directories ...]

サブコマンド: ci

pyfltr ci [files and/or directories ...]

全チェック実行。CI環境やコミット前の検証に適する。

終了コード:

  • 0: Formattersによるファイル変更が無く、かつLinters/Testersでのエラーも無い場合
  • 1: 上記以外の場合

サブコマンド: run

pyfltr run [files and/or directories ...]

全チェック実行。 Formattersによるファイル変更があってもLinters/Testersでのエラー無しなら終了コードは0になる。 ローカルでの全チェック実行に適する。

サブコマンド: fast

pyfltr fast [files and/or directories ...]

pre-commitフックなどで実行しても作業に支障が出にくい高速なコマンドだけを実行する軽量チェック。 mypy / pylint / pytestなど起動やファイルあたりの処理に時間がかかるコマンドは除外される。 Formattersによるファイル変更があっても終了コードは0になる。

有効化しているツールのうち{command}-fast = trueのものが対象で、内訳は以下。

  • Formatters: prettier ruff-format uv-sort shfmt taplo cargo-fmt dotnet-format
  • Linters（言語非依存）: ec shellcheck typos actionlint pinact yamllint hadolint colloquial-check
  • Linters（言語・記法別）: ruff-check ty markdownlint textlint biome oxlint cargo-clippy
  • その他: pre-commit・prek（.pre-commit-config.yamlのhookを統合実行）

含まれるコマンドは各コマンドの{command}-fast設定で制御できる（設定を参照）。

サブコマンド: run-for-agent

pyfltr run-for-agent [files and/or directories ...]

runと同じ動作で出力形式の既定値をjsonlに切り替え、--quietを既定値として有効にしたサブコマンド。 互換維持のために残しており、通常はrunを使う。 AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定された環境では runも同じ既定値になるため、両者は等価に振る舞う。 これらの環境変数が無い環境で明示的にJSON Lines出力と静音モードを得たい場合に指定する。 PYFLTR_OUTPUT_FORMAT=textでtextへ戻すことができ、--no-quietで静音モードを解除できる。

出力形式の詳細はjsonl形式の使い方を参照。

サブコマンド: config

pyfltr config <action> [options]

設定ファイルをCLIから操作する（pnpm/npm config互換の体系）。 --globalなしはカレントディレクトリのpyproject.toml、--global付きはグローバル設定ファイル （~/.config/pyfltr/config.tomlなど）が対象となる。

config get

pyfltr config get <key> [--global]

指定キーの現在値を1行出力する。ファイルに書かれていなければデフォルト値を返す。 未知のキーはエラー終了（終了コード1）。

pyfltr config get archive-max-age-days
pyfltr config get archive-max-age-days --global

config set

pyfltr config set <key> <value> [--global]

指定キーに値を書き込む。値の文字列はキーのデフォルト値の型に応じて変換される。

  • bool: true / false / 1 / 0
  • int: 整数表記
  • str: そのまま文字列として設定する
  • list[str]: カンマ区切りで分割してリスト化する（例: "foo,bar" → ["foo", "bar"]）
  • dict: CLI非対応（エラー終了）
pyfltr config set archive-max-age-days 30 --global
pyfltr config set preset latest

--global指定時、グローバル設定ファイルが存在しなければディレクトリを含めて自動作成する。 project側（--globalなし）でpyproject.tomlが存在しない場合はエラー終了する。 未知のキーはエラー終了（終了コード1）。

set時の警告条件:

  • archive/cache系のキー（archive / archive-max-runs等）をproject側にsetした場合: globalで集約するよう促す警告を出力する。
  • archive/cache以外のキーをglobal側にsetした場合: 通常はproject側が優先されるため、globalで設定しても上書きされる旨の警告を出力する。

config delete

pyfltr config delete <key> [--global]

設定ファイルから指定キーを削除する。 該当キーがなければ正常終了（何もしない）。 対象ファイルが存在しない場合は「削除対象がありません」と表示して正常終了する。 未知のキーはエラー終了（終了コード1）。

config list

pyfltr config list [--global] [--all] [--output-format text|json|jsonl]

設定ファイルに書かれているキーと値の一覧を表示する。 --all未指定時は明示された値のみを挿入順で表示する。 --all指定時はデフォルト値のままのキーも含めて全件をキー昇順で表示し、既定値か明示値かを区別する。

--all未指定時の出力形式は次の通り。

  • text（既定）: key = value形式の行出力
  • json: {"values": {...}}の単発出力
  • jsonl: 1件1行の{"key": ..., "value": ...}ストリーム

--all指定時は各出力形式に既定値か明示値かの区別を追加する。

  • text: 既定値の行末に(default)を付加する（明示値には何も付かない）
  • json: {"values": {key: {"value": ..., "default": bool}, ...}}の二段構造
  • jsonl: {"key": ..., "value": ..., "default": bool}の1行1レコード

設定項目の一覧とデフォルト値を確認したい場合は、pyfltr config list --allで全件を確認できる。 設定項目名の詳細は設定項目一覧を参照。

サブコマンド: list-runs

pyfltr list-runs [--limit N] [--output-format text|json|jsonl]

実行アーカイブに保存されたrun一覧を新しい順で表示する。

  • 既定は直近20件（--limitで変更可能）
  • text: 固定幅テーブル。列はRUN_ID / STARTED_AT / EXIT / FILES / COMMANDS
  • json: {"runs":[{...}, ...]}の単発出力
  • jsonl: 1件1行ストリーム（kind: "run"）

アーカイブ未作成の環境では(no runs)を出力し、終了コードは0。

サブコマンド: show-run

pyfltr show-run <run_id> [--commands NAME[,NAME...]] [--output] [--output-format text|json|jsonl]

指定runの詳細を表示する。

  • <run_id>: ULID完全一致のほか、先頭一意な前方一致とlatestエイリアスを受け付ける。 前方一致で複数該当した場合は曖昧エラー（終了コード1）
  • 既定: meta（run_id・started_at・finished_at・exit_code・files・commands）と ツール別サマリ（status / diagnostics）を表示
  • --commands NAME[,NAME...]: 指定ツールのtool.jsonとdiagnostics.jsonl全件を表示。 カンマ区切りで複数指定可（入力順で並ぶ）
  • --commands NAME --output: 指定ツールの生出力（output.log）全文を表示（単一指定のみ）
  • --output-format: textは行形式key: value、jsonは単発dictとして表示する。 jsonlはkindごとの1行1レコードとして表示し、kindはmeta・command・diagnostic・outputの いずれかとなる

存在しないrun_id・--commands指定時は終了コード1で標準エラーにメッセージを出力する。

同じツールがfixステージと通常ステージの両方で実行された場合、アーカイブの保存キーはツール名固定のため 通常ステージ側の結果で上書きされる（show-runで参照できるのは各ツールの最終保存結果のみ）。

サブコマンド: grep

pyfltr grep <pattern> [paths...]

正規表現でファイルを横断検索する。 pyfltr設定のexclude/extend-exclude/respect-gitignoreを尊重するため、 node_modulesやbuild配下のノイズが混入しない。 コーディングエージェント環境では、多数の一致を持つファイルだけを件数表示へ縮約し、低密度ファイルの本文を維持する。

例:

pyfltr grep "TODO" src/
pyfltr grep -i "deprecated" .
pyfltr grep -F "exact_string" --output-format=jsonl docs/

詳細は検索と置換を参照。

サブコマンド: replace

pyfltr replace <pattern> <replacement> [paths...]

正規表現で横断置換する。書き込みが既定動作で、--dry-runで試行できる。 実行アーカイブに履歴を保存し、--undoで取り消せる。

例:

# 試行（書き込みなし）
pyfltr replace --dry-run "old_name" "new_name" src/
# 実書き込み（履歴に保存される）
pyfltr replace "old_name" "new_name" src/
# 直前のreplaceを取り消す
pyfltr replace --undo <replace_id>

詳細は検索と置換を参照。

サブコマンド: mcp

pyfltr mcp

stdioトランスポートでMCPサーバーを起動する。 追加オプションはなく、起動後はstdin/stdoutをJSON-RPCフレームが専有する。 MCPクライアントがstdinを閉じた時点でサーバーが終了する。

提供するMCPツール（11件）:

ツール名 対応CLI 説明
list_runs pyfltr list-runs run一覧を新しい順で返す。limitで件数制御（既定20件）
show_run pyfltr show-run <run_id> 指定runのmetaとツール別サマリを返す。前方一致・latestエイリアス可
show_run_diagnostics pyfltr show-run <run_id> --commands=<name> 指定runのコマンドmeta情報とdiagnostics全件を返す（複数指定可）。チェック対象ファイルの引数列は含めない
show_run_output pyfltr show-run <run_id> --commands=<name> --output 指定runのoutput.log全文を返す（複数指定可）
run pyfltr run / fast / ci lint/format/testを実行しrun_id・失敗ツール名・retry_commands・警告（対処を含む）・次の操作の案内等を返す。modeで実行モードを選ぶ
grep pyfltr grep ファイル横断の正規表現検索（pyfltr exclude/.gitignore尊重）
replace pyfltr replace 横断置換。dry_runの既定値はTrue（CLI既定のFalseと異なりLLM暴発防止）
replace_undo pyfltr replace --undo 過去のreplaceを取り消す
replace_history pyfltr replace --list-history / --show-history <ID> replace履歴を一覧または単体で返す
command_info pyfltr command-info <command> ツール起動方式の解決結果を返す。check=Trueは副作用を伴う
config pyfltr config <action> 設定ファイルを操作する（get / set / delete / list）

コーディングエージェント側へのMCPサーバー登録例（JSON形式で設定ファイルに記載する場合）:

{
  "mcpServers": {
    "pyfltr": {
      "command": "uvx",
      "args": ["pyfltr", "mcp"]
    }
  }
}

エージェント常駐起動では、独立venvで動くuvxの方がプロジェクトのpyproject.toml解釈やcwd依存の影響を受けない。

Claude Codeから登録する場合はclaude mcp addコマンドを利用できる:

claude mcp add pyfltr -- uvx pyfltr mcp

pyfltr mcpでMCPサーバーを起動すると、コーディングエージェントがCLIで可能な操作を 原則としてMCPツールから呼び出せる。 端末表示・出力先の制御と--no-archiveはMCPへ露出せず、ツール固有の引数を任意の文字列で 上書きする--{tool}-argsも露出しない。 CLIの直接呼び出しとは異なりJSONL出力がstdoutに流れず、 MCPクライアントは結果を構造化データとして1件の応答で受け取れる。 ただしpyfltr mcp起動後は同一プロセスのstdin/stdoutがJSON-RPCに専有されるため、 他のコマンドと組み合わせた場合に出力が混在する点に注意する （詳細はトラブルシューティングを参照）。

runの主要パラメーターとCLI相当オプションは次のとおり。

MCPパラメーター CLI相当
mode サブコマンドのrun / fast / ci
work_dir --work-dir
commands --commands
no_fix --no-fix
only_failed --only-failed
changed_since --changed-since
shuffle --shuffle
exit_zero_even_if_formatted --exit-zero-even-if-formatted

runの応答は次の順に読む。

  1. completionを読む。 completedなら、指定した全対象へ到達し、全コマンドが対象を評価し終えている。 incompleteは一部のコマンドまたは対象が未完了、not_reachedはどのコマンドも対象を評価しなかったことを示す
  2. completed以外の場合は、incomplete_commands・missing_targets・fully_excluded_files・ skipped_reason・warningsから未完了の理由を確認し、指定したパスやコマンドを直して再実行する
  3. failedが空でなければ、show_run_diagnosticsで診断を取得して修正する。 retry_commandsとonly_failedで失敗したコマンドだけを再実行できる

exit_codeは診断・formatterによる書き換え・ツール失敗の有無を表し、対象へ到達したかは表さない。 診断を検出してexit_codeが1になった実行でも、チェックが対象を評価し終えていればcompletionはcompletedとなる。 一部の対象が不在でも他の対象のチェックが成功すればexit_codeは0となるが、completionはincompleteとなる。

サブコマンド: command-info

pyfltr command-info <tool> [--output-format text|json|jsonl] [--check]

対象ツールの起動方式（runner種別・実行ファイルパス・最終コマンドライン）の解決結果を副作用無しで表示する。 pyproject.tomlの{command}-runner設定やpython-runner / js-runner / bin-runnerの影響を 実環境で確認する場合に使う。

出力はセクション見出し（## 実行コマンド / ## ランナー解決 / ## mise診断 / ## 設定 / ## 環境変数） で関連項目をまとめる。 情報が無いセクションは省略される。

mise設定（プロジェクトmise.tomlまたはグローバル設定）にrust記述がある場合の出力例:

$ pyfltr command-info cargo-fmt
# cargo-fmt

## 実行コマンド

commandline: mise exec -- cargo fmt
executable: mise
executable_resolved: /home/user/.local/bin/mise

## ランナー解決

runner: bin-runner (default)
effective_runner: mise
mise_tool_spec_omitted: True

## mise診断

mise_active_tool_key: rust
mise_active_tools.status: ok
mise_active_tools.active_keys: rust

## 設定

enabled: True
configured_args: fmt
version: latest

tool specを省略したmise exec -- cargo fmt形になり、mise設定の解決済み内容（バージョン固定・components等）が反映される。 mise設定にrust記述が無い場合はmise exec rust@latest -- cargo fmt形になる。

応答フィールドの接頭辞は値の出所を表す。 configured_で始まるものは既定値・グローバル設定・プロジェクト設定を統合した パス・引数系の実効設定値である。 check_で始まるものは--check指定時のみ実行して得られる値である。 接頭辞を持たない設定由来フィールドはenabled・severity・hints・versionである。 このほかの接頭辞を持たないフィールドは解決状態または環境情報を表す。 versionは{command}-version設定値であり、実際にインストールされている版ではない。 実行版は--check指定時かつ事前確認に成功した場合のcheck_installed_versionが返す。 この値は解決済みコマンドラインへ--versionを渡した結果である。 cargo-fmtなどのサブコマンド型ツールでは基底ツールの版となる。

{command}-fix-argsが定義されているコマンド（textlint・markdownlintなど）では、 commandline (fix step):とcommandline (check step):を併記する。 fix段とcheck段の二度実行が異なる引数を必要とするためである。

$ pyfltr command-info textlint
# textlint

## 実行コマンド

commandline (fix step): pnpm --config.enableGlobalVirtualStore=false --package textlint --package ... dlx textlint --fix
commandline (check step): pnpm --config.enableGlobalVirtualStore=false --package textlint --package ... dlx textlint --format json
...

textlintの場合、fix段では@textlint/fixer-formatterがcompactをサポートしない。 このためユーザーが指定した--formatペアを除去した形が表示される。 check段ではtextlint-json設定（既定true）により出力フォーマット指定--format=jsonが注入される。

主要なオプション。

  • --output-format=text|json|jsonl: 出力形式を切り替える（既定text）。 未指定時は環境変数PYFLTR_OUTPUT_FORMATを、AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTの いずれかが設定されていればjsonlを採用する
  • --check: 実行時と同じ事前チェックを行う （mise経由ツールはmise exec --versionでの可用性確認、パッケージマネージャー系ツールは最低版の確認） 事前確認に成功した場合は解決済みコマンドラインへ--versionを渡し、実行版をcheck_installed_versionとして返す。 取得できなかった場合はnullを返す。--check未指定時と事前確認失敗時はそのフィールドを出力しない。 （mise install / mise trust / --versionの起動が発生する場合があるため、既定の動作では行わない）

未知のコマンド名や{command}-runner = "mise"を未登録ツールに指定した場合などは終了コード1で失敗する。

サブコマンド: generate-shell-completion

pyfltr generate-shell-completion bash
pyfltr generate-shell-completion powershell

シェル補完スクリプトを標準出力に出力する。 引数にシェル種別（bashまたはpowershell）を指定する。

bashでの設定例:

eval "$(pyfltr generate-shell-completion bash)"

PowerShellでの設定例:

pyfltr generate-shell-completion powershell | Out-String | Invoke-Expression

永続化する場合はプロファイルに上記を追記。

[files and/or directories ...]

対象を指定しなかった場合は、カレントディレクトリ(.)を指定した場合と同じ扱いとなる。

指定したファイルやディレクトリの配下のうち、各コマンドのtargetsパターンに一致するファイルのみ処理される。 一例を以下に示す。

  • Python系ツール: *.py
  • textlint / markdownlint: *.md
  • pytest: *_test.py

外部パス指定時の挙動

起点cwd（--work-dir適用後の作業ディレクトリ）配下にない絶対パスを「外部パス」と呼ぶ。 ツールの性質に応じて以下の3分類で扱う。

  • --config明示注入: markdownlint ・ textlint
  • 外部パス除外＋警告: markdownlint・textlint・pre-commit・prek・uv-audit・ pnpm-audit・npm-audit・yarn-audit・pytest・vitest・cargo-test・ dotnet-test・gitleaks・semgrep
  • 既定（素通し）: 上記以外。各ツールの設定探索仕様に委ねる

注入対象では起点cwd直下の設定ファイル（.textlintrc.yaml ・ .markdownlint-cli2.yaml 等）を --config <絶対パス> 形式で明示注入する。 起点cwd直下に設定ファイルが見つからないときは注入をスキップし、ツールの既定動作で処理する。 利用者が {command}-args ・ {command}-extend-args ・ CLI --{command}-args のいずれかで --config を指定している場合は注入をスキップする。

除外対象では対象ファイル展開後の最終リストから外部パスのみを除いて内部パスは対象として実行し、 除外時は1ファイルにつき1件の警告を発行する。 markdownlint ・ textlint は--config注入対象でありながら除外対象でもある。 外部パスを直接渡すと textlint ・ markdownlint-cli2 の対象探索エラーが未整形のまま出力されるためである。

既定の動作では除外対象ツールへ外部パスを渡すと対象から除外し、1ファイルにつき1件の警告を発行する。 --allow-external-pathsを指定するとこの分類を上書きし、外部パスを対象へ保持して除外警告を発行しない。

markdownlint ・ textlint では、起点cwd直下から解決した設定ファイルを --config <絶対パス>形式で明示注入する。 フラグ指定時も設定探索の基準は外部ファイルの配置先へ移らず、起点cwdの設定を外部ファイルへ適用する。

外部のMarkdownファイルだけをチェックする場合は、対象外のtesterや監査ツールへ外部パスを渡さないよう --commandsで実行ツールを限定する。

pyfltr run --allow-external-paths --commands=textlint,markdownlint ~/.claude/plans/example.md

事前チェック領域からの除外

--exclude-fence-under=<H2見出し>オプションを指定すると、Markdownファイル内で指定H2見出し配下の フェンス内側行をtextlint・markdownlintのチェック対象から除外する。 フィードバック原文の転記領域などlint違反が原文由来で不可避な区間のチェック除外を想定する。 改行数は保存されるため診断出力の行番号は元ファイル基準となる。 行内文字数は保存されず、フェンス内側行は空行化する（markdownlint MD013 line-lengthなど 長さ由来ルールの発火を防ぐため）。 改行なしEOF最終行は短い空白へ置換する。 [tool.pyfltr]側でもexclude-fence-under = ["## 背景"]形式で指定できる。

fast / run / ciの動作の違いと自動修正（fixステージ）

各サブコマンドの主な違いを以下に示す（軽い順）。

項目 fast run ci
対象コマンド {command}-fast = trueのツールのみ 有効な全ツール 有効な全ツール
fixステージ（自動修正） 有効 有効 無効
Formatterによる変更時の終了コード 0（成功扱い） 0（成功扱い） 1（失敗扱い）
Linters / Testersのエラー時の終了コード 1 1 1
既定の出力形式 text（注） text（注） text（注）
--quiet既定 無効（注） 無効（注） 無効（注）
主な用途 pre-commitフック等 ローカルで全チェック CI・コミット前

（注）AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定された環境では、 fast / run / ciの既定の出力形式はjsonl、--quiet既定は有効となる。

ciで「Formatterによる変更時の終了コード」を0（成功扱い）へ変更する場合は --exit-zero-even-if-formattedを指定する（UI節のオプション一覧を参照）。

fast / run サブコマンドは、formatter段の前にfixステージを内蔵する。

fixステージでは{command}-fix-argsが定義された有効なlinterを--fix付きで順次実行する。 対象ツールはruff-check / textlint / markdownlint / eslint / biome / cargo-clippyなど。 ruff check --fix → ruff format → ruff checkのような2段階処理をpyfltrのパイプライン全体で実現する位置づけ。

カスタムコマンドでもpyproject.tomlの[tool.pyfltr.custom-commands.<name>]にfix-args = [...]を定義すれば fixステージの対象になる。

fixステージの抑止（--no-fix）

--no-fix（MCPではno_fix）を指定するとfixステージを実行しない。 診断内容の確認だけを目的に実行する場合など、自動修正で診断が消えると困るときに使う。

pyfltr run --no-fix --commands=ruff-check [files and/or directories ...]

抑止の対象はfixステージ（{command}-fix-argsを持つlinter）だけである。 formatterは通常ステージで対象ファイルを書き込むため、--no-fixを指定しても整形は行われる。 特にruff-format-by-checkが既定値として有効なため、ruff-formatは--no-fixの指定時も ruff check --fix --unsafe-fixesを先に実行し、未使用importの削除など整形以外の修正まで及ぶ。

対象ファイルの書き換えを避けたい場合は、--no-fixに加えて--commandsで対象をlinterへ限定する。

特定のツールのみ実行

pyfltr ci --commands=ruff-check,markdownlint [files and/or directories ...]

カンマ区切りで実行するツールだけ指定する。全サブコマンドで使用可能。 --commandsは複数回指定も可能で、カンマ区切りと併用できる。 例えば--commands=mypy --commands=pyright,ruff-checkは--commands=mypy,pyright,ruff-checkと同じになる。

以下のエイリアスも使用可能。(例: --commands=format)

  • format: prettier ruff-format uv-sort shfmt taplo cargo-fmt dotnet-format prek pre-commit。
  • lint: ec shellcheck typos actionlint pinact glab-ci-lint yamllint hadolint gitleaks。 semgrep bandit pylint mypy ruff-check pyright ty arid markdownlint。 textlint designmd lychee colloquial-check tsc eslint biome oxlint cargo-clippy。 cargo-check cargo-deny dotnet-build sqlfluff uv-audit pnpm-audit npm-audit yarn-audit。
  • test: pytest vitest cargo-test dotnet-test。
  • audit: uv-audit pnpm-audit npm-audit yarn-audit。
  • fast: per-commandの{cmd}-fastフラグがtrueのコマンド。

※ pyproject.tomlの[tool.pyfltr]で無効になっているコマンドは無視される。

一時的に有効・無効を切り替えたい場合は--enable・--disableを使う。

# 通常無効化しているsemgrepを1回だけ実行する
pyfltr run --enable=semgrep --commands=semgrep

# 通常有効なmypyを1回だけ抑止する
pyfltr run --disable=mypy

--enable・--disableは--commandsと同じくカンマ区切り・複数回指定を併用できる。 同一コマンドを両方に指定した場合は--enableが優先される。 永続的に有効・無効を切り替える場合はpyfltr config setを使う。

--commandsで指定したコマンドのうち、pyproject.toml側で有効化されていないため実行されないものがある場合は 警告レコード（source: "commands"）が出力される。 --enableまたはpyproject.tomlの[tool.pyfltr]で指定したコマンドをtrueに設定すると実行される。

エイリアス名（format・lint・test・audit・fast）で指定した場合は、 展開結果に有効化済みのコマンドが1件以上あれば未有効化コマンドの警告を出力しない。 エイリアスは該当するものを実行する意味で使うため、一部のみ有効な構成を正常とみなす。 展開結果が全て未有効化の場合は実行対象が空になるため警告を出力する。 コマンド名を個別に指定した場合は、エイリアスとの併記の有無にかかわらず従来どおり警告を出力する。

特定のツール1件だけを実行したいときは--commands=<tool>オプションを使う。

pyfltr run --commands=textlint docs/
pyfltr run --commands=mypy src/

サブコマンドはrunを利用する。 pyfltr textlint docs/のようにツール名をそのままサブコマンドへ書くことはできない （誤入力を検知した場合は実行例付きのエラーメッセージが表示される）。

JSONL出力に含まれるcommand.retry_commandも同じ--commands=<tool>書式で生成される。 失敗ツールだけを再実行したい場合は、該当commandレコードのretry_commandをそのまま貼り付けて実行できる。

UI

ターミナル上で実行すると、TextualベースのTUIが自動的に有効になる。

  • Summaryタブ: 各コマンドのステータス・エラー数・経過時間をリアルタイム表示
  • Errorsタブ: エラー発生時のみ出現し、全コマンドのエラー箇所をファイル:行番号形式で一覧表示
  • 各コマンドタブ: コマンドの出力をリアルタイム表示

Errorsタブのエラー一覧はファイル:行番号: [コマンド名] メッセージ形式で、 VSCodeのターミナルからクリックして該当箇所にジャンプできる。

  • --ui: UIを強制的に有効化する（非対話端末など自動的にUIが無効になる環境でも起動する）
  • --no-ui: UIを無効化し、出力を直接ターミナルに表示（エラー一覧の後にサマリーを表示）
  • --stream: 非TUIモード時に各コマンドの完了時点で即時出力する（既定は全コマンド完了後にまとめて出力）
  • --no-exclude: exclude/extend-excludeパターンによるファイル除外を無効化する
  • --no-gitignore: .gitignoreによるファイル除外を無効化する
  • --allow-external-paths: 起点ディレクトリ外の絶対パスをチェック対象へ含める。 既定の設定ではmarkdownlint・textlint・prek・pre-commit・pytest・vitest・cargo-test・ dotnet-test・gitleaks・semgrep・各種*-auditが起点外パスを除外して警告を発行するが、 本オプション指定時は分類にかかわらず対象へ含める。 markdownlint・textlintの設定ファイル（.markdownlint-cli2.yaml・.textlintrc.yaml等）は 起点ディレクトリ直下から解決して--configで明示的に渡すため、起点外ファイルでも プロジェクトの設定が適用される。 起点外パスを扱えないツールへ渡した場合の結果は利用者の責任とする
  • --no-archive: 実行アーカイブ（ユーザーキャッシュ配下への全実行の保存）を無効化する
  • --no-cache: ファイルhashキャッシュを無効化する
  • --fail-fast: 1ツールでもエラーが発生した時点で残りのジョブを打ち切る （起動済みサブプロセスにはterminate()を送り、未開始ジョブはskippedとして扱われる）
  • --changed-since <REF>: gitの任意のref（ブランチ・タグ・コミットハッシュ・HEADなど）からの変更ファイルのみを対象とする。 git diff --name-only <REF>で取得したコミット差分・trackedファイルの作業ツリー差分・staged差分の和集合と 展開済みファイル一覧の交差が対象となり、untrackedの新規ファイルは対象外。 gitが不在またはrefが存在しない場合は警告を出力して全体実行へフォールバックする。 --only-failedと併用した場合は--changed-sinceフィルタを先に適用してから--only-failedフィルタを適用する
  • --only-failed: 直前runの実行アーカイブから失敗ツール・失敗ファイルを抽出し、 ツール別にその組み合わせだけを再実行する。直前runが無い・失敗ツールが無い・指定targetsとの交差が空の場合は メッセージを出力してrc=0で成功終了する。診断ファイルが取得できないツール（pytest等のpass-filenames=False系）は 既定ファイル展開にフォールバックして全体再実行する。--no-archiveとは独立に働く（参照するのは過去runのアーカイブ）
  • --from-run <RUN_ID>: --only-failedの参照対象runを明示指定する（前方一致・latest対応）。 未指定時は直前runを自動選択。--only-failedとの併用が前提で、単独指定はargparseエラーで拒否する。 指定した<RUN_ID>が存在しない場合は警告を出力してrc=0で早期終了する
  • --shuffle: チェック対象ファイルの並び順をシャッフルする（既定は自然順ソート）。 ファイル順に依存して結果が変わるチェックを洗い出す用途で使う。 乱数シードを指定する手段は無く、シャッフル後の順序を再現する手段も無い。 fixステージでは再現性を優先して指定時も自然順ソートとなる。 --ciと併用した場合は--ci側の設定が優先され、シャッフルは行われない
  • --exit-zero-even-if-formatted: formatterが対象ファイルを書き換えただけでは終了コードを1にせず、0を返す。 ツールがエラーで終了した場合と、ツールの解決に失敗した場合は、コマンドの種別を問わず1となる。 run / fastはサブコマンドの既定値として常に有効なため、 明示指定が意味を持つのはciサブコマンドとなる
  • --ci: CI環境向け。ファイル順のシャッフルとUIを無効化する
  • -j N / --jobs N: linters/testersの最大並列数を指定（既定: 8、pyproject.tomlでも設定可能）。モノレポ検出時は同一ツールのサブプロジェクト実行を同時に開始する件数の算出にも使われる
  • --verbose: デバッグレベルのログを出力する
  • --keep-ui: TUI終了後にTextual画面を保持する（ログ確認用）
  • --work-dir DIR: pyfltrの作業ディレクトリを指定する（既定はカレントディレクトリ）。 指定したディレクトリが設定探索・サブプロジェクト検出・起点外判定の基準となる。 相対パスで渡した対象はDIRではなく、コマンドを起動したディレクトリを基準に解決される。 MCPのrunツールのwork_dirはこの点が異なり、相対パスをwork_dir基準で解決する

TUI実行中にCtrl+Cを1秒以内に2回続けて押すと協調中断モードへ移行する。 実行中のサブプロセスを終了させ、完了済みツールの結果と中断された残りツール一覧をsummaryへ反映したうえで 終了コード130（128 + SIGINT）を返す。 中断時はwarnings欄に次の形式の1行が追加される。

[pyfltr] Ctrl+C により中断しました。中断されたツール: <ツール名の一覧>

協調中断モードでさらにCtrl+Cを2回続けて押すと、後始末を待たず強制終了（終了コード130）となる。

その他のオプションは pyfltr --help を参照。

出力形式

--output-formatで出力形式を切り替えられる。

値 用途 動作
text 既定。人間向け・従来互換 stdoutに進捗・詳細・summaryをまとめて表示
jsonl LLMエージェント向け stdoutにJSON Lines形式で診断・ツール結果・全体集計を出力。text整形はstderrのWARN以上に抑止
sarif CIツール連携向け stdoutにSARIF 2.1.0形式のJSONを1件出力。text整形はstderrのINFO
github-annotations GitHub Actions向け textと同じレイアウトをstdoutに出力し、エラー箇所のみGAワークフローコマンド記法で補強
code-quality GitLab CI向け stdoutにCode Climate JSON issue形式の配列を1件出力。text整形はstderrのINFO

jsonlはツール完了順にストリーミング出力し、最後にwarning/summary行を追加する。 sarifとcode-qualityは全結果集約後に1回だけ出力する。 いずれも--output-file未指定時はstdoutを占有し、text整形出力はstderrへ振り分けられる （jsonlのみWARN以上に抑止）。 github-annotationsはstdoutをtext整形が占有するため、stdout占有は起きない。

--output-fileを指定した場合は、構造化データはファイルへ、stdoutには常にtext整形出力が並行して出る。 jsonlはファイル出力時もストリーミング（ツール完了順）で出力する。

text出力サマリー行でstatus=formattedのコマンドは末尾に; no rerun neededを付与する。 formatterによる書き換えはそれ自体が成功扱いで、再実行を要しないことを示す。

jsonl形式の使い方

pyfltr run --output-format=jsonl
# エージェント検出用の環境変数があり PYFLTR_OUTPUT_FORMAT が未指定の環境では --output-format の指定なしで jsonl になる
pyfltr run

--output-format=jsonlかつ--output-file未指定時、stdoutにはJSONLのみを書き、 text整形出力（進捗・詳細・summary）はstderrのWARN以上に抑止される。 TUIや--stream、--uiも暗黙に無効化される。 JSONLのwarningレコードとして配送された実行時警告はstderrへ重複出力されない。

--output-file=pathを指定するとJSONLはファイルへ出力され、stdoutには従来どおりのtext出力が並行して出力される （ローカル実行時も開発者が進捗を把握できる）。

環境変数PYFLTR_OUTPUT_FORMATでも出力形式の既定値を指定できる （値はサブコマンドが受理する出力形式のいずれか）。 CLIオプション--output-formatが指定されている場合は環境変数より優先される。 エージェント起動スクリプトなどにPYFLTR_OUTPUT_FORMAT=jsonlを設定しておけば、 毎回オプションを明示しなくてもciなど任意のサブコマンドでJSONL出力に切り替えられる。

環境変数AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定されていれば、 --output-format未指定時の既定値がjsonlになる。 コーディングエージェント環境下での自動切り替え用とする。 JSONLヘッダーのformat_sourceには検出した変数名（例: env.CODEX_CI）が記録される。

PYFLTR_OUTPUT_FORMATを明示すれば、エージェント検出環境下でもtext等へ変更できる （例: PYFLTR_OUTPUT_FORMAT=text pyfltr run）。

静音モード（--quiet・--no-quiet）

--quiet指定時は次を抑止し、エージェントの繰り返し実行時のノイズ削減を目的とする。

  • 成功時commandレコード
    • statusがsucceeded・formatted・skippedのいずれか
    • 診断が0件・切り詰め無し・runner_fallback未発火・遅いテスト一覧が空
    • 上記全条件を満たす場合、そのcommandレコードを出力しない
  • headerレコードをrun_id・commands・filesの3つのフィールドのみへ縮約する
  • pre-commit・prek経由でformatter修正が発生したときのstderrガイダンスも抑止する

AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定された環境では run・ci・fastで既定値として有効になり、--no-quietで無効化できる。 これらの環境変数が無い環境での既定値は無効。 summaryレコード・warningレコード・diagnosticレコード・status:"running"のheartbeatイベントは --quietの影響を受けず常に出力する。

heartbeat出力

JSONL出力中に実行中のコマンドが存在し、一定時間レコードが出力されない場合、 pyfltrはkind:"command"かつstatus:"running"のheartbeatレコードを出力する。 commandは実行中のツール名、elapsedはそのツールの経過秒数を示す。 複数のツールが実行中の場合は各ツールのレコードを出力する。 ツールが完了すると、同じcommandを持つ最終レコードが後続し、確定したstatusと結果を示す。 text・sarif・code-quality出力およびTUI使用時はheartbeatレコードを出力しない。

コーディングエージェント連携

コーディングエージェントからpyfltrを呼び出す方法は2種類ある。 MCPを利用できる環境ではMCP経由で呼び出し、シェルコマンドしか使えない環境では直接呼び出しを使う。 どちらの方法でも、指定したチェックが対象へ到達して完了したかを同じ判定で返す。 MCPの提供ツールとパラメーターはサブコマンド: mcpを参照。

直接呼び出し

MCPを利用できず、エージェントがシェルコマンドを実行できる環境では、pyfltr runを直接呼ぶ。 エージェント検出用の環境変数が設定されPYFLTR_OUTPUT_FORMATが未指定であれば、出力形式は自動的にJSON Linesとなる。 以下の手順は環境によらずJSON Linesを得るため--output-format=jsonlを明示する。 直接呼び出しでは、呼び出し元がシェル実行のタイムアウトとstdout・stderrからの出力取得を扱う必要がある。

コーディングエージェントがpyfltr runを直接呼び出す基本的な流れ:

  1. 全体実行でsummaryを確認する

    pyfltr run --output-format=jsonl

    末尾のsummary行（"kind":"summary"）のcompletionを最初に読む。 値の意味はMCPのrunの応答と同じで、静音モードで成功したcommand行が省略されてもsummary行だけで判定できる。 completionがcompleted以外の場合は、summary行のincomplete_commands・missing_targets・ fully_excluded_filesと"kind":"warning"行から未完了の理由を確認する。 commands_summary.needs_action配下のfailed / resolution_failedがいずれも0であれば対応を要する指摘は無く、 commands_summary.no_issues配下の内訳は確認不要。 applied_fixesが非空でもsummary.guidanceに注記が出るが、formatter/fix-stageによる書き換えのみで 再実行は不要なため、そのまま完了してよい。

  2. 失敗したツール/ファイルだけ再実行する

    # 失敗ツールを --commands で限定する
pyfltr run --output-format=jsonl --commands=mypy path/to/file.py

# または直前runの失敗ツール・失敗ファイルをまとめて再実行
pyfltr run --output-format=jsonl --only-failed

    --commandsで特定ツールに限定することで出力量を抑えつつ、 diagnostic行から修正対象のファイル・行番号・メッセージを取得する。 command.retry_commandフィールドには、そのツールだけを失敗ファイルに限定した再実行コマンドが既に生成されているため、 そのまま貼り付けて実行できる。 --only-failedは直前runのアーカイブから失敗ツール・失敗ファイルを自動抽出して再実行する。 直前runが無い・失敗ツールが無い・対象との交差が空の場合は終了コード0で成功終了する。

pre-commit・prekとの統合

pyfltrはpre-commit・prekのうち有効な方を内部で呼び出し、pre-commit・prekはpyfltrをフックとして呼び出す。 git commit経由でpre-commit・prekのいずれかが起動した場合、pyfltrはPRE_COMMIT=1を検出する。 pyfltrは内部の統合を自動スキップし、二重実行を防ぐ。

sequenceDiagram
    participant U as git commit
    participant PC as pre-commit / prek
    participant PH as pre-commit-hooks
    participant PF as pyfltr fast

    U->>PC: フック起動
    PC->>PH: check-yaml, trailing-whitespace等
    PC->>PF: pyfltr fast（local hook）
    Note over PF: PRE_COMMIT=1 検出で<br/>統合をスキップ
    PF->>PF: ruff-format, ruff-check等

逆にmake test等からpyfltr runを呼び出した場合、pyfltr側がSKIP=pyfltr付きで有効なpre-commitまたはprekを起動する。 pre-commitとprekは、いずれも変更ファイル指定（--files <対象>）で起動する。 各hook内部のtypes・types_or・files・excludeフィルタはファイル指定起動でも適用されるため、関係するhookのみ動作する。 これによりpre-commit-hooks（check-yaml等）を統合実行できる。

pass_filenames: false属性のhook（gitleaks等）はリポジトリ全体を走査する。 pyfltr関連hookは.pre-commit-config.yamlから自動検出し、既存のSKIPと pre-commit-skip / prek-skipの手動指定と合わせて子プロセスへ渡す。 自動検出を止めるにはpre-commit-auto-skip = false / prek-auto-skip = falseを設定する。

fastが{command}-fast = trueのツールに限定する条件は、統合の再帰抑制とは別である。 既定の--files起動は未ステージ変更を退避・復元せず、対象が0件なら実行系を起動しない。 実行されないツールの確認方法はトラブルシューティングを参照。

pyfltrは.pre-commit-hooks.yamlを同梱していない。 pre-commit・prekいずれから呼び出す場合も、.pre-commit-config.yamlのrepo: localでlocal hookとして登録する。 prekは同じ設定ファイルをそのまま読む。 entryにはuvx pyfltrを指定する（uvxでキャッシュされるため2回目以降は実用速度）。

repos:
  - repo: local
    hooks:
      - id: pyfltr-fast
        name: pyfltr fast
        language: system
        entry: uvx pyfltr fast
        require_serial: true
        types: [file]

dev依存にpyfltrを固定する運用ではentry: uv run --frozen pyfltr fastに置き換えることもできる。

pyfltrからprekのhookを呼び出す統合はprek = trueで有効化する。 詳細は設定項目（ツール別）のprekに関する説明を参照。

共通の注意点

  • pyfltr fast はfixステージを内蔵する。pre-commit hookから{command}-fix-args定義済みlinter （cargo-clippy / ruff-check / textlint等）の自動修正が実行されるため、別hookを並べる必要は無い
  • formatter（ruff-format / prettier / cargo-fmt / dotnet-format等）は通常実行で常時書き込みモードで動作するため、 fixステージでは扱わない
  • pass-filenames = Falseのツール（cargo-* / dotnet-* / tsc等）はcrate / solution全体を対象とするため、 コミット時に未変更ファイルまで書き換わる可能性がある。 cargo系・dotnet系はserial_groupで自動直列化されるので、利用者が--jobs=1などを指定する必要は無い

ファイルhashキャッシュ

同じ入力に対するツール再実行をスキップし、待ち時間と再計算を削減する。 対象はファイル間依存を持たず、設定ファイルを起点cwdのみで解決するキャッシュ対応ツールに限る。 現時点の対象はtextlintのみである。 対象ファイル群・ツール固有設定ファイル群のハッシュとツール固有情報からキャッシュキーを構築する。 ヒット時はツール実行をスキップして前回結果を復元する。 既定は有効であり、--no-cacheまたはcache = false設定で実行単位に無効化できる。 保存期間はcache-max-age-hours（既定12時間）で制御する。 設計判断の詳細はアーキテクチャ概要を参照。

モノレポでの動作

起点cwd配下に複数のマーカー（pyproject.toml・Cargo.toml・*.csproj・*.sln）を検出した場合、 サブプロジェクト単位でツールを分割実行する（モノレポモード）。

  • 検出: 起点cwd配下を再帰探索する。 マーカーを持つディレクトリをサブプロジェクトとして扱う。 マーカーは固定ファイル名pyproject.toml・Cargo.tomlと、globパターン*.csproj・*.slnとする。 [tool.pyfltr]の有無は問わない。 [tool.uv.workspace] members glob展開はpyproject.toml側のみに適用する。 .gitignoreを尊重する。 .venv・node_modules・target・build・dist・.git配下は走査しない
  • pyproject.tomlを持たないサブプロジェクト（Cargo.toml単独・*.csproj単独等）は [tool.pyfltr]の記述先が無いため、最近接祖先のpyproject.toml（無ければ起点で解決した設定）を継承する
  • Cargo workspace root配下の登録member crateは重複実行防止のため独立サブプロジェクトとして検出しない。 workspace rootは[workspace]テーブルを持つCargo.tomlで判定する。 .sln所在ディレクトリ配下の登録csprojも同様に検出しない。 workspace root・solution所在ディレクトリで一括実行する。 ただし登録member・登録projectであっても、他のマーカー（pyproject.toml・ 登録csproj所在ディレクトリのCargo.toml）を併有するディレクトリは、 そのディレクトリ固有の設定を尊重するため独立サブプロジェクトとして検出する （この場合はworkspace・solution側の一括実行と重複し得る）
  • package.jsonは汎用ファイルのため単独ではサブプロジェクトとして検出しない
  • 適用範囲: プロジェクトローカル設定・モジュール解決・lockfileをcwd起点で読むツール （mypy・pylint・pyright・pytest・textlint・eslintなど）はサブプロジェクト別に起動する。 cargo-*・dotnet-*・ruff-*も同様に扱う。 リポジトリ単位のツール（typos・shellcheck・shfmt・pre-commit・prek）は1回だけ起動する
  • フォールバック: 検出結果が0件または1件の場合は単一プロジェクトとして従来通り動作する
  • 出力スキーマ: モノレポ実行でもJSONL・SARIF・show-run・MCP読み取り系APIの 公開スキーマは変更しない。サブプロジェクト境界をまたぐ実行結果は1件にマージし、人間向けoutputには # subproject: <相対パス> の区切り行を挿入する
  • 個別設定: 各サブプロジェクトの [tool.pyfltr] 設定（ツールのON/OFF・除外・targets等）を そのディレクトリで個別に解決して尊重する。 CLIオプション（--jobs・--no-exclude・--no-gitignore・--human-readable）は起点と同一に再適用する
  • サブプロジェクトの並列実行: 同一ツールのサブプロジェクト実行は、jobsをそのツール自身のワーカー数の推定値で割った件数まで同時に開始する。 報告順はサブプロジェクトの相対パスの昇順で安定し、実行順に依存しない
  • 設定ファイルの探索起点: config-files（設定ファイル不在の警告）と--config系の自動注入は 常に起点cwd直下を基準に判定する。.pre-commit-config.yaml等をリポジトリルートに置く構成で、 サブプロジェクト側に同名ファイルが無いことを理由に警告することはない
  • ツールON/OFFの両方向: 親（起点）で無効・子で有効なら子でのみ実行し、親で有効・子で無効なら子サブプロジェクトはスキップする。 起点ディレクトリ自体は1つのサブプロジェクトとして扱い、その設定が有効なら起点自身のファイルは実行する
  • 起点cwdでの一括実行はしない: あるツールが起点で有効でも、対象ファイルを持つサブプロジェクトが全て無効化している場合、 起点cwdで全ファイルをまとめて実行することはない（サブプロジェクト境界をまたいだ誤実行を避ける）
  • リポジトリ単位のツール（typos・shellcheck・shfmt・pre-commit・prek）のON/OFFは、 起点 pyproject.toml の設定で固定し、子の設定では切り替えない