# n8n-as-code n8n-as-code ### The agentic toolkit for n8n. **VS Code / Cursor Agent · n8n Environments · n8n-manager · GitOps · AI Skills · TypeScript Workflows** [![CI](https://github.com/EtienneLescot/n8n-as-code/actions/workflows/ci.yml/badge.svg)](https://github.com/EtienneLescot/n8n-as-code/actions/workflows/ci.yml) [![Documentation](https://github.com/EtienneLescot/n8n-as-code/actions/workflows/docs.yml/badge.svg)](https://n8nascode.dev/) [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/etienne-lescot.n8n-as-code?label=VS%20Code&logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=etienne-lescot.n8n-as-code) [![Open VSX](https://img.shields.io/open-vsx/v/etienne-lescot/n8n-as-code?label=Open%20VSX&logo=eclipseide)](https://open-vsx.org/extension/etienne-lescot/n8n-as-code) [![npm: cli](https://img.shields.io/npm/v/n8nac?label=cli&logo=npm)](https://www.npmjs.com/package/n8nac) [![npm: skills](https://img.shields.io/npm/v/@n8n-as-code/skills?label=skills&logo=npm)](https://www.npmjs.com/package/@n8n-as-code/skills) [![Claude Code](https://img.shields.io/badge/Claude%20Code-Beta%20%2F%20Pending%20Review-orange)](https://n8nascode.dev/docs/usage/claude-plugin/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
n8n-as-code intro
**Build, edit, deploy, and debug n8n workflows from your editor with an agent that has live n8n context.** [**Documentation**](https://n8nascode.dev/) · [**Getting Started**](https://n8nascode.dev/docs/getting-started/) · [**VS Code Guide**](https://n8nascode.dev/docs/usage/vscode-extension/) · [**CLI Guide**](https://n8nascode.dev/docs/usage/cli/)
--- > **n8n version compatibility** — The node schema bundled with n8n-as-code is built against the latest stable release of n8n. Keep your n8n instance up to date for best generation and validation results. > **Independent project** — n8n-as-code is an independent community project and is not affiliated with, endorsed by, or sponsored by n8n. --- ## What n8n-as-code Gives You n8n-as-code turns a repository into a full n8n development workspace: | Capability | What it means | |---|---| | **Editor-native workflow work** | Browse, open, edit, validate, and sync n8n workflows from VS Code, Cursor, or the terminal. | | **Agent-ready context** | Generate grounded instructions, schemas, examples, and node knowledge so AI agents can work on real n8n workflows safely. | | **GitOps-style sync** | Pull and push workflows explicitly, review diffs, resolve conflicts, and keep workflow source in version control. | | **TypeScript workflow authoring** | Convert workflows into readable `.workflow.ts` files that are easier for people and agents to edit. | | **Live n8n operations** | Verify workflows, inspect credentials, run tests, activate workflows, and inspect executions against a selected n8n environment. | The repository stores workflow files, generated agent context, and workspace-safe configuration. Secrets and machine-local runtime state stay local. ## Quick Start ### VS Code / Cursor 1. Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=etienne-lescot.n8n-as-code) or [Open VSX](https://open-vsx.org/extension/etienne-lescot/n8n-as-code). 2. Open a folder or `.code-workspace`. 3. Click on the extension icon then on the gear icon to configure your workspace. 4. Create or select an `n8n environment`. 5. Pull or create workflows with the integrated Agent Workbench or the agent of your choice. The configuration UI uses the same model as the CLI: workspace environments are repository context, local managed instances are machine resources. [VS Code / Cursor guide](https://n8nascode.dev/docs/usage/vscode-extension/) ### Claude Code ```text /plugin marketplace add https://github.com/EtienneLescot/n8n-as-code /plugin install n8n-as-code@n8nac-marketplace ``` Then ask Claude for the workflow you want. The `n8n-architect` skill handles workspace setup, n8n context, validation, and sync steps as needed. [Claude setup docs](https://n8nascode.dev/docs/usage/claude-plugin/) ### Generic Agent Skills Install the skill from the repository skills directory: ```text https://github.com/EtienneLescot/n8n-as-code/tree/main/skills ``` Then ask your agent for the workflow you want. The skill gives it the n8n schemas, examples, validation rules, and workspace commands it needs to handle the rest. If your agent asks for an explicit skill path, use `skills/n8n-architect`. [Skills reference](https://n8nascode.dev/docs/usage/skills/) ### CLI Create a workspace environment for an existing n8n URL: ```bash npx --yes n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev printf '%s' "$N8N_API_KEY" | npx --yes n8nac env auth set Dev --api-key-stdin npx --yes n8nac env use Dev npx --yes n8nac update-ai ``` Or attach a local managed instance: ```bash n8n-manager instance list npx --yes n8nac env add Local --managed-instance --workflows-path workflows/local npx --yes n8nac env use Local ``` Then sync workflows explicitly: ```bash npx --yes n8nac list npx --yes n8nac pull npx --yes n8nac push workflows/dev/my-workflow.workflow.ts --verify npx --yes n8nac promote --from Dev --to Prod --dry-run ``` Use `promote` to move workflow source from one environment `workflowsPath` to another. Pass a workflow path for a single workflow, or omit it to promote every `*.workflow.ts` file in the source environment, including nested folders. Promotion rewrites target project metadata, remaps credentials and supported Execute Workflow references, records stable source-to-target bindings in `n8nac-promotion.json`, and pushes by default unless `--no-push` is set. `--dry-run` performs discovery for an accurate create/update plan, but does not write files, push, or update the promotion config. [CLI guide](https://n8nascode.dev/docs/usage/cli/) · [n8n-manager guide](https://n8nascode.dev/docs/usage/n8n-manager/) ## Command Groups ### Primary Usage: `n8nac env` ```bash n8nac env list n8nac env add Dev --base-url --workflows-path workflows/dev n8nac env add Local --managed-instance --workflows-path workflows/local n8nac env use Dev n8nac env auth set Dev --api-key-stdin n8nac env remove Dev ``` Use `n8nac env` for everything that describes how this repository connects to n8n. ### Workspace Inspection: `n8nac workspace` ```bash n8nac workspace status --json n8nac env status --json ``` Use `env status --json` as the source of truth for active environment readiness. ### Managed Local Instances: `n8n-manager` ```bash n8n-manager instance list n8n-manager instance create n8n-manager instance start n8n-manager instance stop n8n-manager instance remove n8n-manager tunnel start n8n-manager tunnel stop ``` Use `n8n-manager` only for local managed instances and machine-local operations. Do not use it as the workspace source of truth. ## GitOps For n8n ```bash n8nac env use Dev n8nac list n8nac pull n8nac push workflows/dev/my-workflow.workflow.ts --verify n8nac resolve --mode keep-current ``` Sync is explicit. Nothing is pushed or pulled unless you ask for it. ## AI Skills The skills layer gives agents grounded n8n knowledge: node schemas, docs, examples, templates, validation rules, and safe workflow operations. ```bash npx --yes n8nac skills search "send slack message when google sheet is updated" npx --yes n8nac skills node-info slack npx --yes n8nac skills validate workflows/dev/my-workflow.workflow.ts ``` ## TypeScript Workflows ```typescript import { workflow, node, links } from '@n8n-as-code/transformer'; @workflow({ id: 'abc123', name: 'Slack Notifier', active: true }) export class SlackNotifierWorkflow { @node() Trigger = { type: 'n8n-nodes-base.webhook', parameters: { path: '/notify', method: 'POST' }, position: [250, 300], }; @node() Slack = { type: 'n8n-nodes-base.slack', parameters: { resource: 'message', operation: 'post', channel: '#alerts', text: '={{ $json.message }}', }, position: [450, 300], }; @links([{ from: 'Trigger', to: 'Slack' }]) connections = {}; } ``` ```bash n8nac convert workflow.json --format typescript n8nac convert-batch workflows/ --format typescript ``` ## Packages | Package | What it does | Install | |:--------|:-------------|:--------| | **[VS Code Extension](packages/vscode-extension)** | Editor experience with sidebar, canvas, integrated Agent Workbench, and n8n environments | [Marketplace](https://marketplace.visualstudio.com/items?itemName=etienne-lescot.n8n-as-code) | | **[n8nac](packages/cli)** | CLI for workspace environments, sync, validation, AI context, and automation | `npx n8nac` | | **[Agent Skills](skills)** | Portable AI skills and embedded n8n knowledge for agents | [repo skills directory](https://github.com/EtienneLescot/n8n-as-code/tree/main/skills) | | **[@n8n-as-code/n8nac](plugins/openclaw/n8n-as-code)** | OpenClaw plugin with prompt context and portable skills | `openclaw plugins install @n8n-as-code/n8nac` | | **[@n8n-as-code/transformer](packages/transformer)** | JSON to TypeScript workflow converter and back | `npm i @n8n-as-code/transformer` | ## How The Pieces Fit - **VS Code/Cursor extension**: visual workflow workspace and integrated Agent Workbench. - **`n8nac env`**: repository-level environment source of truth. - **`n8nac workspace`**: readiness and unified workspace migration. - **`n8n-manager`**: local managed instances, Docker lifecycle, tunnels, and machine-local secrets. - **Skills and MCP**: grounded n8n knowledge for agents. ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=EtienneLescot/n8n-as-code&type=date&legend=top-left)](https://www.star-history.com/#EtienneLescot/n8n-as-code&type=date&legend=top-left) ## Contributing Contributions welcome. 1. Fork the project. 2. Create a branch: `git checkout -b feature/amazing`. 3. Run tests: `npm test`. 4. Open a Pull Request. ## License [MIT License](LICENSE) — free to use, modify, and distribute. Third-party community workflow metadata and downloadable workflow files remain subject to their respective upstream licenses. ## Acknowledgements `n8n-as-code` exists because [n8n](https://n8n.io/) exists. Thanks to the n8n team and community for building and maintaining the workflow automation platform this project builds on.
**If n8n-as-code saves you time, give us a star.** [Star on GitHub](https://github.com/EtienneLescot/n8n-as-code) · [Documentation](https://n8nascode.dev/) · [Report a Bug](https://github.com/EtienneLescot/n8n-as-code/issues)