Skip to content

Getting started with n8n CLI#

n8n CLI is a lightweight command-line client that communicates with a running n8n instance through the n8n API. It can run from any machine with network access and authenticates using an API key.

n8n CLI is in beta

Use it only for experimenting, local development, and personal projects and not for production workflows.

Use the API CLI to:

  • List and inspect workflows
  • Create a workflow from JSON
  • Check recent executions
  • Create a credential
  • Manage projects

All operations respect the permissions of the user and the scope of the API key.

n8n CLI versus server CLI#

If you need to manage your n8n instance (backups, license management, emergency resets), see the Server CLI, a built-in tool that runs on the same machine as n8n.

Aspect n8n CLI Server CLI
Runs from Any machine with network access Same machine as n8n
Authentication API key Direct database access
Requires n8n running Yes No (not required for most operations)
Best for Developers, integrations, AI agents Instance operators, backups, emergencies
Permissions Respects user roles and API key scopes Bypasses access control

Install n8n-cli#

1
2
3
4
5
# Use directly with npx (zero install)
npx @n8n/cli workflow list

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

Connect to your instance#

1
2
3
n8n-cli config set-url https://your-instance.n8n.cloud
n8n-cli config set-api-key YOUR_API_KEY
n8n-cli config show
  • The configuration is saved to ~/.n8n-cli/config.json with restricted file permissions (0600).
  • Get your API key from n8n > Settings > n8n API

Alternatively, skip the configuration file and use environment variables:

1
2
export N8N_URL=https://your-instance.n8n.cloud
export N8N_API_KEY=your_api_key

Inline flags#

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

Resolution order#

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

Commands#

Every command supports --help for detailed usage.

Topic Commands
workflow list, get, create, update, delete, activate, deactivate, tags, transfer
execution list, get, retry, stop, delete
credential list, get, schema, create, delete, transfer
project list, get, create, update, delete, members, add-member, remove-member
tag list, create, update, delete
variable list, create, update, delete
data-table list, get, create, delete, rows, add-rows, update-rows, upsert-rows, delete-rows
user list, get
config set-url, set-api-key, show
source-control pull
skill install
audit (top-level)
login / logout (top-level)

Output formats#

All commands support three output formats via --format:

Format Flag Use when
Table --format=table (default) You want human-readable terminal output
JSON --format=json Piping to jq, programmatic use
ID-only --format=id-only Piping to xargs, scripting

Examples#

  • Human-readable table
1
n8n-cli workflow list
  • JSON for scripts
1
n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'
  • Pipe IDs into another command
1
n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}

Use as skill with Claude Code#

Install the skill so Claude always knows how to use n8n-cli:

1
n8n-cli skill install --global

Then in Claude Code, type /n8n-cli to load it. Claude can now create, update, and manage workflows on your behalf without requiring an MCP.

Examples#

List and inspect workflows#

1
2
n8n-cli workflow list
n8n-cli workflow get <id>

Create a workflow from JSON#

1
cat workflow.json | n8n-cli workflow create --stdin

Check recent executions#

1
n8n-cli execution list --status=error --limit=10

Create a credential#

1
2
n8n-cli credential schema gmailOAuth2  # see required fields first
n8n-cli credential create --type=gmailOAuth2 --name='My Gmail' --file=cred.json

Manage projects#

1
2
n8n-cli project create --name="My Project"
n8n-cli workflow transfer <id> --project=<projectId>
This page was