N8N Command Line Interface (CLI)

Command line interface for managing n8n instances.

Table of Contents

• Installation
  • Quick Install
  • Autocompletion
  • Manual Installation with Go
• Configuration
• Commands
  • Version
  • Workflows
    • List
    • Refresh
    • Sync
    • Activate
    • Deactivate
• Development
• Examples
  • Contact Form Example
  • AI-Enhanced Contact Form Example

Installation

Quick Install (Linux, macOS, Windows with WSL)

curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh

Or install a specific version:

curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh -s -- --version v0.1.0-rc.1

This script will automatically detect your operating system and architecture and install the appropriate binary.

Autocompletion

To enable auto completion for bash, zsh, or fish, run the following command:

source <(n8n completion bash) # for bash
source <(n8n completion zsh)  # for zsh
source <(n8n completion fish) # for fish

If you need it permanently, add it to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish).

Manual Installation with Go

go install github.com/edenreich/n8n-cli@latest

Configuration

Create a .env file in your current directory. The CLI will automatically load environment variables from this file.

N8N_API_KEY=your_n8n_api_key
N8N_INSTANCE_URL=https://your-instance.n8n.cloud

You can generate an API key in the n8n UI under Settings > API.

Alternatively, you can set these environment variables directly in your shell:

export N8N_API_KEY=your_n8n_api_key
export N8N_INSTANCE_URL=https://your-instance.n8n.cloud

Note: Environment variables set directly in your shell will take precedence over those defined in the .env file.

Important: Never commit your .env file containing API credentials to version control systems like GitHub. Make sure to add .env to your .gitignore file to prevent accidental exposure of sensitive credentials.

Commands

Version

Display the version information of the n8n CLI:

n8n --version
# Or use the explicit command
n8n version

Workflows

Manage n8n workflows with various subcommands.

List

List workflows from an n8n instance:

n8n workflows list

Options:

• --output, -o: Output format (default: "table"). Supported formats:
  • table: Human-readable tabular format
  • json: JSON format for programmatic use
  • yaml: YAML format for configuration files
• --limit, -l: Maximum number of workflows to return (default: 100, max: 250)

Examples:

# List workflows in default table format
n8n workflows list

# List workflows in JSON format
n8n workflows list --output json

# List workflows in YAML format
n8n workflows list --output yaml

# List workflows with custom limit
n8n workflows list --limit 50

Refresh

Refresh local workflow files with the current state from an n8n instance:

n8n workflows refresh --directory workflows/

The refresh command is an essential step before syncing to ensure you don't accidentally delete or overwrite workflows on the remote n8n instance. It pulls the current state of the workflows from n8n and updates or creates the corresponding local files.

Options:

• --directory, -d: Directory to store the workflow files (required)
• --dry-run: Show what would be updated without making changes
• --overwrite: Overwrite existing files even if they have a different name
• --output, -o: Output format for new workflow files (json or yaml)
• --no-truncate: Include all fields in output files, including null and optional fields (default: false)
• --all: Refresh all workflows from n8n instance, not just those in the directory.

Examples:

# Refresh only existing workflows in the directory
n8n workflows refresh --directory workflows/

# Refresh all workflows from n8n instance (including new ones)
n8n workflows refresh --directory workflows/ --all

# Preview what would be refreshed without making changes
n8n workflows refresh --directory workflows/ --dry-run

# Refresh workflows and save them as YAML files
n8n workflows refresh --directory workflows/ --output yaml

# Refresh workflows without minimizing the JSON/YAML output
n8n workflows refresh --directory workflows/ --no-truncate

Sync

Synchronize JSON workflows from a local directory to an n8n instance:

n8n workflows sync --directory workflows/

Options:

• --directory, -d: Directory containing workflow JSON/YAML files (required)
• --dry-run: Show what would be done without making changes
• --prune: Remove workflows from the n8n instance that are not present in the local directory
• --refresh: Refresh the local state with the remote state after sync (default: true)
• --output, -o: Output format for refreshed workflow files (json or yaml). If not specified, uses the existing file extension in the directory
• --all: Refresh all workflows from n8n instance when refreshing, not just those in the directory

How the sync command handles workflow IDs:

1. If a workflow file contains an ID:
   • If that ID exists on the n8n instance, the workflow will be updated
   • If that ID doesn't exist on the n8n instance, a new workflow will be created (n8n API doesn't allow specifying IDs when creating workflows)
2. If a workflow file doesn't have an ID, a new workflow will be created with a server-generated ID

This ensures that workflows maintain their IDs across different environments and prevents duplication.

Example:

# Sync workflows to the n8n instance
n8n workflows sync --directory workflows/

# Test without making changes
n8n workflows sync --directory workflows/ --dry-run

# Sync workflows and remove any remote workflows not in the local directory
n8n workflows sync --directory workflows/ --prune

# Sync workflows and refresh as JSON (overrides existing format)
n8n workflows sync --directory workflows/ --output json

# Sync workflows and refresh all workflows from n8n instance (including ones not in local directory)
n8n workflows sync --directory workflows/ --all

# Sync workflows without refreshing the local state afterward
n8n workflows sync --directory workflows/ --refresh=false

Activate

Activate a specific workflow by ID:

n8n workflows activate WORKFLOW_ID

This command activates a workflow in the n8n instance, making it ready to be triggered by events.

Deactivate

Deactivate a specific workflow by ID:

n8n workflows deactivate WORKFLOW_ID

This command deactivates a workflow in the n8n instance, stopping it from being triggered by events.

Development

Available Tasks

The project uses Taskfile for automating common development operations:

# Run unit tests
task test-unit

# Run integration tests
task test-integration

# Run all tests
task test-all

# Run linting
task lint

# Build the CLI
task build

# Run the CLI during development (args are passed to the CLI)
task cli -- workflows list

Examples

The project includes practical examples to help you understand how to use the n8n-cli in real-world scenarios:

Contact Form Example

A basic example that demonstrates how to set up a contact form workflow in n8n and synchronize it using the n8n-cli:

• HTML contact form
• n8n workflow for processing form submissions
• GitHub Actions workflow for automated synchronization

View Contact Form Example

AI-Enhanced Contact Form Example

An advanced example that builds upon the basic contact form by adding AI capabilities:

• AI-powered message processing (summarization, sentiment analysis, categorization)
• Response suggestions generated by AI

View AI-Enhanced Contact Form Example

These examples include complete workflow definitions, HTML templates, and detailed setup instructions.

Contributing

We welcome contributions! Please see the CONTRIBUTING.md guide for details on how to set up the development environment, project structure, testing, and the pull request process.