n8n-cli 操作スキル

n8n-cli（TypeScript/Bun）を使用したワークフロー管理を支援するスキルです。

セッション初期化（重要）

新しいセッションでは、n8n-cli が最新であることを確認するために、必ず以下を実行してください。

優先順位 1：ローカルソースからビルド（開発用）

n8n-cli のソースリポジトリが add-dir 経由で利用可能な場合（例：/path/to/n8n-cli/Makefile が存在する場合）、リリース版ではなくローカルソースからビルドします。これにより、最新の開発中の変更が即座に反映されます。

# n8n-cli リポジトリが add-dir 経由で参照可能な場合
N8N_CLI_REPO="/path/to/n8n-cli"  # add-dir のパスに置き換えてください
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "ローカルソースから n8n-cli をビルド中：$N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /path/to/target/n8n-cli
  cd /path/to/target
  echo "ローカルソースからビルド完了：$(./n8n-cli version 2>/dev/null | head -1)"
fi

優先順位 2：GitHub Releases からの自動更新（推奨）

プリビルド済みバイナリが GitHub Releases で入手可能です。ソースからビルドするよりも高速で、公式リリースを実行していることが保証されます。

# 1. 最新リリースバージョンを確認
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. 現在のローカルバージョンを確認（バイナリが存在する場合）
CURRENT_VERSION=""
if [ -x ./n8n-cli ]; then
  CURRENT_VERSION=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. 比較して、必要に応じてダウンロード
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "n8n-cli を更新中：${CURRENT_VERSION:-なし} -> ${LATEST_TAG}"

  # プラットフォームを検出
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) ASSET_NAME="n8n-cli-${OS}-arm64" ;;
    x86_64)        ASSET_NAME="n8n-cli-${OS}-x64" ;;
    *)             echo "サポートされていないアーキテクチャ：$ARCH"; exit 1 ;;
  esac

  # バイナリをダウンロード
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "更新完了：$(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli は最新です：$CURRENT_VERSION"
fi

フォールバック：ソースからビルド

gh CLI が利用できない場合や開発ビルドが必要な場合：

# 依存関係のインストール + CLI のビルド
bun install && make build

ビルド確認：

./n8n-cli version

環境設定

.env ファイルの確認

プロジェクトルートに .env が存在する場合、n8n-cli はパラメータを指定せずに使用できます。内容は読み取らないでください。

# .env の存在のみ確認（内容は読み取らない）
test -f .env && echo ".env が存在します - n8n-cli はパラメータなしで使用できます"

.env が存在する場合：

N8N_API_URL と N8N_API_KEY がすでに設定されています
./n8n-cli はパラメータなしで実行できます

.env が存在しない場合：

ユーザーに .env ファイルの作成を促してください
または --api-url と --api-key フラグを使用します

.env の作成（必要な場合のみ）

cp .env.example .env
# ユーザーに編集を依頼

共通コマンド

1. リモートワークフローの状態確認

特定のワークフローを確認：

# ID でワークフロー情報を取得
./n8n-cli workflow get <workflow-id>

# 読みやすいテーブル形式で表示
./n8n-cli -o table workflow get <workflow-id>

# ファイルに保存（差分比較に便利）
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

ワークフロー一覧：

# すべてのワークフロー
./n8n-cli workflow list

# テーブル形式
./n8n-cli -o table workflow list

# アクティブなワークフローのみ
./n8n-cli workflow list --active

2. インポート（リモート -> ローカル）

インポート前にローカル形式を確認

リモートコンテンツをローカルに取得する場合、常に以下の手順に従ってください：

ローカルファイルの形式を確認

# ファイルが存在するか、その形式を確認
ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*

形式に応じて適切なインポートオプションを使用
- .json ファイル：--ids のみ使用
- .yaml/.yml ファイル：--ids と --yaml の両方を使用

特定のワークフローをインポート：

# JSON 形式のワークフロー
./n8n-cli import --ids=<workflow-id>

# YAML 形式のワークフロー
./n8n-cli import --ids=<workflow-id> --yaml

# カスタムディレクトリへ
./n8n-cli import --ids=<workflow-id> -d ./my-dir

複数のワークフローをインポート：

# カンマ区切りリスト
./n8n-cli import --ids=abc123,def456,ghi789

すべてのワークフローをインポート：

./n8n-cli import

追加オプション：

オプション	説明
`--include-archived`	アーカイブ済みワークフローを含める
`--cleanup-orphans`	一致する ID のない孤立ファイルを削除
`-t, --threshold <int>`	外部ファイル抽出の最小行数（デフォルト：0、CLAUDE.md で設定可能）
`--dry-run`	プレビューのみ（ファイル変更なし）
`--tags <tags>`	カンマ区切りのタグ名でフィルタリング（AND条件）

3. ドライラン（変更のプレビュー）

適用前に必ずドライランで確認：

# すべてのワークフローの変更をプレビュー
./n8n-cli apply --dry-run

# ID 指定で特定のワークフローのみ
./n8n-cli apply --dry-run --ids=<workflow-id>

