---

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:

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 or Open VSX.
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

Claude Code

/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

Generic Agent Skills

Install the skill from the repository skills directory:

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

CLI

Install first. update-ai then writes agent instructions that name the local binary directly; without an install they fall back to npx, which pays npm's own startup on every one of the tens of calls an agent makes per task.

Create a workspace environment for an existing n8n URL:

npm install n8nac
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:

npm install n8nac
n8n-manager instance list
npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local
npx --yes n8nac update-ai

Then sync workflows explicitly:

npx --yes n8nac list
npx --yes n8nac pull <workflow-id>
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 · n8n-manager guide

Prereleases

To test upcoming features before they hit the stable release, append @next to any CLI/npm command or switch to the pre-release channel in your editor:

• CLI: npm install -g n8nac@next or run on demand with npx --yes n8nac@next <command>
• VS Code / Cursor: Click "Switch to Pre-Release Version" on the Marketplace or run:

  code --install-extension etienne-lescot.n8n-as-code --pre-release
  

• OpenClaw: openclaw plugins install @n8n-as-code/n8nac@next

Note: When testing prereleases, keep all entry points on the @next tag so that the extension, CLI, and agent skills remain aligned.

Command Groups

Primary Usage: n8nac env

n8nac env list
n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env add Local --managed-instance <id> --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

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

n8n-manager instance list
n8n-manager instance create
n8n-manager instance start <id>
n8n-manager instance stop <id>
n8n-manager instance remove <id>
n8n-manager tunnel start <id>
n8n-manager tunnel stop <id>

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

n8nac env use Dev
n8nac list
n8nac pull <workflow-id>
n8nac push workflows/dev/my-workflow.workflow.ts --verify
n8nac resolve <workflow-id> --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.

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

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 = {};
}

n8nac convert workflow.json --format typescript
n8nac convert-batch workflows/ --format typescript

Packages

Prereleases: Append @next to test any package or plugin before release (e.g. npx n8nac@next, npm i @n8n-as-code/transformer@next).

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.

Sponsor

If n8n-as-code saves you time, you can support its development through GitHub Sponsors.

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 — 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 exists.

Thanks to the n8n team and community for building and maintaining the workflow automation platform this project builds on.