### Clone and Setup Project

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Follow these commands to clone the project repository and set up your local environment by copying the example environment file.

```bash
# Clone this example
git clone <your-repo-url>
cd contact-form-ai

# Create environment configuration
cp .env.example .env
```

--------------------------------

### Clone and Setup Project

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Commands to clone the project repository and set up the initial environment configuration by copying the example .env file.

```bash
# Clone this example
git clone <your-repo-url>
cd contact-form

# Create environment configuration
cp .env.example .env
# Edit .env with your credentials
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Run this command to start the local environment, including the n8n instance and Mailhog for email testing.

```bash
task up
```

--------------------------------

### Environment Setup Command

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Command to set up the development environment by creating a .env file from a template.

```bash
# Environment setup
task setup-env   # Create .env from template
```

--------------------------------

### Install N8N CLI

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Installs the n8n CLI using a quick install script or the Go toolchain. Supports installing a specific version and enabling shell autocompletion.

```bash
# Quick install (Linux, macOS, Windows with WSL)
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh
```

```bash
# Install a specific version
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh -s -- --version v0.7.1
```

```bash
# Install via Go
go install github.com/edenreich/n8n-cli@latest
```

```bash
# Enable shell autocompletion (bash)
source <(n8n completion bash)
```

```bash
# Enable shell autocompletion (zsh)
source <(n8n completion zsh)
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Commands to start the local development environment using Taskfile or Docker Compose. This includes n8n, Mailhog for email testing, and Nginx for serving the contact form.

```bash
# Start the development environment
task up
# Or without Task: docker compose up -d --build

# Services will be available at:
# - n8n: http://localhost:5678
# - Mailhog: http://localhost:8025
# - Contact form: http://localhost:8080

# View service logs
task logs        # n8n logs
task logs-mail   # Mailhog logs
```

--------------------------------

### Install n8n CLI with Go

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Manually installs the n8n CLI using the Go package manager. Ensure Go is installed and configured on your system.

```go
go install github.com/edenreich/n8n-cli@latest
```

--------------------------------

### Get workflow ID and activate

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Demonstrates how to list workflows, filter by name using `jq`, extract the ID, and then activate the workflow. Requires `jq` to be installed.

```bash
n8n workflows list --output json | jq -r '.[] | select(.name=="Contact Form") | .id'
n8n workflows activate abc123def456
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Use this command to launch the local development environment, including n8n, Mailhog for email testing, and Nginx, using the Taskfile.

```bash
# Start n8n, mailhog, and nginx locally
task up
```

--------------------------------

### Install n8n CLI (Linux/macOS/WSL)

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Installs the n8n CLI using a curl script. Automatically detects OS and architecture. Use --version flag to install a specific version.

```bash
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh
```

```bash
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh -s -- --version v0.1.0-rc.1
```

--------------------------------

### Clone and Set Up n8n-cli Repository

Source: https://github.com/edenreich/n8n-cli/blob/main/CONTRIBUTING.md

Clone your forked repository and add the upstream remote for tracking changes. Install development dependencies using the provided task runner.

```bash
git clone https://github.com/YOUR-USERNAME/n8n-cli.git
cd n8n-cli
git remote add upstream https://github.com/edenreich/n8n-cli.git
task testing-deps
```

--------------------------------

### Docker Environment Management Commands

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Commands for managing the Docker environment, including starting, stopping, and viewing logs.

```bash
# Container management
task up          # Start n8n and mailhog
task down        # Stop containers
task restart     # Restart all services
task clean       # Remove containers and volumes

# Logs and debugging
task logs        # View n8n logs
task logs-mail   # View mailhog logs
```

--------------------------------

### GitHub Actions: Install n8n CLI

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Installs the n8n CLI within a GitHub Actions environment using a curl script. Ensure the script URL is correct.

```bash
curl -sSLf https://raw.github.com/edenreich/n8n-cli/main/install.sh | sh
```

--------------------------------

### Get n8n CLI Version

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Displays the installed version of the n8n CLI. Can be invoked using the main command or the explicit 'version' subcommand.

```bash
n8n --version
```

```bash
n8n version
```

--------------------------------

### Run Integration Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Execute only the integration tests. These tests interact with real n8n instances and require proper setup.

```bash
task test-integration   # Integration tests only  
```

--------------------------------

### Workflow Modifications Example (YAML)

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Shows common YAML-based customizations for n8n workflows, such as adding spam protection or configuring multiple recipients.

```yaml
# Add spam protection (in Contact_Form.yaml)
- Add IF node to check for spam keywords
- Integrate with reCAPTCHA

