@atom8n/node-cli

@n8n/node-cli

Official CLI for developing community nodes for n8n.

🚀 Getting Started

To create a new node, run:

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

npm run dev
# Runs: n8n-node dev

Building

npm run build
# Runs: n8n-node build

Linting

npm run lint
# Runs: n8n-node lint

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

Publishing

npm run release
# Runs: n8n-node release

🛠️ CLI Reference

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

n8n-node [COMMAND] [OPTIONS]

Commands

n8n-node new

Create a new node project.

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:

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.

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:

# 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.

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.

n8n-node lint [--fix]

Flags:

Flag	Description
--fix	Automatically fix problems

Examples:

# Check for linting issues
n8n-node lint

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

n8n-node cloud-support

Manage n8n Cloud eligibility.

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.

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:

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

• Start development:

  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:

  npm run lint
  

• Build for production:

  npm run build
  

• Publish:

  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:

{
  "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

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

# Restart development server
npm run dev

Build failures

# 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! 🎉