Command line interface for managing n8n instances.
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | shOr install a specific version:
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh -s -- --version v0.1.0-rc.1This script will automatically detect your operating system and architecture and install the appropriate binary.
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 fishIf you need it permanently, add it to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish).
go install github.com/edenreich/n8n-cli@latestCreate 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.cloudNote: 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.
Display the version information of the n8n CLI:
n8n --version
# Or use the explicit command
n8n versionManage n8n workflows with various subcommands.
List workflows from an n8n instance:
n8n workflows listOptions:
--output, -o: Output format (default: "table"). Supported formats:table: Human-readable tabular formatjson: JSON format for programmatic useyaml: YAML format for configuration files
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 yamlRefresh 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-truncateSynchronize 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:
- 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)
- 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=falseActivate a specific workflow by ID:
n8n workflows activate WORKFLOW_IDThis command activates a workflow in the n8n instance, making it ready to be triggered by events.
Deactivate a specific workflow by ID:
n8n workflows deactivate WORKFLOW_IDThis command deactivates a workflow in the n8n instance, stopping it from being triggered by events.
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 listThe project includes practical examples to help you understand how to use the n8n-cli in real-world scenarios:
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
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.
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.