CLI Package - Development Guide

Note: This guide is for developers who want to understand, extend, or contribute to the command-line interface component of n8n-as-code.

🎯 Purpose

The CLI package (n8nac) provides a command-line interface for managing n8n workflows from the terminal. It offers:

Project Management: Initialize and configure n8n-as-code projects
Workflow Synchronization: Sync workflows between local files and n8n with git-like commands
AI Assistance: AI-powered workflow generation and assistance

🏗️ Architecture

Package Structure

packages/cli/
├── src/
│   ├── index.ts              # CLI entry point (registers all commands)
│   ├── commands/
│   │   ├── base.ts           # Base command class
│   │   ├── update-ai.ts      # UpdateAiCommand
│   │   ├── list.ts           # List command
│   │   ├── convert.ts        # Convert command (JSON ↔ TypeScript)
│   │   └── sync.ts           # Sync command (pull / push / fetch / resolve)
│   ├── core/
│   │   ├── types.ts          # WorkflowSyncStatus enum, interfaces
│   │   ├── sync-manager.ts   # Core sync engine
│   │   └── ...               # API client, services
│   └── services/
│       └── config-service.ts # Configuration management
├── bin/
│   └── n8n-as-code.js        # CLI executable
├── package.json              # Package manifest
└── tsconfig.json             # TypeScript configuration

Command Hierarchy

🧩 Sync Components

1. CLI Entry Point (`index.ts`)

The main entry point that sets up the CLI application.

Key Responsibilities:

Parse command-line arguments
Initialize configuration
Execute appropriate command
Handle global errors

Setup:

import { Command } from 'commander';
import { InitCommand, SyncCommand, ListCommand, InitAICommand } from './commands';

const program = new Command();

program
  .name('n8n-as-code')
  .description('Manage n8n workflows as code')
  .version(version);

// Register commands
new InitCommand(program);
new SyncCommand(program);
new ListCommand(program);
new InitAICommand(program);

program.parse(process.argv);

2. Base Command (`commands/base.ts`)

Abstract base class for all commands.

Key Responsibilities:

Provide common command functionality
Handle error reporting
Manage configuration loading
Provide logging utilities

Base Implementation:

abstract class BaseCommand {
  protected config: Config;
  protected logger: Logger;
  
  constructor(protected program: Command) {
    this.config = ConfigService.load();
    this.logger = new Logger(program.opts().verbose);
  }
  
  abstract execute(options: any): Promise<void>;
  
  protected handleError(error: Error): void {
    this.logger.error(error.message);
    process.exit(1);
  }
}

3. Workspace Commands

Workspace commands own only local overrides over the global n8n-manager configuration.

Key Responsibilities:

Show backend-resolved workspace status
Pin or clear the effective workspace instance
Set or clear legacy workspace sync-folder overrides
Set or clear the workspace project override

4. Sync Command (`commands/sync.ts`)

Synchronizes workflows between local files and n8n.

Key Responsibilities:

Pull workflows from n8n to local files
Push local workflows to n8n
Handle conflicts and resolutions
Provide sync progress reporting

Sync Modes:

interface SyncOptions {
  mode: 'pull' | 'push' | 'both';
  force: boolean;
  dryRun: boolean;
  instance?: string;
}

5. List Command (`commands/list.ts`)

Shows current sync status of all workflows.

Key Responsibilities:

Fetch fresh remote metadata on each invocation
Calculate 3-way status (local vs remote vs base)
Display color-coded status table
Support --local / --remote filters for focused views

6. Update AI Command (`commands/update-ai.ts`)

Regenerates AI context files for the project.

Key Responsibilities:

Generate AGENTS.md with n8n-specific AI agent instructions
Generate .vscode/n8n.code-snippets from the n8n node index
Optionally connect to n8n to embed the running instance version

7. Config Service (`services/config-service.ts`)

Manages CLI configuration.

Key Responsibilities:

Load configuration from multiple sources
Validate configuration
Merge environment variables and file config
Provide typed configuration access

