n8n-cli

Q: How do I install n8n-cli?

Run npx skills add https://github.com/n8n-io/n8n --skill n8n-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/n8n-cli/ (personal) or .claude/skills/n8n-cli/ (project).

by n8n-io OfficialProductivity & Automation

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.

Installs: 208
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/n8n-io/n8n --skill n8n-cli

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads n8n-cli automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

# 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_...

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

# 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>

Executions

# 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>

Credentials

# 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>

Tip: Use credential schema <type> to discover required fields before creating.

Projects

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>

Variables

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>

Data Tables

# 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

Users

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

Promotions

Move projects between instances through a Git repository. A provider holds the credentials, a connection names the repository, and a configuration sets up one direction on it: promote pushes to Git, apply imports from 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>

Apply a reviewed commit only:

# 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.

Connection JSON for step 2:

{
  "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" } }
  }
}

# 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>

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.
apply and apply-continue import nothing on exit code 3 (source-changed) or 4 (blocked). Check $?, or the status field in JSON output, before you read counts. With --json, a blocked result lists what is missing under preflight.
The --expected-* flags go together: pass all three or none. The commit SHA must be the full SHA.
API key scopes for this group are named gitConnection:*. promote also needs variable:list when the workflows reference variables.

Other

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

# Source control
n8n-cli source-control pull

# View config
n8n-cli config show

Composability Patterns

The CLI is designed to be piped and composed:

# 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

Workflow JSON Structure

When creating or updating workflows, the JSON follows this structure:

{
  "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

FAQ

What does the n8n-cli skill do?

How do I install n8n-cli?

Run npx skills add https://github.com/n8n-io/n8n --skill n8n-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/n8n-cli/ (personal) or .claude/skills/n8n-cli/ (project).

Which AI agents can use n8n-cli?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is n8n-cli safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains n8n-cli?

It is published by n8n-io in n8n-io/n8n, and it is an official skill from the maker of the technology it covers. It has 208 recorded installs.

More from n8n-io/n8n

View all →

create-pr

n8n-io/n8n

Creates GitHub pull requests with properly formatted titles that pass the check-pr-title CI validation. Use when creating PRs, submitting changes for review, or when the user says /pr or asks to create a pull request.

OfficialCode Quality & Workflow847 installs