# Multiple recipients
- Duplicate Email node
- Set different recipients

# Auto-response
- Add second Email node
- Send confirmation to submitter
```

--------------------------------

### Webhook Security Configuration

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Example of how to add an authentication token to a webhook URL for enhanced security. Always use HTTPS webhooks.

```javascript
// Currently allows: https://example.com
// Update in webhook node settings:
"Access-Control-Allow-Origin": "https://your-domain.com"
```

--------------------------------

### Test Webhook Manually

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Example cURL command to manually test a webhook endpoint with JSON data.

```bash
curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@example.com","message":"Test message"}'
```

--------------------------------

### Display N8N CLI Version

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Shows the current version, git commit hash, and build date of the installed n8n CLI binary. Can be invoked using a flag or an explicit subcommand.

```bash
# Show version using the flag
n8n --version
```

```bash
# Show version using the explicit subcommand
n8n version
```

--------------------------------

### Check n8n API Connectivity

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Example cURL command to check connectivity to the n8n API using an API key.

```bash
curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  $N8N_INSTANCE_URL/api/v1/workflows
```

--------------------------------

### n8n Programmatic API Client (Go)

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Demonstrates how to use the n8n Go client to interact with an n8n instance. Requires API credentials and the n8n instance URL.

```go
package main

import (
    "fmt"
    "log"

    "github.com/edenreich/n8n-cli/n8n"
)

func main() {
    // Create a client connected to your n8n instance
    client := n8n.NewClient("https://mycompany.n8n.cloud", "n8n_api_abc123xyz")

    // List all workflows (up to 250)
    limit := 250
    workflows, err := client.GetWorkflows(&limit)
    if err != nil {
        log.Fatalf("failed to list workflows: %v", err)
    }
    for _, wf := range *workflows.Data {
        fmt.Printf("ID: %s  Name: %s  Active: %v\n", *wf.Id, wf.Name, *wf.Active)
    }

    // Get a single workflow by ID
    wf, err := client.GetWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("workflow not found: %v", err)
    }
    fmt.Println("Fetched:", wf.Name)

    // Activate a workflow
    activated, err := client.ActivateWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("activation failed: %v", err)
    }
    fmt.Println("Activated:", activated.Name)

    // Deactivate a workflow
    _, err = client.DeactivateWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("deactivation failed: %v", err)
    }

    // Create a new workflow from a struct
    newWf := &n8n.Workflow{
        Name: "My New Workflow",
        // ... populate Nodes, Connections, Settings
    }
    created, err := client.CreateWorkflow(newWf)
    if err != nil {
        log.Fatalf("create failed: %v", err)
    }
    fmt.Println("Created ID:", *created.Id)

    // Update an existing workflow
    updated, err := client.UpdateWorkflow("abc123def456", wf)
    if err != nil {
        log.Fatalf("update failed: %v", err)
    }
    fmt.Println("Updated:", *updated.Id)

    // Delete a workflow
    if err := client.DeleteWorkflow("abc123def456"); err != nil {
        log.Fatalf("delete failed: %v", err)
    }

    // Get execution history
    executions, err := client.GetExecutions("abc123def456", false, "error", 10, "")
    if err != nil {
        log.Fatalf("executions failed: %v", err)
    }
    fmt.Printf("Found %d failed executions\n", len(*executions.Data))

    // Manage tags
    tag, err := client.CreateTag("production")
    if err != nil {
        log.Fatalf("tag creation failed: %v", err)
    }
    tagIds := n8n.TagIds{{Id: *tag.Id}}
    _, err = client.UpdateWorkflowTags("abc123def456", tagIds)
    if err != nil {
        log.Fatalf("tag update failed: %v", err)
    }
}

```

--------------------------------

### Build Project with Version Info

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Build the project, incorporating version information. This task is essential for creating distributable artifacts.

```bash
# Build with version info
task build
```

--------------------------------

### Taskfile Help Command

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Displays all available commands for the Taskfile, providing a quick reference for development tasks.

```bash
task help        # Show all available commands
```

--------------------------------

### Configure n8n Environment Variables

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Shows how to set essential environment variables for connecting to an n8n instance, including API key and instance URL.

```bash
N8N_API_KEY=your_api_key_here
N8N_INSTANCE_URL=http://localhost:5678  # or your cloud instance
```

--------------------------------

### API Key Management Best Practices

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Essential practices for managing API keys, including ignoring .env files in git and using GitHub secrets for CI/CD.

```bash
# Never commit .env files
echo ".env" >> .gitignore

