# n8n Debugger

AI-native debugging toolkit for n8n workflows. Works for both self-hosted and cloud n8n instances.

> **Note:** This is a third-party debugging tool, not affiliated with n8n.io. For official n8n CLI commands, see [n8n CLI documentation](https://docs.n8n.io/hosting/cli-commands/).

## Installation

```bash
npm install -g @seibert/n8n-debugger
```

## Setup

```bash
# Create a project directory
mkdir my-n8n-project && cd my-n8n-project

# Initialize (creates .env template and copies agent guidelines)
n8n-debug init

# Edit .env with your credentials, then test
n8n-debug list
```

The tool creates `workflows/` and `executions/` directories in your current working directory.

## AI Agent Mode

Designed for autonomous AI debugging. When you describe a workflow problem to an AI assistant, it can:

1. Search for workflows by name
2. Check health and assess error patterns
3. Analyze recent errors with structured data
4. Pull and edit workflow JSON to fix issues
5. Validate and push changes back to n8n
6. Retry failed executions to verify fixes
7. Manage workflows (activate/deactivate, compare versions)

## Commands

```
Usage:
  n8n-debug init                                    Initialize directory with guidelines and .env template
  n8n-debug list                                    List all workflows
  n8n-debug search <term>                           Search workflows by name
  n8n-debug errors <workflow-id> [limit]            Show recent errors for a workflow
  n8n-debug health <workflow-id>                    Check workflow health and execution stats
  n8n-debug validate <file.json>                    Validate workflow JSON before pushing
  n8n-debug activate <id> [<id> ...]                Activate one or more workflows
  n8n-debug deactivate <id> [<id> ...]              Deactivate one or more workflows
  n8n-debug diff <id1> <id2>                        Compare two workflows and show differences
  n8n-debug compare-executions <wf-id> <ok> <fail>  Compare successful vs failed executions
  n8n-debug retry <execution-id> [--load-workflow]  Retry a failed execution
  n8n-debug pull [workflow-id|all]                  Pull workflow(s) to local JSON files
  n8n-debug pull-executions <id> [limit]            Pull execution data for a workflow
  n8n-debug push <file.json>                        Push local workflow changes to n8n
  n8n-debug clean [all|workflows|executions]        Remove downloaded files
  n8n-debug help                                    Show help

Flags:
  --json                                            Output in JSON format (for agent use)

Examples:
  n8n-debug search "Todoist"
  n8n-debug errors mp3KdoJFgCDT5ktt --json
  n8n-debug validate workflows/mp3KdoJFgCDT5ktt_Workflow.json
  n8n-debug activate mp3KdoJFgCDT5ktt
  n8n-debug deactivate mp3KdoJFgCDT5ktt abc123def
  n8n-debug compare-executions mp3KdoJFgCDT5ktt 437776 440301
  n8n-debug retry 440301                            # Retry with original workflow
  n8n-debug retry 440301 --load-workflow            # Retry with latest workflow version
```

## Workflow Development

```bash
n8n-debug search "My Workflow"     # Find the workflow
n8n-debug errors <workflow-id>      # See what's failing
n8n-debug pull <workflow-id>        # Get the workflow
# ... edit the JSON ...
n8n-debug validate <file>           # Check it's valid
n8n-debug push <file>              # Deploy the fix
```

**Note:** Only core workflow fields can be updated via push:

- `name` - Workflow name
- `nodes` - Workflow nodes and their configuration
- `connections` - Node connections
- `settings` - Workflow settings
- `staticData` - Static workflow data

Read-only fields (like `active`, `tags`, timestamps) are filtered out and must be changed in the n8n UI.

## Security Notes

`workflows/` and especially `executions/` can include production data, credentials and PII from n8n runs. Treat those folders as sensitive artifacts and avoid syncing or uploading them to shared repos or cloud storage unless they are scrubbed.