Configuration Sources: The CLI currently loads local configuration from n8nac-config.json in the current working directory and stores API keys in a secure global credential store.

🔄 Integration with CLI Core

Sync Engine Usage

The CLI commands use the sync engine (embedded in packages/cli/src/core/):

import { SyncManager, StateManager, N8nApiClient } from 'n8nac';

class SyncCommand extends BaseCommand {
  private syncManager: SyncManager;
  
  constructor() {
    super();
    this.syncManager = new SyncManager(this.config);
  }
  
  async execute(options: any): Promise<void> {
    const result = await this.syncManager.sync({
      mode: options.mode,
      force: options.force
    });
    
    this.logger.reportSyncResult(result);
  }
}

Event Handling

The CLI listens to Sync library events:

syncManager.on('sync:progress', (progress) => {
  this.logger.progress(progress);
});

syncManager.on('sync:conflict', (conflict) => {
  this.logger.conflict(conflict);
  // Prompt user for resolution
});

syncManager.on('sync:complete', (result) => {
  this.logger.success(`Synced ${result.synced} workflows`);
});

🛠️ Development Setup

Prerequisites

Node.js 18+
n8n instance for testing
Git (for version control features)

Local Development

# Install dependencies
cd packages/cli
npm install

# Build CLI
npm run build

# Link for local testing
npm link

# Test commands
n8nac --help

Testing with Local n8n

Start a local n8n instance.
Get an API key from n8n settings.
Configure a workspace environment:

n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env auth set Dev --api-key-stdin
n8nac env use Dev

🔧 Adding New Commands

Step 1: Create Command Class

// commands/new-command.ts
import { Command } from 'commander';
import { BaseCommand } from './base';

export class NewCommand extends BaseCommand {
  constructor(program: Command) {
    super(program);
    
    program
      .command('new-command')
      .description('Description of new command')
      .option('--option <value>', 'Option description')
      .action(this.execute.bind(this));
  }
  
  async execute(options: any): Promise<void> {
    // Command implementation
    this.logger.info('New command executed');
  }
}

Step 2: Register Command

// index.ts
import { NewCommand } from './commands/new-command';

// Add to command registration
new NewCommand(program);

Step 3: Update TypeScript Configuration

Ensure the new command is included in the build.

🧪 Testing

Test Structure

packages/cli/
└── tests/
    ├── unit/
    │   ├── commands/
    │   │   ├── init.test.ts
    │   │   └── sync.test.ts
    │   └── services/
    │       └── config-service.test.ts
    └── integration/
        └── cli-integration.test.ts

Running Tests

cd packages/cli
npm test

Mocking

Mock file system and n8n API for testing:

import mockFs from 'mock-fs';
import nock from 'nock';

beforeEach(() => {
  mockFs({
    'workflows': {},
    'n8nac-config.json': JSON.stringify({
      version: 4,
      activeEnvironmentId: 'dev',
      environments: [{
        id: 'dev',
        name: 'Dev',
        environmentTargetId: 'dev',
        projectId: 'personal',
        projectName: 'Personal',
        workflowsPath: 'workflows/dev'
      }],
      environmentTargets: [{
        id: 'dev',
        name: 'Dev',
        kind: 'external-instance', // persisted kind for a remote n8n URL target
        url: 'http://test.n8n'
      }]
    })
  });
  
  nock('http://test.n8n')
    .get('/api/v1/workflows')
    .reply(200, []);
});

afterEach(() => {
  mockFs.restore();
  nock.cleanAll();
});

📦 Packaging and Distribution

Building for Production

npm run build

Creating Executable

The CLI uses pkg or nexe for creating standalone executables:

{
  "bin": {
    "n8nac": "./dist/index.js"
  }
}

Publishing to npm

npm version patch
npm publish

🔐 Security Considerations

API Key Management

Never Log: API keys are never logged
Environment Variables: Preferred over config files
Encryption: Optional encryption for stored keys

Input Validation