# Use GitHub secrets for CI/CD
# Rotate API keys regularly
# Use read-only keys when possible
```

--------------------------------

### Run n8n-cli in Docker

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Demonstrates how to run the n8n-cli within a Docker environment using either the standard release or a development build from source.

```bash
docker compose run --rm cli
n8n workflows list
```

```bash
docker compose run --rm cli-dev
n8n workflows list
```

--------------------------------

### Backup and refresh n8n workflows

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Creates a date-stamped backup directory and refreshes all workflows into it, saving them as JSON. Requires `mkdir` and `date` commands.

```bash
mkdir -p backups/$(date +%Y%m%d)
n8n workflows refresh --directory backups/$(date +%Y%m%d)/ --all --output json
```

--------------------------------

### Run All Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Execute all tests, including both unit and integration tests. This provides a comprehensive check of the project's stability.

```bash
task test              # All tests
```

--------------------------------

### Project Structure Overview

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

This snippet outlines the directory structure of the contact form project, highlighting key files and their purposes, including workflow definitions, Docker configurations, and CI/CD pipelines.

```tree
├── .github/
│   └── workflows/
│       └── sync-n8n.yml     # CI/CD pipeline for automatic n8n deployment
├── workflows/
│   └── Contact_Form.yaml    # n8n workflow definition (webhook → email)
├── docker-compose.yaml      # Local development environment setup
├── .env.example             # Environment variable template
├── .gitignore               # Version control exclusions
├── contact-form.html        # Frontend contact form with validation
├── Taskfile.yaml            # Development automation commands
└── README.md                # Project documentation
```

--------------------------------

### View recent n8n workflow executions

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Displays a formatted table of recent workflow executions, including ID, flow path, status, start time, duration, and trigger mode. Defaults to the last 10 executions.

```bash
n8n workflows executions
```

--------------------------------

### Preview workflow changes with n8n CLI

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Simulates refreshing workflows without writing changes to files. Useful for validation before applying.

```bash
n8n workflows refresh --directory workflows/ --dry-run
```

--------------------------------

### Deploy and Manage n8n Workflows

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Use these tasks to manage your n8n workflows. 'sync-dry-run' previews changes, 'sync' deploys them, and 'list' shows deployed workflows and their webhook URLs.

```bash
# Preview what will be synced (dry run)
task sync-dry-run

# Deploy the workflow to n8n
task sync

# Verify deployment
task list
```

--------------------------------

### Run Unit Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Execute only the unit tests for the project. This is useful for quick feedback during development.

```bash
# Run tests
task test-unit          # Unit tests only
```

--------------------------------

### Run All Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Executes all available tests, including unit and integration tests.

```bash
task test-all
```

--------------------------------

### Build CLI

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Compiles the n8n-cli application. This is a necessary step before running the CLI during development or for deployment.

```bash
task build
```

--------------------------------

### Configure n8n CLI with Environment Variables

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Sets n8n API key and instance URL directly in the shell environment. These variables take precedence over .env file settings.

```bash
export N8N_API_KEY=your_n8n_api_key
export N8N_INSTANCE_URL=https://your-instance.n8n.cloud
```

--------------------------------

### Run n8n-cli Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/CONTRIBUTING.md

Execute unit tests, integration tests, or all tests using the provided 'task' commands. Ensure all tests pass before submitting changes.

```bash
task test-unit
```

```bash
task test-integration
```

```bash
task test
```

--------------------------------

### Show all nodes in n8n execution flow path

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Displays the complete node execution path without truncation. Use the --no-truncate flag.

```bash
n8n workflows executions --no-truncate
```

--------------------------------

### Run Integration Tests

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Executes integration tests for the project. This helps verify the interaction between different components.

```bash
task test-integration
```

--------------------------------

### List N8N Workflows

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Fetches and displays all workflows from the connected n8n instance. Supports table, JSON, and YAML output formats, and a configurable result limit. Short flags are available for output format and limit.

```bash
# List workflows in the default table format
n8n workflows list
# Output:
# ID              NAME                  ACTIVE
# abc123def456    Contact Form          Yes
# xyz789ghi012    Daily Report          No
```

```bash
# List workflows as JSON (useful for scripting)
n8n workflows list --output json
# [
#   { "id": "abc123def456", "name": "Contact Form", "active": true, ... },
#   { "id": "xyz789ghi012", "name": "Daily Report",  "active": false, ... }
# ]
```

```bash
# List workflows as YAML
n8n workflows list --output yaml
```

```bash
# Limit results to 50
n8n workflows list --limit 50
```

```bash
# Short flags
n8n workflows list -o json -l 25
```

--------------------------------

### List n8n Workflows

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Lists workflows from an n8n instance. Supports outputting in table, JSON, or YAML formats and setting a custom limit.

```bash
n8n workflows list
```

```bash
n8n workflows list --output json
```

```bash
n8n workflows list --output yaml
```

```bash
n8n workflows list --limit 50
```

--------------------------------

### Run n8n-cli Development Build

Source: https://github.com/edenreich/n8n-cli/blob/main/CONTRIBUTING.md

Use the 'task cli' command to run the CLI during development. Pass arguments after '--' to execute specific commands.

```bash
task cli -- <args>
```

```bash
task cli -- workflows list
```

--------------------------------

### n8n-cli Quick Reference Commands

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Commonly used n8n-cli commands for various tasks.

```bash
task help         # Show all available commands
```

```bash
task up           # Start local environment
```

```bash
task down         # Stop local environment
```

```bash
task sync         # Deploy workflows to n8n
```

```bash
task refresh      # Pull workflows from n8n
```

```bash
task list         # List all workflows
```

```bash
task executions   # View execution history
```

--------------------------------

### Deploy n8n Workflow Manually

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Provides commands for manually deploying n8n workflows using the Taskfile or directly with the n8n-cli. Includes a dry-run option to preview changes.

```bash
# Using Taskfile (recommended)
task sync

