Usage Guides

Welcome to the n8n-as-code usage guides. This section provides detailed instructions for using the primary tools in the n8n-as-code ecosystem.

🎯 What You'll Find Here

This section is organized by the primary user-facing tools:

Tool	Purpose	Best For
VS Code Extension	Integrated development environment	Visual editing, git-like sync, workflow validation
CLI	Command-line interface	Automation, scripting, CI/CD integration
Skills CLI	AI tools and node schemas	AI coding assistants, node search, schema retrieval
Claude Plugin	Claude Code plugin	High-level workflow creation, updates, and fixes through Claude

🎨 Choosing the Right Tool

For Visual Workflow Editing (Recommended)

Use the VS Code Extension if you:

• Prefer a visual interface with split-view editing
• Want git-like synchronization (push/pull/fetch) with explicit control
• Need workflow validation and schema checking
• Work primarily in VS Code for development
• Want to see n8n canvas preview while editing JSON

For Automation and Scripting

Use the CLI if you:

• Need to automate workflow management tasks
• Want to integrate with CI/CD pipelines
• Prefer working in the terminal
• Need to script bulk operations
• Want to run n8n-as-code in headless environments

🔄 Common Workflows

Basic Workflow Management with VS Code

graph LR
    A[Install Extension] --> B[Configure Connection]
    B --> C[Fetch & Pull Workflows]
    C --> D[Edit in Split View]
    D --> E[Push to n8n via Context Menu]
    E --> F[Version Control with Git]

Automation Pipeline with CLI

graph LR
    A[Git Push] --> B[CI/CD Pipeline]
    B --> C[Run Tests]
    C --> D[Validate JSON]
    D --> E[Push to n8n]
    E --> F[Deploy to Production]

🛠️ Integration Examples

VS Code + Git Integration

1. Edit workflows in VS Code with git-like sync controls
2. Push changes to n8n via the context menu
3. Commit changes to Git for version control
4. Review changes using Git diff
5. Collaborate with team members via Git
6. Deploy using CI/CD pipelines

CLI + Automation Scripts

#!/bin/bash
# Example automation script for CI/CD

# List available workflows on source instance
n8nac list

# Pull the specific workflows you need
n8nac pull <workflowId>

# Validate JSON syntax (using jq or other tools)
find workflows/ -name "*.json" -exec jq . {} >/dev/null 2>&1 \;

# Push to target environment
export N8N_HOST="https://target.n8n.example.com"
export N8N_API_KEY="$TARGET_API_KEY"
n8nac init
n8nac push workflows/instance/project/workflow.workflow.ts

📚 Quick Reference

Common Commands

Command	Description	Tool
n8nac init	Configure host/key and select project	CLI
n8nac switch	Switch active project	CLI
n8nac list	Show workflow status with filtering	CLI
n8nac pull	Download workflows from n8n	CLI
n8nac push	Upload workflows to n8n	CLI
n8nac update-ai	Generate AI context files	CLI
npx @n8n-as-code/skills search	Search for n8n nodes	Skills CLI
npx @n8n-as-code/skills get	Get node JSON schema	Skills CLI
npx @n8n-as-code/skills list	List all available nodes	Skills CLI
VS Code: Refresh button	Pull workflows	Extension
VS Code: Context menu	Fetch, pull, push workflows	Extension

Configuration Files

File	Purpose	Location
n8nac-config.json	Project settings	Project root
Credential store	API key storage	System keychain / credential store

🚀 Getting Started with Each Tool

1. VS Code Extension (Recommended)

1. Install from VS Code Marketplace
2. Configure connection in extension settings
3. Open workflow tree view from Activity Bar
4. Use context menu actions (right-click) for fetch, pull, push operations

2. CLI

1. Install globally: npm install -g n8nac
2. Initialize: n8nac init
3. (Optional) Switch project: n8nac switch
4. Sync workflows: n8nac pull
5. Use commands as needed for automation

3. AI Tools (via n8nac skills)

1. Run with npx: npx n8nac skills --help
2. Search for nodes: npx n8nac skills search "query"
3. Get node schemas: npx n8nac skills node-info nodeName
4. Use output for AI context or development

4. Claude Plugin (For Claude Code)

1. Add the marketplace: /plugin marketplace add EtienneLescot/n8n-as-code
2. Install the plugin: /plugin install n8n-as-code@n8nac-marketplace
3. Ask Claude high-level workflow requests
4. See Claude Plugin Guide for details

🔧 Advanced Features

Multi-Instance Management

Work with multiple n8n instances. Workflows are automatically organized by instance to avoid mixing files from different environments.

Git-like Sync Workflow

Follow a git-like pattern for synchronization: list workflows to see status, pull changes you want, edit locally, then push changes back.

Use n8nac list to check status, n8nac pull to download by workflow ID, and n8nac push <path> to upload the local workflow file you want to send.

Git Integration

Store workflows as JSON files in Git for version control, collaboration, and deployment pipelines.

AI Assistant Support

Generate context files that help AI coding assistants understand n8n workflow structure and provide accurate suggestions.

📖 Next Steps

Explore the specific guides for each tool:

• VS Code Extension Guide: Learn about visual editing, git-like sync, and advanced features
• CLI Guide: Master command-line usage, automation, and scripting
• Skills CLI Guide: Use AI tools for node search and schema retrieval

🔍 Internal Components

For information about internal components used by developers and AI assistants, see:

• Contribution Guide: Architecture, development setup, and internal packages

🆘 Troubleshooting

Common issues and solutions:

• Connection issues: Check n8n URL and API key
• File permission errors: Check file and directory permissions
• Extension not working: Restart VS Code or reinstall extension

For more help, check the Troubleshooting guide or open an issue.

---

Ready to dive deeper? Choose a tool below to get started with detailed guides.