# 特定のファイルのみ
./n8n-cli apply --dry-run -d definitions/path/to/workflow.json

出力例：

=== 作成（1ワークフロー） ===
  + new-workflow.json（名前："新規自動化"）

=== 更新（2ワークフロー） ===
  ~ existing.json（id：R2cTI0LDzCJSnvNG）
    - name: "旧名" -> "新名"
    - nodes: 3 -> 5 ノード

=== スキップ（1ワークフロー） ===
  = unchanged.json（変更なし）

サマリー（ドライラン）：1作成、2更新、1変更なし

4. 適用（デプロイ）

AI アシスタントは常に --ids を使用してください

# 特定のワークフローのみ適用（推奨）
./n8n-cli apply --ids=<workflow-id>

# 特定のファイルのみ適用
./n8n-cli apply -d definitions/path/to/workflow.json

# 強制適用（リモートの変更を上書き）
./n8n-cli apply --ids=<workflow-id> --force

禁止事項：ディレクトリ全体への適用

# AI は以下を実行してはいけません
./n8n-cli apply -d definitions/
./n8n-cli apply

追加オプション：

オプション	説明
`--from-git-changes <spec>`	Git diff で変更されたファイルのみを適用
`--yaml` / `--no-yaml`	YAML 処理の有効/無効
`--allow-duplicates`	上流の重複名チェックをスキップ（デフォルト：オン；チェックを無効にする代わりに `--force` を使用して警告を回避）
`--no-auto-tag`	自動タグ付けを無効にする（managed-as-code）
`-p, --project <id>`	ターゲットプロジェクト ID を指定

環境変数：

APPLY_FILTER_BY_TAGS - カンマ区切りのタグ名でフィルタリング（AND条件）

Git diff モード：

# フィーチャーブランチの変更のみを適用
./n8n-cli apply --from-git-changes origin/main..HEAD

# プレビュー
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# 最後の3コミットの変更
./n8n-cli apply --from-git-changes HEAD~3..HEAD

3-way コンフリクト検出：--from-git-changes が指定された場合、ベース（基準点）、ローカル（現在）、リモート（サーバー）を比較して真のコンフリクトのみを特定します。

5. リンター（品質チェック）

リンターはCLIに統合されています。別途ビルドは必要ありません。

注：位置引数はサポートされていません。ファイル/ディレクトリは常に -f または -d で指定してください。

# 特定のファイルをチェック（-f 必須）
./n8n-cli lint -f definitions/<filename>

# 特定のディレクトリをチェック
./n8n-cli lint -d ./definitions/example-project

# すべてのワークフローをチェック
./n8n-cli lint -d ./definitions

# JSON 出力（CI/CD 用）
./n8n-cli lint -d ./definitions -o json

オプション：

オプション	説明
`-d, --dir <path>`	定義ファイルのディレクトリ
`-f, --file <files...>`	特定のファイル
`-c, --config <path>`	設定ファイルのパス（.n8nlintrc.json）
`--disable-rule <name>`	特定のルールを無効にする
`--list-rules`	すべてのルールを一覧表示
`-o, --output <format>`	出力形式：text, json（デフォルト：text）

ルール（11ルール）：

ルール	重大度	説明
`json-syntax`	error	JSON 構文チェック
`required-fields`	error	必須フィールド（name, nodes, connections）のチェック
`connection-reference`	error	接続先ノードの存在チェック
`webhook-id-required`	error	webhook および formTrigger ノードに webhookId フィールドがあるかチェック
`orphaned-node`	warning	孤立ノードの検出
`implicit-json-ref`	warning	暗黙の `$json` 参照の検出
`expression-mode-prefix`	warning	欠落している `=` プレフィックスの検出
`ai-agent-output-ref`	warning	AI Agent 出力の誤参照の検出
`node-params`	warning	ノードパラメータスキーマの検証
`node-ref-field-check`	warning	参照フィールドの存在検証
`node-ref-cardinality`	warning	`.item`/`.first()` 使用法の検証

設定ファイル（.n8nlintrc.json）：

{
  "rules": {
    "json-syntax": "error",
    "required-fields": "error",
    "orphaned-node": "warning",
    "implicit-json-ref": "off"
  }
}

設定ファイルの検索順序：

--config フラグで指定されたパス
ターゲットディレクトリ内の .n8nlintrc.json / .n8nlintrc
カレントディレクトリ内の .n8nlintrc.json / .n8nlintrc

6. フォーマッター（自動整形）

注：fmt はファイルを位置引数として受け取ります（-f オプションはありません）。

# 特定のファイルをフォーマット（位置引数）
./n8n-cli fmt definitions/<filename>

# 複数ファイル
./n8n-cli fmt definitions/file1.yaml definitions/file2.yaml

# ディレクトリ全体をフォーマット
./n8n-cli fmt -d ./definitions

# プレビューのみ
./n8n-cli fmt -d ./definitions --dry-run

7. テスト（実行）

テスト Webhook を使用したワークフローのテスト：

# 基本テスト
./n8n-cli test <workflow-id>