# Or using n8n-cli directly
n8n workflows sync --directory workflows/

# Preview changes without applying
task sync-dry-run
```

--------------------------------

### Refresh all n8n workflows

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Downloads all workflows from the n8n instance, including new ones. Ensure the target directory exists.

```bash
n8n workflows refresh --directory workflows/ --all
```

--------------------------------

### Configure n8n CLI with .env file

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Sets n8n API key and instance URL using a .env file. This file is automatically loaded by the CLI. Ensure sensitive credentials are not committed to version control.

```dotenv
N8N_API_KEY=your_n8n_api_key
N8N_INSTANCE_URL=https://your-instance.n8n.cloud
```

--------------------------------

### Minimal Workflow File (JSON)

Source: https://context7.com/edenreich/n8n-cli/llms.txt

A basic n8n workflow definition in JSON format. This can be created locally and synced to any n8n instance.

```json
{
  "id": "abc123def456",
  "name": "Contact Form",
  "active": true,
  "nodes": [
    {
      "id": "node-uuid-1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [250, 300],
      "parameters": {
        "path": "contact-form",
        "responseMode": "responseNode",
        "httpMethod": "POST"
      }
    },
    {
      "id": "node-uuid-2",
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend",
      "typeVersion": 2.1,
      "position": [500, 300],
      "parameters": {
        "toEmail": "admin@example.com",
        "subject": "New Contact Form Submission",
        "emailType": "text",
        "message": "={{ $json.name }} wrote: {{ $json.message }}"
      },
      "credentials": {
        "smtp": { "id": "cred-smtp-1", "name": "SMTP Account" }
      }
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{ "node": "Send Email", "type": "main", "index": 0 }]]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "tags": [
    { "name": "production" }
  ]
}
```

--------------------------------

### Basic n8n-cli Command

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

A simple command to list all active workflows in an n8n instance.

```bash
n8n workflows list --active
```

--------------------------------

### Generate Mocks and Interfaces

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Generate necessary mocks and interfaces for testing and dependency injection. This is part of the code generation process.

```bash
task generate          # Generate mocks and interfaces
```

--------------------------------

### `n8n.NewClient` — Programmatic API Client

Source: https://context7.com/edenreich/n8n-cli/llms.txt

The `n8n` package exposes a `Client` struct and a `ClientInterface` for direct programmatic use in Go programs, integration tests, or custom tooling built on top of the CLI.

```APIDOC
## `n8n.NewClient` — Programmatic API Client

The `n8n` package exposes a `Client` struct and a `ClientInterface` for direct programmatic use in Go programs, integration tests, or custom tooling built on top of the CLI.

