n8n-cli

n8n CLI

n8n-cli コマンドラインツールは、REST API を通じて n8n インスタンスを管理します。 パイプされた出力を自動検出して JSON に切り替えるため、スクリプトや LLM ツールで組み合わせて使用できます。

セットアップ

# Interactive login (saves to ~/.n8n-cli/config.json)
n8n-cli login

# Or configure directly
n8n-cli config set-url https://my-instance.n8n.cloud
n8n-cli config set-api-key n8n_api_...

# Or use environment variables (no config file needed)
export N8N_URL=https://my-instance.n8n.cloud
export N8N_API_KEY=n8n_api_...

グローバルフラグ

すべてのコマンドで次のフラグを使用できます。

フラグ	短縮形	説明
--url	-u	インスタンスの URL（設定／環境変数を上書きします）
--apiKey	-k	API キー（設定／環境変数を上書きします）
--format	-f	出力形式：table、json、id-only
--json		--format=json の短縮形
--jq		jq 形式のフィルター（--json を暗黙的に指定）、例：'.[0].id'、'.[].name'
--quiet	-q	出力を抑制します
--no-header		テーブルのヘッダーを非表示にします（awk／cut で解析する場合）
--debug		HTTP の詳細を stderr に出力します

JSON の自動切り替え： stdout がパイプされている場合（TTY ではない場合）、出力形式は自動的に JSON になります。

ワークフロー

# List all workflows
n8n-cli workflow list

# Filter workflows
n8n-cli workflow list --active
n8n-cli workflow list --tag=production
n8n-cli workflow list --name="My Workflow"
n8n-cli workflow list --limit=5

# Get a single workflow (full JSON with nodes and connections)
n8n-cli workflow get <id>

# Extract just node names from a workflow
n8n-cli workflow get <id> --jq '.nodes[].name'

# Create a workflow from JSON
n8n-cli workflow create --file=workflow.json
cat workflow.json | n8n-cli workflow create --stdin

# Update a workflow
n8n-cli workflow update <id> --file=updated.json
cat updated.json | n8n-cli workflow update <id> --stdin

# Activate / deactivate
n8n-cli workflow activate <id>
n8n-cli workflow deactivate <id>

# Delete a workflow
n8n-cli workflow delete <id>

# Transfer to another project
n8n-cli workflow transfer <id> --project=<projectId>

# List tags on a workflow
n8n-cli workflow tags <id>

実行

# List recent executions
n8n-cli execution list
n8n-cli execution list --workflow=<id> --status=error --limit=10
# status options: canceled, error, running, success, waiting

# Get execution details
n8n-cli execution get <id>
n8n-cli execution get <id> --include-data   # includes full node I/O

# Retry a failed execution
n8n-cli execution retry <id>

# Stop a running execution
n8n-cli execution stop <id>

# Delete an execution
n8n-cli execution delete <id>

認証情報

# List credentials
n8n-cli credential list

# Get credential metadata (not secrets)
n8n-cli credential get <id>

# Get the schema for a credential type (shows required fields)
n8n-cli credential schema notionApi
n8n-cli credential schema slackOAuth2Api

# Create a credential
n8n-cli credential create --type=notionApi --name='My Notion' --data='{"apiKey":"..."}'
n8n-cli credential create --type=notionApi --name='My Notion' --file=cred.json
cat cred.json | n8n-cli credential create --type=notionApi --name='My Notion' --stdin

# Delete / transfer
n8n-cli credential delete <id>
n8n-cli credential transfer <id> --project=<projectId>

ヒント： 作成前に必要なフィールドを確認するには、credential schema <type> を使用してください。

プロジェクト

n8n-cli project list
n8n-cli project get <id>
n8n-cli project create --name="My Project"
n8n-cli project update <id> --name="New Name"
n8n-cli project delete <id>

# Team management
n8n-cli project members <id>
n8n-cli project add-member <id> --user=<userId> --role=<role>
n8n-cli project remove-member <id> --user=<userId>

タグ

n8n-cli tag list
n8n-cli tag create --name=production
n8n-cli tag update <id> --name=staging
n8n-cli tag delete <id>

