n8nctl 0.1.0

CLI for managing n8n Cloud workflows

n8n CLI

A command-line tool for managing n8n Cloud workflows.

Installation

Global Installation (Recommended)

uv tool install .

Configuration

Create a credentials file with your n8n API credentials. The file can be placed in:

• Your current working directory as .env (project-specific)
• ~/.config/n8n-cli/config (global configuration)

Project-specific (.env in current directory):

N8N_API_KEY=your-api-key
N8N_INSTANCE_URL=https://your-instance.app.n8n.cloud/api/v1

Global (~/.config/n8n-cli/config):

N8N_API_KEY=your-api-key
N8N_INSTANCE_URL=https://your-instance.app.n8n.cloud/api/v1

Alternatively, set environment variables:

export N8N_API_KEY="your-api-key"
export N8N_BASE_URL="https://your-instance.app.n8n.cloud/api/v1"

Development Installation

For local development:

uv sync

Development

# Install with dev dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Clean install tool globally (clears cache for fresh build)
uv run poe install

# Quick reinstall without cache clean (faster)
uv run poe reinstall

# Run tests
uv run poe test

# Run code quality checks
uv run poe check        # lint + typecheck + test
uv run poe lint         # just linting
uv run poe typecheck    # just type checking
uv run poe format       # format code

# Run pre-commit hooks manually
uv run pre-commit run --all-files

Usage

n8n --help

Examples

Workflow Management

List all workflows:

n8n workflow list
n8n workflow list -v  # verbose output with more details

View workflow details:

n8n workflow view "My Workflow"

Activate/deactivate workflows:

n8n workflow activate "My Workflow"
n8n workflow deactivate "My Workflow"

Pull workflows to local files:

n8n workflow pull                    # Pull all workflows
n8n workflow pull "My Workflow"      # Pull specific workflow
n8n workflow pull --project "Sales"  # Pull all workflows from a project

Push local workflow to cloud:

n8n workflow push workflow.json
n8n workflow push workflow.json --update  # Update existing workflow

Create new workflow:

n8n workflow create new_workflow.json

Compare local and cloud versions:

n8n workflow diff workflow.json

Move workflow to different project:

n8n workflow move "My Workflow" --project "Marketing"

Open workflow in browser:

n8n workflow open "My Workflow"

Delete workflow:

n8n workflow delete "My Workflow"

Execution Management

List recent executions:

n8n execution list
n8n execution list --workflow "My Workflow"  # Filter by workflow
n8n execution list --limit 50                # Show more results

View execution details:

n8n execution view <execution-id>

Download execution data:

n8n execution download <execution-id>
n8n execution download <execution-id> -o execution.json

Retry failed execution:

n8n execution retry <execution-id>

Project Management

List all projects:

n8n project list

View project details:

n8n project view "Sales"

User & Member Management

List users:

n8n user list

Invite user:

n8n user invite [e-mail] --role member
n8n user invite [e-mail] --role admin

Remove user:

n8n user remove [e-mail]

List project members:

n8n member list --project "Sales"

Add member to project:

n8n member add [e-mail] --project "Sales" --role editor

Remove member from project:

n8n member remove [e-mail] --project "Sales"

Shell Completion

Enable tab completion for workflows, projects, and file paths:

Installation

Automatic (recommended):

n8n --install-completion

Follow the shell-specific instructions. You may need to restart your shell.

Manual setup:

Bash:

eval "$(n8n --show-completion bash)"
# Add to ~/.bashrc for persistence

Zsh:

eval "$(n8n --show-completion zsh)"
# Add to ~/.zshrc for persistence

Fish:

n8n --show-completion fish > ~/.config/fish/completions/n8n.fish

What Gets Completed

• Workflow names: n8n workflow view <TAB> shows your workflows
• Project names: n8n project view <TAB> shows your projects
• File paths: n8n workflow diff <TAB> shows .json files

Note: The n8n command must be available in your PATH for completion to work. Either activate the virtual environment (source .venv/bin/activate) or install globally.