@n8n/node-cli

Official CLI for developing community nodes for n8n.

🚀 Getting Started

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.

📦 Generated Project Commands

After creating your node with npm create @n8n/node, you'll use these commands in your project:

Development

bash

npm run dev
# Runs: n8n-node dev

Building

bash

npm run build
# Runs: n8n-node build

Linting

bash

npm run lint
# Runs: n8n-node lint

npm run lint:fix
# Runs: n8n-node lint --fix

Publishing

bash

npm run release
# Runs: n8n-node release

🛠️ CLI Reference

Note: These commands are typically wrapped by npm scripts in generated projects.

bash

n8n-node [COMMAND] [OPTIONS]

Commands

`n8n-node new`

Create a new node project.

bash

n8n-node new [NAME] [OPTIONS]

Flags:

Flag	Description
`-f, --force`	Overwrite destination folder if it already exists
`--skip-install`	Skip installing dependencies
`--template <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 npm create @n8n/node to provide the interactive scaffolding experience.

`n8n-node dev`

Run n8n with your node in development mode with hot reload.

bash

n8n-node dev [--external-n8n] [--custom-user-folder <value>]

Flags:

Flag	Description
`--external-n8n`	Run n8n externally instead of in a subprocess
`--custom-user-folder <path>`	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/ directory

Examples:

bash

# Standard development with built-in n8n
n8n-node dev

# Use external n8n instance
n8n-node dev --external-n8n

# Custom n8n extensions directory
n8n-node dev --custom-user-folder /home/user

`n8n-node build`

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 dist/

`n8n-node lint`

Lint the node in the current directory.

bash

n8n-node lint [--fix]

Flags:

Flag	Description
`--fix`	Automatically fix problems

Examples:

bash

# Check for linting issues
n8n-node lint

# Automatically fix fixable issues
n8n-node lint --fix

`n8n-node cloud-support`

Manage n8n Cloud eligibility.

bash

n8n-node cloud-support [enable|disable]

Arguments:

Argument	Description
(none)	Show current cloud support status
`enable`	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 release`

Publish 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:

Create your node:

bash

npm create @n8n/node my-awesome-node
cd my-awesome-node

Start development:
bash
```
npm run dev
```
- Starts n8n on http://localhost:5678
- Links your node automatically
- Rebuilds on file changes
Test your node at http://localhost:5678
Lint your code:
bash
```
npm run lint
```
Build for production:
bash
```
npm run build
```
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 package.json:

json

{
  "name": "n8n-nodes-my-awesome-node",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": [
      "dist/nodes/MyNode/MyNode.node.js"
    ],
    "credentials": [
      "dist/credentials/MyNodeAuth.credentials.js"
    ]
  }
}

🐛 Troubleshooting

Development server issues

bash

# Clear n8n custom nodes cache
rm -rf ~/.n8n-node-cli/.n8n/custom

# Restart development server
npm run dev

Build failures

bash

# Run linting first
npm run lint

# Clean build
npm run build

📚 Resources

Creating Nodes Guide - Complete documentation
Node Development Reference - API specifications
Community Forum - Get help and showcase your nodes
@n8n/create-node - Recommended scaffolding tool

🤝 Contributing

Found an issue? Contribute to the n8n repository on GitHub.

Happy node development! 🎉