# テストデータ付き
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# 実行完了を待機（推奨）
./n8n-cli test <workflow-id> --wait-execution

# 非アクティブなワークフローを自動アクティベート
./n8n-cli test <workflow-id> --activate

# Webhook URL のみ確認
./n8n-cli test <workflow-id> --dry-run

# 入力パラメータを確認
./n8n-cli test <workflow-id> --show-inputs

オプション：

オプション	説明
`-d, --data <json>`	テストデータ（JSON 文字列）
`--timeout <duration>`	HTTP タイムアウト（デフォルト：30s）
`--wait-execution`	実行完了を待機して結果を表示
`--activate`	非アクティブなワークフローを自動アクティベート
`--dry-run`	Webhook URL のみ確認
`--show-inputs`	入力パラメータを表示
`-o, --output <fmt>`	出力形式：json, table（デフォルト：json）

ローカルファイルからのテスト：

# ローカルの JSON/YAML ファイルを指定
./n8n-cli test ./definitions/my-workflow.json

8. 実行（ログとエラー）

最近の実行を一覧表示：

# 最近のすべての実行を一覧表示
./n8n-cli execution list

# 読みやすいテーブル形式
./n8n-cli -o table execution list

# ステータスでフィルタリング
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# ワークフローでフィルタリング
./n8n-cli execution list --workflow <workflow-id>

# 結果を制限
./n8n-cli execution list --limit 5

# 複合フィルタ
./n8n-cli execution list --workflow <workflow-id> --status error --limit 10

実行の詳細を取得：

# ID で実行を取得
./n8n-cli execution get <execution-id>

# エラー詳細付きテーブル形式
./n8n-cli -o table execution get <execution-id>

# ノード実行サマリーを含める
./n8n-cli -o table execution get <execution-id> --show-data

execution list のオプション：

オプション	説明
`-w, --workflow <id>`	ワークフロー ID でフィルタリング
`-s, --status <status>`	ステータスでフィルタリング（success, error, running, waiting）
`-l, --limit <n>`	最大実行数（デフォルト：20）

execution get のオプション：

オプション	説明
`--show-data`	出力にノード実行サマリーを含める

表示されるエラー情報：

フィールド	説明
エラーノード	エラーが発生したノード
エラーメッセージ	エラーメッセージ
エラー詳細	追加のエラー説明（利用可能な場合）
最終ノード	最後に実行されたノード

典型的なデバッグワークフロー：

# 1. 最近のエラーを一覧表示
./n8n-cli -o table execution list --status error --limit 5

# 2. 特定の失敗した実行の詳細を取得
./n8n-cli -o table execution get <execution-id> --show-data

# 3. エラー詳細を確認し、ワークフローを修正

9. 変換（形式変換）

ワークフローファイルを JSON と YAML 形式間で変換（ローカルのみ、API 不要）：

# すべての JSON ワークフローを YAML に変換
./n8n-cli convert -d ./definitions --format yaml

# ID で特定のワークフローを変換
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# 書き込みなしでプレビュー
./n8n-cli convert -d ./definitions --format yaml --dry-run

# 元のファイルを保持
./n8n-cli convert -d ./definitions --format yaml --keep

# 単一ファイルを変換
./n8n-cli convert --format yaml definitions/<filename>.json

オプション：

オプション	説明
`--format <format>`	ターゲット形式：`json`、`yaml`（必須）
`-d, --directory <dir>`	ワークフローファイルをスキャンするディレクトリ
`--ids <ids>`	変換するワークフロー ID（カンマ区切り）
`--tags <tags>`	タグでフィルタリング（カンマ区切り、AND条件）
`-t, --threshold <n>`	コード外部化の最小行数（JSON→YAML）
`--dry-run`	プレビューのみ
`--keep`	元のファイルを保持

動作：

JSON→YAML：YAML + _subfiles/ に外部化されたコードを生成
YAML→JSON：!include 参照を解決し、_subfiles/ を削除
すでにターゲット形式のファイルはスキップ
変換後、元のファイルは --keep 以外は削除されます

10. データテーブル

データテーブルと行の管理：

# すべてのデータテーブルを一覧表示
./n8n-

…

[翻訳のため一部省略]

ubie-oss/n8n-cli

n8n-cli とは？

お気に入りのAIに質問する

ドキュメント

n8n-cli 操作スキル

セッション初期化（重要）

優先順位 1：ローカルソースからビルド（開発用）

優先順位 2：GitHub Releases からの自動更新（推奨）

フォールバック：ソースからビルド

環境設定

.env ファイルの確認

.env の作成（必要な場合のみ）

共通コマンド

1. リモートワークフローの状態確認

2. インポート（リモート -> ローカル）

インポート前にローカル形式を確認

3. ドライラン（変更のプレビュー）

4. 適用（デプロイ）

5. リンター（品質チェック）

6. フォーマッター（自動整形）

7. テスト（実行）

8. 実行（ログとエラー）

9. 変換（形式変換）

10. データテーブル

関連スキル

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7