Official CLI for developing community nodes for n8n
npm install @atom8n/node-cliOfficial CLI for developing community nodes for n8n.
To create a new node, run:
``bash`
npm create @n8n/node@latest # or pnpm/yarn/...
This will generate a project with npm scripts that use this CLI under the hood.
After creating your node with npm create @n8n/node, you'll use these commands in your project:
bash
npm run dev
Runs: n8n-node dev
`$3
bash
npm run build
Runs: n8n-node build
`$3
bash
npm run lint
Runs: n8n-node lint
npm run lint:fix
Runs: n8n-node lint --fix
`$3
bash
npm run release
Runs: n8n-node release
`š ļø CLI Reference
> Note: These commands are typically wrapped by
scripts in generated projects.`bash
n8n-node [COMMAND] [OPTIONS]
`$3
####
Create a new node project.
bash
n8n-node new [NAME] [OPTIONS]
`Flags:
| Flag | Description |
|------|-------------|
|
| Overwrite destination folder if it already exists |
| --skip-install | Skip installing dependencies |
| --template | Choose template: declarative/custom, declarative/github-issues, programmatic/example |Examples:
`bash
n8n-node new
n8n-node new n8n-nodes-my-app --skip-install
n8n-node new n8n-nodes-my-app --force
n8n-node new n8n-nodes-my-app --template declarative/custom
`> Note: This command is used internally by
to provide the interactive scaffolding experience.####
n8n-node devRun n8n with your node in development mode with hot reload.
bash
n8n-node dev [--external-n8n] [--custom-user-folder ]
`Flags:
| Flag | Description |
|------|-------------|
|
| Run n8n externally instead of in a subprocess |
| --custom-user-folder | Folder to use to store user-specific n8n data (default: ~/.n8n-node-cli) |This command:
- Starts n8n on
http://localhost:5678 (unless using --external-n8n)
- Links your node to n8n's custom nodes directory (~/.n8n-node-cli/.n8n/custom)
- Rebuilds on file changes for live preview
- Watches for changes in your src/ directoryExamples:
`bash
Standard development with built-in n8n
n8n-node devUse external n8n instance
n8n-node dev --external-n8nCustom n8n extensions directory
n8n-node dev --custom-user-folder /home/user
`####
Compile your node and prepare it for distribution.
bash
n8n-node build
`Flags: None
Generates:
- Compiled TypeScript code
- Bundled node package
- Optimized assets and icons
- Ready-to-publish package in
####
Lint the node in the current directory.
bash
n8n-node lint [--fix]
`Flags:
| Flag | Description |
|------|-------------|
|
| Automatically fix problems |Examples:
`bash
Check for linting issues
n8n-node lintAutomatically fix fixable issues
n8n-node lint --fix
`####
Manage n8n Cloud eligibility.
bash
n8n-node cloud-support [enable|disable]
`Arguments:
| Argument | Description |
|----------|-------------|
| _(none)_ | Show current cloud support status |
|
| Enable strict mode + default ESLint config |
| disable | Allow custom ESLint config (disables cloud eligibility) |Strict mode enforces the default ESLint configuration and community node rules required for n8n Cloud verification. When disabled, you can customize your ESLint config but your node won't be eligible for n8n Cloud verification.
####
n8n-node releasePublish your community node package to npm.
bash
n8n-node release
`Flags: None
This command handles the complete release process using release-it:
- Builds the node
- Runs linting checks
- Updates changelog
- Creates git tags
- Creates GitHub releases
- Publishes to npm
š Development Workflow
The recommended workflow using the scaffolding tool:
1. Create your node:
bash
npm create @n8n/node my-awesome-node
cd my-awesome-node
`2. Start development:
bash
npm run dev
`
- Starts n8n on
- Links your node automatically
- Rebuilds on file changes3. Test your node at
4. Lint your code:
bash
npm run lint
`5. Build for production:
bash
npm run build
`6. Publish:
bash
npm run release
`š Project Structure
The CLI expects your project to follow this structure:
my-node/
āāā src/
ā āāā nodes/
ā ā āāā MyNode/
ā ā āāā MyNode.node.ts
ā ā āāā MyNode.node.json
ā āāā credentials/
āāā package.json
āāā tsconfig.json
āļø Configuration
The CLI reads configuration from your
:`json
{
"name": "n8n-nodes-my-awesome-node",
"n8n": {
"n8nNodesApiVersion": 1,
"nodes": [
"dist/nodes/MyNode/MyNode.node.js"
],
"credentials": [
"dist/credentials/MyNodeAuth.credentials.js"
]
}
}
`š Troubleshooting
$3
bash
Clear n8n custom nodes cache
rm -rf ~/.n8n-node-cli/.n8n/customRestart development server
npm run dev
`$3
bash
Run linting first
npm run lintClean build
npm run build
``- Creating Nodes Guide - Complete documentation
- Node Development Reference - API specifications
- Community Forum - Get help and showcase your nodes
- @n8n/create-node - Recommended scaffolding tool
Found an issue? Contribute to the n8n repository on GitHub.
---
Happy node development! š