Skip to main content

Getting Started with n8nac

Welcome to n8nac! This guide will help you set up and start using n8nac to manage your n8n workflows as code.

🎯 What You'll Learn​

In this section, you'll learn how to:

  1. Install n8nac VS Code Extension or CLI
  2. Configure your connection to n8n
  3. Inspect and pull the workflows you want locally
  4. Start editing workflows in VS Code

📋 Prerequisites​

Before you begin, make sure you have:

  • n8n instance running (self-hosted or cloud)
  • API key from your n8n instance (found in Settings > API)
  • VS Code (recommended for the best experience)

🚀 Quick Start: VS Code Extension (Recommended)​

The VS Code Extension provides the best user experience with visual editing, git-like sync controls, and workflow validation.

Step 1: Install VS Code Extension​

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "n8nac"
  4. Click Install

Step 2: Configure Connection​

  1. Click the n8n icon in the Activity Bar
  2. Click the gear icon (⚙️) to open settings
  3. Enter your n8n host URL (e.g., https://n8n.yourdomain.com)
  4. Enter your n8n API key
  5. The extension automatically loads your projects and pre-selects your Personal project
  6. Verify your settings and click "Save settings"

Step 3: Sync Your Workflows​

  1. Click the refresh button in the n8n panel
  2. Review the current status shown in the tree
  3. Pull the workflows you want to edit locally
  4. Use the context menu (right-click on a workflow) to fetch, pull, and push changes

🛠️ Alternative: CLI Installation​

If you prefer command-line tools or need automation:

Install CLI via npm​

# Install globally
npm install -g n8nac

# Verify installation
n8nac --version

Initialize Your Project​

# Run initialization wizard
n8nac init

The interactive wizard will guide you through:

  • n8n Host URL: The URL of your n8n instance
  • API Key: Your n8n API key
  • Sync Folder: Local folder where workflow files are written
  • Project: Which n8n project to sync

Sync Workflows (Git-like Pattern)​

# List workflows to see current status
n8nac list

# Pull that workflow locally
n8nac pull <workflowId>

# After editing, push changes back
n8nac push workflows/instance/project/workflow.workflow.ts

⚙️ Configuration Files​

After setup, you'll have:

  • n8nac-config.json: Workspace-level project configuration (safe to commit to Git)
  • Global credential storage for your API key (not committed, stored securely in your system)

🔄 Syncing Your Workflows​

Pull a Workflow​

Download a specific workflow from your n8n instance:

# List workflows to see what's available
n8nac list

# Pull the workflow you want
n8nac pull <workflowId>

This will:

  • Download the workflow file to your local directory
  • Refuse to overwrite if a conflict is detected (use n8nac resolve in that case)

Push Local Changes​

Send your local modifications back to n8n:

  • VS Code Extension: Use the context menu on workflow items (right-click → Push)
  • CLI: Use n8nac push <path> with the local workflow path you want to upload

Git-like Sync Workflow​

Follow this git-like pattern for synchronization:

# 1. Check status
n8nac list

# 2. Pull remote changes
n8nac pull <workflowId>

# 3. Edit workflow locally
# ... make changes ...

# 4. Push local changes
n8nac push workflows/instance/project/workflow.workflow.ts

# 5. If a conflict is reported, resolve it
n8nac resolve <workflowId> --mode keep-current   # keep local
n8nac resolve <workflowId> --mode keep-incoming  # keep remote

This explicit command pattern gives you full control over when to sync, similar to git workflow. pull always starts from a remote workflow ID, while push always starts from a local filename in the active sync scope.

🎨 VS Code Extension Features​

Once configured, you'll have access to:

  • Workflow Tree View: Browse all your workflows in the sidebar with status indicators
  • Split View Editing: Edit JSON while viewing the n8n canvas
  • Git-like Sync: Context menu actions for fetch, pull, and push operations
  • Validation & Snippets: JSON validation and code snippets
  • AI Context Generation: Files to help AI assistants understand n8n workflows

📁 Project Structure​

After setup, your project will look like this:

your-project/
├── n8nac-config.json             # Workspace configuration
├── workflows/                    # Workflow storage
│   └── instance-name_user/       # Instance identifier (auto-generated)
│       └── project-slug/         # Project slug (from project name)
│           ├── workflow-1.workflow.ts
│           ├── workflow-2.workflow.ts
│           └── folder/
│               └── workflow-3.workflow.ts
├── AGENTS.md                     # AI assistant instructions (optional)
└── .git/                         # Version control (recommended)

🚨 Common Issues​

Connection Issues​

Problem: Can't connect to n8n instance Solution:

  • Verify the n8n URL is correct and accessible
  • Check that API key has proper permissions
  • Ensure n8n instance is running and accessible

Permission Issues​

Problem: "Permission denied" when writing files Solution:

  • Check directory permissions
  • Run with appropriate user privileges
  • Use a different project directory

Sync Issues​

Problem: Changes not syncing properly Solution:

  • Use n8nac list to check workflow status
  • Use n8nac list to refresh status and identify the workflow ID you need
  • Use n8nac pull <workflowId> to get fresh copy
  • Use n8nac push <path> to send local changes
  • Use n8nac resolve <workflowId> --mode keep-current|keep-incoming if a conflict is reported
  • Check network connectivity to n8n instance

📚 Next Steps​

Now that you're set up, explore these resources:

🆘 Need Help?​

Ready to dive deeper? Continue to the VS Code Extension guide to learn about advanced editing features.