mirror of
https://github.com/n8n-io/n8n.git
synced 2026-05-22 20:35:23 +02:00
20f1092815
Co-authored-by: Daria Staferova <daria.staferova@n8n.io> Co-authored-by: Nikhil Kuriakose <nikhil.kuriakose@n8n.io>
116 lines
2.5 KiB
Markdown
116 lines
2.5 KiB
Markdown
# Getting Started
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
export N8N_URL=https://my-n8n.app.n8n.cloud
|
|
export N8N_API_KEY=n8n_api_xxxxx
|
|
```
|
|
|
|
### Option 3: Inline flags
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. Command-line flags (`--url`, `--api-key`)
|
|
2. Environment variables (`N8N_URL`, `N8N_API_KEY`)
|
|
3. Config file (`~/.n8n-cli/config.json`)
|
|
|
|
## Your first commands
|
|
|
|
```bash
|
|
# 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 |
|
|
|
|
```bash
|
|
# 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`.
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
n8n-cli --help
|
|
n8n-cli workflow --help
|
|
n8n-cli workflow list --help
|
|
```
|