変数

n8n-cli variable list
n8n-cli variable create --key=API_ENDPOINT --value=https://api.example.com
n8n-cli variable update <id> --key=API_ENDPOINT --value=https://new-api.example.com
n8n-cli variable delete <id>

データテーブル

# CRUD
n8n-cli data-table list
n8n-cli data-table get <id>
n8n-cli data-table create --name=Inventory --columns='[{"name":"item","type":"string"},{"name":"qty","type":"number"}]'
n8n-cli data-table delete <id>

# Row operations
n8n-cli data-table rows <id>
n8n-cli data-table add-rows <id> --file=rows.json
n8n-cli data-table update-rows <id> --file=rows.json
n8n-cli data-table upsert-rows <id> --file=rows.json
n8n-cli data-table delete-rows <id> --ids=row1,row2,row3

# All row commands support --stdin
cat rows.json | n8n-cli data-table add-rows <id> --stdin

ユーザー

n8n-cli user list
n8n-cli user get <id>

プロモーション

Git リポジトリを通じて、インスタンス間でプロジェクトを移動します。プロバイダーには認証情報を保持し、接続でリポジトリを指定します。設定では、リポジトリに対する一方向の処理をセットアップします。promote は Git にプッシュし、apply は Git からインポートします。

# 1. Create a provider. An SSH provider returns a public key to add as a deploy key.
#    The response carries the provider fields at the top level, so `.id` and
#    `.publicKey` both work with --jq and --format=id-only.
echo '{"name":"GitHub","type":"git","auth":{"authType":"ssh-key","keyType":"ed25519"}}' \
  | n8n-cli promotion-provider create --stdin --json > provider.json
jq -r '.id' provider.json          # use as providerId in step 2
jq -r '.publicKey' provider.json   # add to the repository as a deploy key

# 2. Create a connection on that provider, with the directions you need.
#    Leave out "configs" to configure no direction yet.
n8n-cli promotion-connection create --file=connection.json

# 3. Clone each direction before you use it.
n8n-cli promotion-connection clone <id> promote
n8n-cli promotion-connection clone <id> apply

# 4. Promote from this instance, or apply to it.
n8n-cli promotion-connection promote <id> -m "Promote team projects"
n8n-cli promotion-connection apply <id>

レビュー済みのコミットのみを適用します。

# Review the changes. Take the commit SHA from the same response as the rows:
# a second request can read a newer commit.
n8n-cli promotion-connection list-changes <projectId> apply --sort=updatedAt --order=desc --json > reviewed-changes.json
jq '{commitSha, changes}' reviewed-changes.json
# The config ID and branch come from the connection.
n8n-cli promotion-connection get <id> --jq '.configs.apply.id'
n8n-cli promotion-connection get <id> --jq '.configs.apply.settings.branchName'

n8n-cli promotion-connection apply <id> \
  --expected-config-id=<configId> --expected-branch=<branch> --expected-commit-sha=<full sha>
# Exit 3: the source changed since the review. Review again.
# Exit 4: preflight found missing bindings, access requirements, or conflicts. Resolve them,
# then run the apply-continue command that apply printed:
n8n-cli promotion-connection apply-continue <id> \
  --expected-config-id=<configId> --expected-branch=<branch> --expected-commit-sha=<full sha>
# To also apply destructive data table changes and delete the team projects that the
# package does not hold, add --confirm-destructive-changes.

ステップ 2 の接続 JSON：

{
  "name": "Production",
  "scope": "instance",
  "providerId": "prov-1",
  "target": { "schemaVersion": 1, "remoteUrl": "[email protected]:acme/flows.git" },
  "configs": {
    "promote": {
      "settings": {
        "schemaVersion": 1,
        "baseBranchName": "main",
        "createBranchOnPromotion": false
      }
    },
    "apply": { "settings": { "schemaVersion": 1, "branchName": "main" } }
  }
}

# Providers
n8n-cli promotion-provider list
n8n-cli promotion-provider get <id>          # re-read the public key; the list omits it
echo '{"name":"New name"}' | n8n-cli promotion-provider update <id> --stdin
n8n-cli promotion-provider delete <id>       # fails while a connection uses it

