mirror of https://github.com/n8n-io/n8n.git synced 2026-05-22 20:35:23 +02:00

feat: Add @n8n/cli: a client CLI to manage n8n from the terminal (#26943 )

Co-authored-by: Daria Staferova <daria.staferova@n8n.io>
Co-authored-by: Nikhil Kuriakose <nikhil.kuriakose@n8n.io>

2026-03-20 14:11:35 +00:00

2.5 KiB

Raw Permalink Blame History

Getting Started

Installation

# Use directly with npx (zero install)
npx @n8n/cli workflow list

# Or install globally
npm install -g @n8n/cli

Configuration

The CLI needs two things: your n8n instance URL and an API key.

Option 1: Config file (recommended)

n8n-cli config set-url https://my-n8n.app.n8n.cloud
n8n-cli config set-api-key n8n_api_xxxxx

# Verify
n8n-cli config show

Configuration is saved to ~/.n8n-cli/config.json with restricted file permissions (0600).

Option 2: Environment variables

export N8N_URL=https://my-n8n.app.n8n.cloud
export N8N_API_KEY=n8n_api_xxxxx

Option 3: Inline flags

n8n-cli --url=https://my-n8n.app.n8n.cloud --api-key=n8n_api_xxxxx workflow list

Resolution order

The CLI resolves configuration in this priority order:

Command-line flags (--url, --api-key)
Environment variables (N8N_URL, N8N_API_KEY)
Config file (~/.n8n-cli/config.json)

Your first commands

# List all workflows
n8n-cli workflow list

# Get a specific workflow as JSON
n8n-cli workflow get 1234 --format=json

# List failed executions
n8n-cli execution list --status=error --limit=5

# Create a tag
n8n-cli tag create --name=production

Output formats

Every command supports three output formats:

Format	Flag	Use case
Table	`--format=table` (default)	Human-readable terminal display
JSON	`--format=json`	Piping to `jq`, programmatic use
ID-only	`--format=id-only`	Piping to `xargs`, scripting

# Human reads a table
n8n-cli workflow list

# AI agent or script gets JSON
n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'

# Pipe IDs to deactivate all workflows
n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}

AI agent skills

The CLI ships with a skill that teaches AI coding agents how to use n8n-cli.

# Claude Code (installs to .claude/skills/n8n-cli/ in the current project)
n8n-cli skill install

# Claude Code (global — installs to ~/.claude/skills/n8n-cli/)
n8n-cli skill install --global

# Cursor (appends to .cursorrules)
n8n-cli skill install --target=cursor

# Windsurf (appends to .windsurfrules)
n8n-cli skill install --target=windsurf

Then use /n8n-cli in Claude Code to load the skill.

Getting help

Every command has built-in help:

n8n-cli --help
n8n-cli workflow --help
n8n-cli workflow list --help

2.5 KiB Raw Permalink Blame History