Validate All Inputs: Host URLs, file paths, etc.
Sanitize Outputs: Prevent injection attacks
Rate Limiting: Prevent abuse of n8n API

📈 Performance Optimization

Command Performance

Lazy Loading: Load Sync library only when needed
Caching: Cache configuration and API responses
Parallel Processing: Sync multiple workflows in parallel

Memory Management

Stream Processing: Process large workflows as streams
Cleanup: Proper disposal of resources
Monitoring: Track memory usage

🐛 Troubleshooting

Common Issues

Connection Failed

# Test connection manually
curl -H "X-N8N-API-KEY: your-key" https://your-n8n.com/api/v1/workflows

Configuration Not Found

Check current directory for n8nac-config.json.
Run n8nac env add Dev --base-url <url> --workflows-path workflows/dev to create an environment.
Run n8nac env auth set Dev --api-key-stdin to store the local API key.

Sync Conflicts

Review conflict details in output
Use --force to overwrite (with caution)
Manually resolve in n8n UI

Debug Mode

Enable verbose logging:

DEBUG=n8n-as-code:* n8nac list

Log Files

Check the terminal output (and VS Code Output panel when using the extension) for detailed error information.

Sync Engine: Sync engine internals (embedded in CLI)
Architecture Overview: Overall system architecture
VS Code Extension: VS Code extension development
Contribution Guide: How to contribute

The n8nac package provides powerful command-line tools for n8n workflow management, enabling automation, scripting, and integration with other development tools. It also exposes n8nac skills — a subcommand group bridging to the @n8n-as-code/skills library for AI agent tooling.

🎯 Purpose​

🏗️ Architecture​

Package Structure​

Command Hierarchy​

🧩 Sync Components​

1. CLI Entry Point (index.ts)​

2. Base Command (commands/base.ts)​

3. Workspace Commands​

4. Sync Command (commands/sync.ts)​

5. List Command (commands/list.ts)​

6. Update AI Command (commands/update-ai.ts)​

7. Config Service (services/config-service.ts)​

🔄 Integration with CLI Core​

Sync Engine Usage​

Event Handling​

🛠️ Development Setup​

Prerequisites​

Local Development​

Testing with Local n8n​

🔧 Adding New Commands​

Step 1: Create Command Class​

Step 2: Register Command​

Step 3: Update TypeScript Configuration​

🧪 Testing​

Test Structure​

Running Tests​

Mocking​

📦 Packaging and Distribution​

Building for Production​

Creating Executable​

Publishing to npm​

🔐 Security Considerations​

API Key Management​

Input Validation​

📈 Performance Optimization​

Command Performance​

Memory Management​

🐛 Troubleshooting​

Common Issues​

Connection Failed​

Configuration Not Found​

Sync Conflicts​

Debug Mode​

Log Files​

📚 Related Documentation​

🎯 Purpose

🏗️ Architecture

Package Structure

Command Hierarchy

🧩 Sync Components

1. CLI Entry Point (`index.ts`)

2. Base Command (`commands/base.ts`)

3. Workspace Commands

4. Sync Command (`commands/sync.ts`)

5. List Command (`commands/list.ts`)

6. Update AI Command (`commands/update-ai.ts`)

7. Config Service (`services/config-service.ts`)

🔄 Integration with CLI Core

Sync Engine Usage

Event Handling

🛠️ Development Setup

Prerequisites

Local Development

Testing with Local n8n

🔧 Adding New Commands

Step 1: Create Command Class

Step 2: Register Command

Step 3: Update TypeScript Configuration

🧪 Testing

Test Structure

Running Tests

Mocking

📦 Packaging and Distribution

Building for Production

Creating Executable

Publishing to npm

🔐 Security Considerations

API Key Management

Input Validation

📈 Performance Optimization

Command Performance

Memory Management

🐛 Troubleshooting

Common Issues

Connection Failed

Configuration Not Found

Sync Conflicts

Debug Mode

Log Files

📚 Related Documentation