```go
package main

import (
    "fmt"
    "log"

    "github.com/edenreich/n8n-cli/n8n"
)

func main() {
    // Create a client connected to your n8n instance
    client := n8n.NewClient("https://mycompany.n8n.cloud", "n8n_api_abc123xyz")

    // List all workflows (up to 250)
    limit := 250
    workflows, err := client.GetWorkflows(&limit)
    if err != nil {
        log.Fatalf("failed to list workflows: %v", err)
    }
    for _, wf := range *workflows.Data {
        fmt.Printf("ID: %s  Name: %s  Active: %v\n", *wf.Id, wf.Name, *wf.Active)
    }

    // Get a single workflow by ID
    wf, err := client.GetWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("workflow not found: %v", err)
    }
    fmt.Println("Fetched:", wf.Name)

    // Activate a workflow
    activated, err := client.ActivateWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("activation failed: %v", err)
    }
    fmt.Println("Activated:", activated.Name)

    // Deactivate a workflow
    _, err = client.DeactivateWorkflow("abc123def456")
    if err != nil {
        log.Fatalf("deactivation failed: %v", err)
    }

    // Create a new workflow from a struct
    newWf := &n8n.Workflow{
        Name: "My New Workflow",
        // ... populate Nodes, Connections, Settings
    }
    created, err := client.CreateWorkflow(newWf)
    if err != nil {
        log.Fatalf("create failed: %v", err)
    }
    fmt.Println("Created ID:", *created.Id)

    // Update an existing workflow
    updated, err := client.UpdateWorkflow("abc123def456", wf)
    if err != nil {
        log.Fatalf("update failed: %v", err)
    }
    fmt.Println("Updated:", *updated.Id)

    // Delete a workflow
    if err := client.DeleteWorkflow("abc123def456"); err != nil {
        log.Fatalf("delete failed: %v", err)
    }

    // Get execution history
    executions, err := client.GetExecutions("abc123def456", false, "error", 10, "")
    if err != nil {
        log.Fatalf("executions failed: %v", err)
    }
    fmt.Printf("Found %d failed executions\n", len(*executions.Data))

    // Manage tags
    tag, err := client.CreateTag("production")
    if err != nil {
        log.Fatalf("tag creation failed: %v", err)
    }
    tagIds := n8n.TagIds{{Id: *tag.Id}}
    _, err = client.UpdateWorkflowTags("abc123def456", tagIds)
    if err != nil {
        log.Fatalf("tag update failed: %v", err)
    }
}
```
```

--------------------------------

### Run Linter

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Perform code quality checks using golangci-lint. This task ensures code adheres to project standards.

```bash
# Code quality
task lint              # Run golangci-lint
```

--------------------------------

### Workflow File Format (JSON)

Source: https://context7.com/edenreich/n8n-cli/llms.txt

A minimal workflow file that can be created locally and synced to any n8n instance.

```APIDOC
## Workflow File Format (JSON)

A minimal workflow file that can be created locally and synced to any n8n instance.

```json
{
  "id": "abc123def456",
  "name": "Contact Form",
  "active": true,
  "nodes": [
    {
      "id": "node-uuid-1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [250, 300],
      "parameters": {
        "path": "contact-form",
        "responseMode": "responseNode",
        "httpMethod": "POST"
      }
    },
    {
      "id": "node-uuid-2",
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend",
      "typeVersion": 2.1,
      "position": [500, 300],
      "parameters": {
        "toEmail": "admin@example.com",
        "subject": "New Contact Form Submission",
        "emailType": "text",
        "message": "={{ $json.name }} wrote: {{ $json.message }}"
      },
      "credentials": {
        "smtp": { "id": "cred-smtp-1", "name": "SMTP Account" }
      }
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{ "node": "Send Email", "type": "main", "index": 0 }]]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "tags": [
    { "name": "production" }
  ]
}
```
```

--------------------------------

### Download n8n OpenAPI Specification

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Download the latest OpenAPI specification for the n8n API. This is a prerequisite for generating API client types.

```bash
# Download latest n8n OpenAPI spec
task oas-download
```

--------------------------------

### Detect Workflow Configuration Drift

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Compares two workflow structs to detect differences, useful for avoiding unnecessary API calls during synchronization. The comparison can be done with or without cleaning (stripping null/server fields).

```go
package main

import (
    "fmt"

    "github.com/edenreich/n8n-cli/cmd"
    "github.com/edenreich/n8n-cli/n8n"
)

func main() {
    client := n8n.NewClient("https://mycompany.n8n.cloud", "n8n_api_abc123xyz")

    remote, _ := client.GetWorkflow("abc123def456")

    decoder := n8n.NewWorkflowDecoder()
    localData := []byte(`{"id":"abc123def456","name":"Contact Form","nodes":[...]}`)
    local, _ := decoder.DecodeFromJSON(localData)

    // Compare with minimal=true (cleans both workflows before comparison)
    drifted := cmd.DetectWorkflowDrift(*remote, local, true)
    if drifted {
        fmt.Println("Local workflow differs from remote — update needed")
        updated, err := client.UpdateWorkflow(*remote.Id, &local)
        if err != nil {
            panic(err)
        }
        fmt.Println("Updated to:", *updated.Id)
    } else {
        fmt.Println("Workflows are in sync — no update needed")
    }
}

