SKILL.md
2,978 tokens · o200k_base · 10,648 bytes
Source excerpt starting at line 1.---name: n8n-clidescription: Use the n8n CLI to manage workflows, credentials, executions, and more on an n8n instance. Use when the user asks to interact with n8n, automate workflows, manage credentials, or operate their instance from the command line.allowed-tools: Bash(n8n-cli:*), Bash(echo:*), Bash(cat:*), Read, Write--- # n8n CLI The `n8n-cli` command-line tool manages an n8n instance via its REST API.It auto-detects piped output and switches to JSON, making it composable for scripts and LLM tool use. ## Setup ```bash# Interactive login (saves to ~/.n8n-cli/config.json)n8n-cli login # Or configure directlyn8n-cli config set-url https://my-instance.n8n.cloudn8n-cli config set-api-key n8n_api_... # Or use environment variables (no config file needed)export N8N_URL=https://my-instance.n8n.cloudexport N8N_API_KEY=n8n_api_...``` ## Global Flags Every command supports these flags: | Flag | Short | Description ||------|-------|-------------|| `--url` | `-u` | Instance URL (overrides config/env) || `--apiKey` | `-k` | API key (overrides config/env) || `--format` | `-f` | Output format: `table`, `json`, `id-only` || `--json` | | Shorthand for `--format=json` || `--jq` | | jq-style filter (implies `--json`), e.g. `'.[0].id'`, `'.[].name'` || `--quiet` | `-q` | Suppress output || `--no-header` | | Hide table headers (for `awk`/`cut` parsing) || `--debug` | | Print HTTP details to stderr | **Auto-JSON:** When stdout is piped (not a TTY), output defaults to JSON automatically. ## Workflows ```bash# List all workflowsn8n-cli workflow list # Filter workflowsn8n-cli workflow list --activen8n-cli workflow list --tag=productionn8n-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 workflown8n-cli workflow get <id> --jq '.nodes[].name' # Create a workflow from JSONn8n-cli workflow create --file=workflow.jsoncat workflow.json | n8n-cli workflow create --stdin # Update a workflown8n-cli workflow update <id> --file=updated.jsoncat updated.json | n8n-cli workflow update <id> --stdin # Activate / deactivaten8n-cli workflow activate <id>n8n-cli workflow deactivate <id> # Delete a workflown8n-cli workflow delete <id> # Transfer to another projectn8n-cli workflow transfer <id> --project=<projectId> # List tags on a workflown8n-cli workflow tags <id>``` ## Executions ```bash# List recent executionsn8n-cli execution listn8n-cli execution list --workflow=<id> --status=error --limit=10# status options: canceled, error, running, success, waiting # Get execution detailsn8n-cli execution get <id>n8n-cli execution get <id> --include-data # includes full node I/O # Retry a failed executionn8n-cli execution retry <id> # Stop a running executionn8n-cli execution stop <id> # Delete an executionn8n-cli execution delete <id>``` ## Credentials ```bash# List credentialsn8n-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 notionApin8n-cli credential schema slackOAuth2Api # Create a credentialn8n-cli credential create --type=notionApi --name='My Notion' --data='{"apiKey":"..."}'n8n-cli credential create --type=notionApi --name='My Notion' --file=cred.jsoncat cred.json | n8n-cli credential create --type=notionApi --name='My Notion' --stdin # Delete / transfern8n-cli credential delete <id>n8n-cli credential transfer <id> --project=<projectId>``` **Tip:** Use `credential schema <type>` to discover required fields before creating. ## Projects ```bashn8n-cli project listn8n-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 managementn8n-cli project members <id>n8n-cli project add-member <id> --user=<userId> --role=<role>n8n-cli project remove-member <id> --user=<userId>``` ## Tags ```bashn8n-cli tag listn8n-cli tag create --name=productionn8n-cli tag update <id> --name=stagingn8n-cli tag delete <id>``` ## Variables ```bashn8n-cli variable listn8n-cli variable create --key=API_ENDPOINT --value=https://api.example.comn8n-cli variable update <id> --key=API_ENDPOINT --value=https://new-api.example.comn8n-cli variable delete <id>``` ## Data Tables ```bash# CRUDn8n-cli data-table listn8n-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 operationsn8n-cli data-table rows <id>n8n-cli data-table add-rows <id> --file=rows.jsonn8n-cli data-table update-rows <id> --file=rows.jsonn8n-cli data-table upsert-rows <id> --file=rows.jsonn8n-cli data-table delete-rows <id> --ids=row1,row2,row3 # All row commands support --stdincat rows.json | n8n-cli data-table add-rows <id> --stdin``` ## Users ```bashn8n-cli user listn8n-cli user get <id>``` ## Promotions Move projects between instances through a Git repository. A **provider** holdsthe credentials, a **connection** names the repository, and a **configuration**sets up one direction on it: `promote` pushes to Git, `apply` imports from Git. ```bash# 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.jsonjq -r '.id' provider.json # use as providerId in step 2jq -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> promoten8n-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>``` Connection JSON for step 2: ```json{ "name": "Production", "scope": "instance", "providerId": "prov-1", "target": { "schemaVersion": 1, "remoteUrl": "git@github.com:acme/flows.git" }, "configs": { "promote": { "settings": { "schemaVersion": 1, "baseBranchName": "main", "createBranchOnPromotion": false } }, "apply": { "settings": { "schemaVersion": 1, "branchName": "main" } } }}``` ```bash# Providersn8n-cli promotion-provider listn8n-cli promotion-provider get <id> # re-read the public key; the list omits itecho '{"name":"New name"}' | n8n-cli promotion-provider update <id> --stdinn8n-cli promotion-provider delete <id> # fails while a connection uses it # Connectionsn8n-cli promotion-connection list --scope=instancen8n-cli promotion-connection list --provider=<providerId>n8n-cli promotion-connection get <id>echo '{"name":"New name"}' | n8n-cli promotion-connection update <id> --stdinn8n-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 --stdinecho '{"settings":{"schemaVersion":1,"baseBranchName":"main","createBranchOnPromotion":false}}' \ | n8n-cli promotion-connection set-config <id> promote --stdinn8n-cli promotion-connection delete-config <id> applyn8n-cli promotion-connection disconnect <id> promote # Link projects to a "projects"-scoped connectionn8n-cli promotion-connection list-projects <id>n8n-cli promotion-connection add-project <id> <projectId>n8n-cli promotion-connection remove-project <id> <projectId>``` Key points:- Pass every JSON body through `--stdin` or `--file`, never through a flag. This keeps credentials off the command line.- `authType` is `ssh-key` or `token`. `token` means an HTTP(S) username and password, not a Git host API token. `publicKey` is `null` for a `token` provider.- `createBranchOnPromotion` is always required in a promote configuration.- `promote` and `apply` work on the `instance` connection only, and need their direction cloned first. Cloning one direction does not make the other ready.- API key scopes for this group are named `gitConnection:*`. `promote` also needs `variable:list` when the workflows reference variables. ## Other ```bash# Security auditn8n-cli auditn8n-cli audit --categories=credentials,nodes # Source controln8n-cli source-control pull # View confign8n-cli config show``` ## Composability Patterns The CLI is designed to be piped and composed: ```bash# Get all workflow IDsn8n-cli workflow list --jq '.[].id' # Get the name of the first workflown8n-cli workflow list --jq '.[0].name' # Export a workflow to a filen8n-cli workflow get 1234 --json > workflow-backup.json # Find failing executions for a workflown8n-cli execution list --workflow=1234 --status=error --json # Pipe workflow JSON for modificationn8n-cli workflow get 1234 --json | jq '.name = "Updated Name"' | n8n-cli workflow update 1234 --stdin # Table output without headers for shell parsingn8n-cli workflow list --no-header | awk '{print $1}' # Debug API callsn8n-cli workflow list --debug 2>debug.log``` ## Workflow JSON Structure When creating or updating workflows, the JSON follows this structure: ```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 }]] } }}``` Key points:- `nodes[].type` follows the pattern `n8n-nodes-base.<nodeName>` for built-in nodes- `connections` is keyed by source node name, with `main` output arrays- Each connection specifies target `node`, `type` (usually `main`), and output `index`- Use `workflow get <id> --json` to see real examples from the instance
Discovery context
Discovered by repository scan. No exact path reference found in the snapshot’s root AGENTS.md.