The Problem
Developers building automation with n8n must manually browse node documentation, copy JSON snippets, and keep schemas in sync with the running instance. This leads to frequent mismatches, copy‑paste errors, and wasted time when creating or maintaining workflows programmatically.
What This Does
n8n-as-code ships a generated TypeScript ontology of every n8n node (≈ 537 nodes, 7 700+ templates) that can be consumed locally by AI agents, IDE extensions, or a CLI. The core CLI lives under packages/cli and orchestrates:
Schema import – packages/cli/src/core/assets/n8n-workflows.d.ts provides full type definitions. Git‑like synchronization – packages/cli/src/commands/sync.ts and the SyncEngine (packages/cli/src/core/services/sync-engine.ts) detect drift between a local workflow repository and a remote n8n instance, then apply changes. Workflow generation – the WorkflowTransformerAdapter (packages/cli/src/core/services/workflow-transformer-adapter.ts) converts AI‑produced JSON into valid n8n workflow files.
Documentation, VS Code and Claude plugins consume the same underlying package (@n8n-as-code/skills in packages/skills), ensuring a single source of truth.
How To Use It
Setup
The repo uses a standard Node ecosystem:
Install the CLI globally (or as a dev dependency) npm i -g @n8n-as-code/cli Or from source cd packages/cli npm ci # installs exact versions from package.json
A Docker‑based “Marketplace Control Plane” (MCP) is also provided for self‑hosting:
cd packages/mcp/docker docker build -t n8nac-mcp . docker run -p 3000:3000 -v $(pwd)/.env:/app/.env n8nac-mcp
Configuration
Create a copy of .env-example as .env and fill the required values (e.g. N8NURL, N8NAPIKEY). The CLI reads this file via packages/cli/src/services/config-service.ts.
.env N8NURL=https://my-n8n-instance.com N8NAPIKEY=your-api-key-here
Running
Typical workflow lifecycle commands are defined in packages/cli/src/commands/:
Initialise a new project linked to an n8n instance n8nac init
Pull the current remote state into ./workflows
n8nac sync pull
Push local changes back to the server
n8nac sync push
Run a single workflow locally (uses the transformer)
n8nac workflow run ./workflows/example.json
The entry point is packages/cli/src/index.ts, which registers the above sub‑commands with commander (see packages/cli/src/commands/). CI is defined in .github/workflows/ci.yml, confirming the CLI builds and tests on each PR.
Real‑World Use
A CI pipeline can enforce that all committed workflows stay in sync with production:
.github/workflows/workflow-sync.yml name: Workflow Sync on: push jobs: sync: runs-on: ubuntu-latest steps: uses: actions/checkout@v3 run: npm ci run: n8nac sync pull # fetch latest from prod run: n8nac test # run unit tests in packages/cli/tests run: n8nac sync push # update prod if CI passes env: N8NURL: ${{ secrets.N8NURL }} N8NAPIKEY: ${{ secrets.N8NAPIKEY }}
The pipeline guarantees that any schema change in n8n (e.g., a new node version) is immediately reflected in the TypeScript types and in downstream AI‑generated workflows.
Code Health & Issues
Low – Missing lockfile for docs – docs/package.json has dependencies but no package-lock.json/pnpm-lock.yaml; reproducible installs for the docs site are not guaranteed. Medium – Incomplete env validation – config-service.ts loads env vars but does not abort if required keys (N8NURL, N8NAPI_KEY) are missing; runtime errors may surface later. Low – Docker entrypoints – Both entrypoint.sh and entrypoint.bun.sh exist; unclear which is default, could cause confusion for new users. Low – Test coverage – 44 test files exist across CLI, MCP, and skills packages; CI runs them, indicating reasonable coverage. Low – License present – MIT license is included (LICENSE). Low – Documentation depth – The docs/ site (Docusaurus) is comprehensive, and README links to usage pages for VS Code, Claude, and OpenClaw.
Overall the repo follows a monorepo pattern with clear separation (cli, mcp, skills). TypeScript strictness is enforced via tsconfig.json in each package, and CI validates build + tests on every push.
The Bottom Line
n8n-as-code delivers a practical, type‑safe bridge between n8n and AI‑driven development tools, backed by a functional CLI and Docker‑based server component. The codebase is reasonably healthy, with solid test coverage and CI, though a lockfile for the docs site and stricter env validation would improve reliability. Teams that already use n8n and want programmatic, version‑controlled workflow management—especially those integrating AI assistants—will find this solution ready for production.