```

--------------------------------

### Test Webhook Directly with cURL

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Demonstrates how to send a POST request to an n8n webhook URL using `curl` to test its functionality with sample JSON data.

```bash
curl -X POST your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@example.com","message":"Hello"}'
```

--------------------------------

### GitHub Actions: Sync workflows to n8n

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Synchronizes local workflows to the n8n instance using GitHub Actions. Requires N8N_API_KEY and N8N_INSTANCE_URL secrets to be set.

```bash
n8n workflows sync --directory workflows/
```

--------------------------------

### Project Structure Overview

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

This tree displays the directory and file structure of the AI-enhanced contact form project, outlining the location of key components like the n8n workflow, CI/CD pipeline, and frontend form.

```tree
├── .github/
│   └── workflows/
│       └── sync-n8n.yml        # CI/CD pipeline for automatic n8n deployment
├── workflows/
│   └── Contact_Form_AI.yaml    # AI-enhanced n8n workflow (webhook → AI → email)
├── docker-compose.yaml         # Local development environment setup
├── .env.example                # Environment variable template
├── .gitignore                  # Version control exclusions
├── contact-form-ai.html        # Frontend form with AI features
├── Taskfile.yaml               # Development automation commands
└── README.md                   # Project documentation
```

--------------------------------

### Minimal Workflow File (YAML)

Source: https://context7.com/edenreich/n8n-cli/llms.txt

The same n8n workflow definition expressed in YAML format, which is preferred for readability and version control diffs.

```yaml
# workflows/Contact_Form.yaml
---
id: abc123def456
name: Contact Form
active: true
nodes:
  - id: node-uuid-1
    name: Webhook
    type: n8n-nodes-base.webhook
    typeVersion: 2
    position:
      - 250
      - 300
    parameters:
      path: contact-form
      responseMode: responseNode
      httpMethod: POST
  - id: node-uuid-2
    name: Send Email
    type: n8n-nodes-base.emailSend
    typeVersion: 2.1
    position:
      - 500
      - 300
    parameters:
      toEmail: admin@example.com
      subject: New Contact Form Submission
      emailType: text
      message: "={{ $json.name }} wrote: {{ $json.message }}"
    credentials:
      smtp:
        id: cred-smtp-1
        name: SMTP Account
connections:
  Webhook:
    main:
      - - node: Send Email
          type: main
          index: 0
settings:
  executionOrder: v1
tags:
  - name: production

```

--------------------------------

### Workflow Management Commands

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Commands for synchronizing, monitoring, and managing n8n workflows.

```bash
# Synchronization
task sync           # Deploy workflows
task sync-dry-run   # Preview changes
task refresh        # Download workflows
task refresh-all    # Download all workflows

# Monitoring
task list           # List workflows with status
task executions     # View execution history

# Set limit for workflows returned
n8n workflows list --limit 50   # Return up to 50 workflows
n8n workflows list -l 25        # Short form
```

--------------------------------

### Run CLI during development

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Execute the CLI tool during development using the 'task cli' command. Pass arguments after '--'.

```bash
# Run CLI during development
task cli -- <args>
```

--------------------------------

### Paginate n8n workflow executions

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Retrieves workflow executions in pages using a cursor for navigation. Use --limit to set page size and the provided cursor for subsequent pages.

```bash
n8n workflows executions --limit 10
n8n workflows executions --limit 10 --cursor eyJpZCI6MTAzMH0=
```

--------------------------------

### AI Model Configuration Options

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Select different AI models within the Groq node configuration. The default is 'mixtral-8x7b-32768'.

```javascript
// Available models:
- mixtral-8x7b-32768 (default, balanced)
- llama2-70b-4096 (more creative)
- gemma-7b-it (faster, lighter)
```

--------------------------------

### Debugging Commands for n8n Services

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Use these commands to check logs, view recent executions, and restart services for debugging purposes.

```bash
# Check n8n logs
task logs

# Check mailhog logs
task logs-mail

# View recent workflow executions
task executions

# Restart services if needed
task restart
```

--------------------------------

### Lint OpenAPI Specification

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Lint the n8n OpenAPI specification file to ensure it conforms to standards and is free of errors.

```bash
# Lint OpenAPI specification
task oas-lint
```

--------------------------------

### Workflow File Format (YAML)

Source: https://context7.com/edenreich/n8n-cli/llms.txt

The same workflow expressed as YAML — preferred for readability and version control diffs.

```APIDOC
## Workflow File Format (YAML)

