Skip to content

n8nctl

Control any n8n instance from your terminal. One static binary, many instances.

n8nctl is a fast, scriptable command-line client for the n8n public REST API. It manages workflows, executions, credentials, tags, variables, projects, users, data tables, the audit report, and the source-control integration on any n8n instance — self-hosted or Cloud — over HTTPS with an API key. Beyond plain CRUD it promotes workflows across instances, snapshots an instance to git, applies a directory of workflow files like GitOps, runs as an MCP server for AI agents, and gates workflow writes behind a linter. It is built in Go as a single static binary: no Node runtime to install and nothing to keep updated except one file on your PATH.

Unofficial

Not affiliated with n8n. Talks to the public API at <your-host>/api/v1 using the X-N8N-API-KEY header.

Install

brew install jjuanrivvera/n8n-cli/n8nctl-cli   # macOS/Linux

Or go install github.com/jjuanrivvera/n8n-cli/cmd/n8nctl@latest, or download a prebuilt binary from the latest release. Then run the first-time setup:

n8nctl init             # name a profile, capture the base URL and API key
n8nctl workflows list   # list workflows on the active instance

Features at a glance

Resource management — full CRUD over every API resource.

  • Workflows, executions, credentials, projects, users, tags, variables, and data tables, with resource-specific actions (activate, retry, transfer, members, rows, and more). Plus the audit report, package import/export, and source-control pull. → Features

Fleet operations — work across instances and to disk.

  • workflows sync promotes a workflow between instances; backup/restore snapshot an instance for git versioning; workflows search finds workflows by node type, credential, webhook path, or name. → Beyond the API

Workflows as code — GitOps for workflow definitions.

  • workflows apply --dir reconciles a directory of files into an instance (--prune, --dry-run); lint runs static checks; diff compares against another instance or a file; convert moves between JSON and YAML. → Workflows as Code

AI agents — a safe tool surface for coding agents.

  • mcp runs the CLI as a Model Context Protocol server; agent guard blocks destructive operations; proxy lint-gates every workflow write; skills install ships the agent skill. → MCP server · Agent guard · Lint-enforcing proxy

Output and scripting — built for pipelines.

  • table/json/yaml/csv/id output, --columns, --jq (gojq) filtering, --dry-run that prints the equivalent curl, the raw api escape hatch, and cursor pagination with --all. → Output and filtering

Multi-instance and security — many instances, secrets in the keyring.

Resilience — predictable under load.

  • Idempotent-only retry with backoff, adaptive client-side rate limiting, clean Ctrl-C cancellation, typed API errors with hints, and tolerant JSON parsing of n8n's loose encodings. → Features

Where to next