# Connections
n8n-cli promotion-connection list --scope=instance
n8n-cli promotion-connection list --provider=<providerId>
n8n-cli promotion-connection get <id>
echo '{"name":"New name"}' | n8n-cli promotion-connection update <id> --stdin
n8n-cli promotion-connection delete <id>

# Change one direction. The write replaces the whole configuration,
# so send every setting you want to keep.
echo '{"settings":{"schemaVersion":1,"branchName":"main"}}' \
  | n8n-cli promotion-connection set-config <id> apply --stdin
echo '{"settings":{"schemaVersion":1,"baseBranchName":"main","createBranchOnPromotion":false}}' \
  | n8n-cli promotion-connection set-config <id> promote --stdin
n8n-cli promotion-connection delete-config <id> apply
n8n-cli promotion-connection disconnect <id> promote

# Link projects to a "projects"-scoped connection
n8n-cli promotion-connection list-projects <id>
n8n-cli promotion-connection add-project <id> <projectId>
n8n-cli promotion-connection remove-project <id> <projectId>

重要なポイント：

• すべての JSON 本文は --stdin または --file を通じて渡し、フラグでは渡さないでください。これにより、認証情報がコマンドラインに表示されるのを防げます。
• authType は ssh-key または token です。token は HTTP(S) のユーザー名とパスワードを意味し、Git ホストの API トークンではありません。token プロバイダーの場合、publicKey は null です。
• promote 設定では、常に createBranchOnPromotion が必要です。
• promote と apply は instance 接続でのみ動作し、使用する方向を事前にクローンする必要があります。一方の方向をクローンしても、もう一方の準備は整いません。
• 終了コードが 3（source-changed）または 4（blocked）の場合、apply と apply-continue は何もインポートしません。counts を確認する前に、$? または JSON 出力の status フィールドを確認してください。--json を指定した場合、blocked の結果では不足している項目が preflight に表示されます。
• --expected-* フラグはすべて一緒に使用する必要があります。3 つすべてを渡すか、どれも渡さないでください。コミット SHA には完全な SHA を指定してください。
• このグループの API キーのスコープ名は gitConnection:* です。ワークフローが変数を参照している場合、promote には variable:list も必要です。

その他

# Security audit
n8n-cli audit
n8n-cli audit --categories=credentials,nodes

# Source control
n8n-cli source-control pull

# View config
n8n-cli config show

組み合わせて使用するパターン

この CLI は、パイプや組み合わせての使用を想定して設計されています。

# Get all workflow IDs
n8n-cli workflow list --jq '.[].id'

# Get the name of the first workflow
n8n-cli workflow list --jq '.[0].name'

# Export a workflow to a file
n8n-cli workflow get 1234 --json > workflow-backup.json

# Find failing executions for a workflow
n8n-cli execution list --workflow=1234 --status=error --json

# Pipe workflow JSON for modification
n8n-cli workflow get 1234 --json | jq '.name = "Updated Name"' | n8n-cli workflow update 1234 --stdin

# Table output without headers for shell parsing
n8n-cli workflow list --no-header | awk '{print $1}'

# Debug API calls
n8n-cli workflow list --debug 2>debug.log

ワークフロー JSON 構造

ワークフローを作成または更新する場合、JSON は次の構造に従います。

{
  "name": "My Workflow",
  "nodes": [
    {
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300],
      "parameters": {}
    },
    {
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300],
      "parameters": {
        "url": "https://api.example.com/data",
        "method": "GET"
      }
    }
  ],
  "connections": {
    "Start": {
      "main": [[{ "node": "HTTP Request", "type": "main", "index": 0 }]]
    }
  }
}

重要なポイント：

• 組み込みノードの場合、nodes[].type は n8n-nodes-base.<nodeName> のパターンに従います。
• connections はソースノード名をキーとし、main の出力配列を含みます。
• 各接続では、対象の node、type（通常は main）、出力の index を指定します。
• インスタンスの実例を確認するには、workflow get <id> --json を使用してください。