The same workflow expressed as YAML — preferred for readability and version control diffs.

```yaml
# workflows/Contact_Form.yaml
---
id: abc123def456
name: Contact Form
active: true
nodes:
  - id: node-uuid-1
    name: Webhook
    type: n8n-nodes-base.webhook
    typeVersion: 2
    position:
      - 250
      - 300
    parameters:
      path: contact-form
      responseMode: responseNode
      httpMethod: POST
  - id: node-uuid-2
    name: Send Email
    type: n8n-nodes-base.emailSend
    typeVersion: 2.1
    position:
      - 500
      - 300
    parameters:
      toEmail: admin@example.com
      subject: New Contact Form Submission
      emailType: text
      message: "={{ $json.name }} wrote: {{ $json.message }}"
    credentials:
      smtp:
        id: cred-smtp-1
        name: SMTP Account
connections:
  Webhook:
    main:
      - - node: Send Email
          type: main
          index: 0
settings:
  executionOrder: v1
tags:
  - name: production
```
```

--------------------------------

### Enable Shell Autocompletion

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Enables command-line autocompletion for bash, zsh, or fish shells. Add to your shell's configuration file for permanent activation.

```bash
source <(n8n completion bash) # for bash
```

```bash
source <(n8n completion zsh)  # for zsh
```

```bash
source <(n8n completion fish) # for fish
```

--------------------------------

### Configure N8N CLI Credentials

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Configures n8n CLI credentials using a .env file, environment variables, or CLI flags. Environment variables take precedence over .env file values. Debug logging can be enabled by setting the DEBUG environment variable.

```bash
# .env file (auto-loaded from current directory)
N8N_API_KEY=your_n8n_api_key
N8N_INSTANCE_URL=https://your-instance.n8n.cloud
```

```bash
# Or export directly in shell (takes precedence over .env)
export N8N_API_KEY=n8n_api_abc123xyz
export N8N_INSTANCE_URL=https://mycompany.n8n.cloud
```

```bash
# Or pass per-command using flags
n8n --api-key n8n_api_abc123xyz --url https://mycompany.n8n.cloud workflows list
```

```bash
# Enable debug logging
export DEBUG=true
n8n workflows list
```

--------------------------------

### Output raw JSON response for n8n executions

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Retrieves the raw JSON response for workflow executions without any formatting. Use the --raw flag.

```bash
n8n workflows executions --raw
```

--------------------------------

### Update Branch and Push Changes

Source: https://github.com/edenreich/n8n-cli/blob/main/CONTRIBUTING.md

Before creating a pull request, rebase your branch onto the latest upstream changes and ensure all tests and linting pass. Then, push your branch to your fork.

```bash
git fetch upstream
git rebase upstream/main
task lint
task test
git push origin feature/your-feature-name
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/edenreich/n8n-cli/blob/main/CONTRIBUTING.md

Before making changes, create a new branch for your feature or bugfix to keep your work organized.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Production Email Configuration (Gmail)

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Configuration settings for sending emails via Gmail in a production environment. Use an app-specific password for security.

```yaml
SMTP Host: smtp.gmail.com
Port: 587
User: your-email@gmail.com
Password: App-specific password (not regular password)
SSL/TLS: STARTTLS
```

--------------------------------

### Sync Local Workflows to n8n

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Synchronizes local JSON/YAML workflows to an n8n instance. Handles workflow IDs to ensure consistency across environments. Use `--directory` to specify the local workflow source.

```bash
n8n workflows sync --directory workflows/
```

```bash
# Test without making changes
n8n workflows sync --directory workflows/ --dry-run
```

```bash
# Sync workflows and remove any remote workflows not in the local directory
n8n workflows sync --directory workflows/ --prune
```

```bash
# Sync workflows and refresh as JSON (overrides existing format)
n8n workflows sync --directory workflows/ --output json
```

```bash
# Sync workflows and refresh all workflows from n8n instance (including ones not in local directory)
n8n workflows sync --directory workflows/ --all
```

```bash
# Sync workflows without refreshing the local state afterward
n8n workflows sync --directory workflows/ --refresh=false
```

--------------------------------

### Run CLI During Development

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Executes the n8n-cli during development, allowing you to pass arguments directly to the CLI commands.

```bash
task cli -- workflows list
```

--------------------------------

### Run Linting

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Applies linting rules to the codebase to enforce coding standards and identify potential issues.

```bash
task lint
```

--------------------------------

### View Service Status

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form-ai/README.md

Command to check the status of Docker services.

