Skip to main content

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:

ToolPurposeBest For
VS Code ExtensionIntegrated development environmentVisual editing, real-time sync, workflow validation
CLICommand-line interfaceAutomation, scripting, CI/CD integration
Agent CLIAI tools and node schemasAI coding assistants, node search, schema retrieval
Claude SkillClaude Agent Skill packageUsing Claude AI to generate n8n workflows

🎨 Choosing the Right Tool​

Use the VS Code Extension if you:

  • Prefer a visual interface with split-view editing
  • Want real-time synchronization as you type
  • 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[Pull Workflows]
    C --> D[Edit in Split View]
    D --> E[Auto-sync to n8n]
    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 real-time sync
  2. Commit changes to Git for version control
  3. Review changes using Git diff
  4. Collaborate with team members via Git
  5. Deploy using CI/CD pipelines

CLI + Automation Scripts​

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

# Pull workflows from source instance
n8n-as-code pull

# 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"
n8n-as-code init
n8n-as-code push

📚 Quick Reference​

Common Commands​

CommandDescriptionTool
n8n-as-code initInitialize project configurationCLI
n8n-as-code pullDownload workflows from n8nCLI
n8n-as-code pushUpload workflows to n8nCLI
n8n-as-code watchReal-time sync modeCLI
n8n-as-code init-aiGenerate AI context filesCLI
npx @n8n-as-code/agent-cli searchSearch for n8n nodesAgent CLI
npx @n8n-as-code/agent-cli getGet node JSON schemaAgent CLI
npx @n8n-as-code/agent-cli listList all available nodesAgent CLI
VS Code: Refresh buttonPull workflowsExtension
VS Code: Save fileAuto-push to n8nExtension

Configuration Files​

FilePurposeLocation
n8n-as-code.jsonProject settingsProject root
VS Code SettingsConnection configVS Code settings

🚀 Getting Started with Each Tool​

  1. Install from VS Code Marketplace
  2. Configure connection in extension settings
  3. Open workflow tree view from Activity Bar
  4. Start editing with auto-sync enabled

2. CLI​

  1. Install globally: npm install -g @n8n-as-code/cli
  2. Initialize: n8n-as-code init
  3. Sync workflows: n8n-as-code pull
  4. Use commands as needed for automation

3. Agent CLI (For AI Tools)​

  1. Run with npx: npx @n8n-as-code/agent-cli --help
  2. Search for nodes: npx @n8n-as-code/agent-cli search "query"
  3. Get node schemas: npx @n8n-as-code/agent-cli get nodeName
  4. Use output for AI context or development

4. Claude Skill (For Claude AI)​

  1. Build: cd packages/claude-skill && npm run build
  2. Install to Claude.ai, Claude Code, or use via API
  3. Claude automatically uses the skill for n8n questions
  4. See Claude Skill 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.

Real-time Sync​

Changes made in VS Code are instantly reflected in n8n, and vice versa. No manual push/pull required when using watch mode.

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:

🔍 Internal Components​

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

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