```bash
# Check service status
docker-compose ps
```

--------------------------------

### Refresh n8n workflows to YAML output

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Refreshes workflows and saves them in YAML format instead of the default JSON. Specify the output format using --output.

```bash
n8n workflows refresh --directory workflows/ --output yaml
```

--------------------------------

### Refresh Local Workflows

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Refreshes local workflow files to match the current state of an n8n instance. Essential before syncing to prevent accidental data loss. Use `--directory` to specify the local storage location.

```bash
n8n workflows refresh --directory workflows/
```

```bash
# Refresh only existing workflows in the directory
n8n workflows refresh --directory workflows/
```

```bash
# Refresh all workflows from n8n instance (including new ones)
n8n workflows refresh --directory workflows/ --all
```

```bash
# Preview what would be refreshed without making changes
n8n workflows refresh --directory workflows/ --dry-run
```

```bash
# Refresh workflows and save them as YAML files
n8n workflows refresh --directory workflows/ --output yaml
```

```bash
# Refresh workflows without minimizing the JSON/YAML output
n8n workflows refresh --directory workflows/ --no-truncate
```

--------------------------------

### Generate Go Types from OpenAPI Spec

Source: https://github.com/edenreich/n8n-cli/blob/main/CLAUDE.md

Generate Go types from the downloaded OpenAPI specification. This ensures the Go client is up-to-date with the n8n API.

```bash
# Generate Go types from OpenAPI spec
task oas-generate
```

--------------------------------

### Production Email Configuration (SendGrid)

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Configuration settings for sending emails via SendGrid in a production environment. Use your SendGrid API key as the password.

```yaml
SMTP Host: smtp.sendgrid.net
Port: 587
User: apikey
Password: Your SendGrid API key
```

--------------------------------

### Docker Debug Commands

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Commands to check Docker service status, view n8n logs, and test n8n API connection.

```bash
# Check if services are running
docker compose ps

# View detailed logs
docker compose logs -f n8n

# Test n8n API connection
curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
  $N8N_INSTANCE_URL/api/v1/workflows
```

```bash
# Check webhook directly
curl -X POST your-webhook-url \
  -H "Content-Type: application/json" \
  -d '{"test": true}'
```

--------------------------------

### Sync Local Workflows to N8N

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Pushes local JSON/YAML workflow files to the n8n instance. Updates existing workflows by ID, creates new ones, and can optionally prune remote workflows not present locally. A dry-run option previews changes. Local files can be refreshed with server state after sync, and output can be converted to YAML.

```bash
# Basic sync: push all workflow files in ./workflows/ to n8n
n8n workflows sync --directory workflows/
```

```bash
# Preview changes without making them (dry run)
n8n workflows sync --directory workflows/ --dry-run
# Output:
# Syncing workflows...
# Would update workflow 'Contact Form' (ID: abc123def456) from Contact_Form.yaml
# Would create workflow 'New Onboarding' from Onboarding.yaml
```

```bash
# Sync and delete remote workflows not present locally (prune)
n8n workflows sync --directory workflows/ --prune
```

```bash
# Sync without refreshing local files afterward
n8n workflows sync --directory workflows/ --refresh=false
```

```bash
# Sync and convert refreshed files to YAML format
n8n workflows sync --directory workflows/ --output yaml
```

```bash
# Sync and refresh all remote workflows (not just those in the directory)
n8n workflows sync --directory workflows/ --all
```

```bash
# CI/CD pipeline pattern: validate then deploy
n8n workflows sync --directory workflows/ --dry-run && \
n8n workflows sync --directory workflows/
```

--------------------------------

### Activate Workflow by ID

Source: https://github.com/edenreich/n8n-cli/blob/main/README.md

Activates a specific workflow in the n8n instance using its unique ID, making it ready for triggering.

```bash
n8n workflows activate WORKFLOW_ID
```

--------------------------------

### Overwrite existing n8n workflow files

Source: https://context7.com/edenreich/n8n-cli/llms.txt

Forces overwriting of existing workflow files, even if they have different names. Use the --overwrite flag.

```bash
n8n workflows refresh --directory workflows/ --overwrite
```

--------------------------------

### Update Webhook URL in HTML Form

Source: https://github.com/edenreich/n8n-cli/blob/main/examples/contact-form/README.md

Illustrates how to update the placeholder webhook URL in an HTML form file using the `sed` command.

```bash
# Update the webhook URL in the HTML form
sed -i 's|YOUR_N8N_WEBHOOK_URL_HERE|your-actual-webhook-url|g' contact-form.html
```