# valn8n

A validator for [n8n](https://n8n.io/) workflow JSON files. Like `ruff` for Python, but for your n8n workflows.

Checks for errors, warning, and hints regarding syntax and semantics of workflows. Output in different formats (rich in terminal, text, JSON, CSV), most LLMs seem to work with 'text' quite well (tightly followed by JSON, but more tokens).

Also, `valn8n` allows me to asses the quality or hidden traps of workflows downloaded from the web, saving a lot of time not bothering with sometimes totally broken workflows.

## Background

I have been testing n8n on and off with LLM assisted workflow generation and couldn't find a n8n workflow validator that would find whatever silly mistake an LLM (even flagship ones) could sometimes generate.

With `valn8n` however I can have the LLMs autocorrect those errors and am getting most n8n workflows as one-shot.

## Requirements

- Python >= 3.13
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package and project manager

## Installation

```bash
uv tool install valn8n
```

## Quick Start

```bash
valn8n check my_workflow.json
valn8n check --strict-only my_workflow.json
```

See also README in supplied demo workflows in `demo_valn8n/broken_vs_notbroken`.

## Usage

### Check a single file

```bash
valn8n check workflow.json
```

### Check a directory

```bash
valn8n check workflows/
```

### Select specific rules

Only check rules ND01xx and ND05xx.

```bash
valn8n check --select ND01,ND05 workflow.json
```

### Ignore specific rules

Ignore ND05xx and ND0802.

```bash
valn8n check --ignore ND05,ND0802 workflow.json
```

### Switching back on ignored rules

Ignore ND05xx but not ND0502.

```bash
valn8n check --ignore ND05 --extend-select ND0502 workflow.json
```

### Strict-only mode

Run only strict rules, skipping advisory and hint rules:

```bash
valn8n check --strict-only workflow.json
```

### JSON output (for CI)

```bash
valn8n check --fmt json workflow.json
```

### Quiet mode (summary only)

```bash
valn8n check -q workflow.json
```

### Tolerate unknown node keys

```bash
valn8n check --tolerate-node-keys '*' workflow.json
```

### List all rules

```bash
valn8n rule
```

## Output Formats

| Format | Flag | Description |
|--------|------|-------------|
| Rich | `--fmt rich` | Colored terminal output (default) |
| Text | `--fmt text` | Plain text |
| JSON | `--fmt json` | Machine-readable JSON |
| CSV | `--fmt csv` | Comma-separated values |
| List | `--fmt lst` | One diagnostic per line |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | No violations found |
| 1 | Violations found |
| 2 | Error (e.g. file not found, invalid arguments) |

## Rules

| Group | Range | Description |
|-------|-------|-------------|
| IO | IO00xx | File I/O validation (read errors, invalid JSON) |
| ND01 | ND01xx | Filter operations (invalid ops, common mistakes) |
| ND02 | ND02xx | Node structure (unknown keys, value types, zero-property params) |
| ND03 | ND03xx | Parameter validation (deep param keys, param value types) |
| ND04 | ND04xx | Expression syntax (broken brackets, suspect prefixes) |
| ND05 | ND05xx | Credential validation (missing, empty, placeholder, leaking) |
| ND06 | ND06xx | Connection validation (unconnected inputs, dangling refs) |
| ND07 | ND07xx | Error handling (missing errorWorkflow, unhandled errors) |
| ND08 | ND08xx | Naming & documentation (default names, missing notes) |

Rules ND01xx-ND04xx and ND06xx are **strict** (structural correctness). ND05xx and 07xx are **advisory** (best practices). ND08xx are **hints** (atm only regarding naming clarity and documentation).

Note: in future this may change and strict/advisory might not be clean ranges anymore.

Use `--strict-only` to run only strict rules.

Run `valn8n rule` to see the full list with descriptions.

## Contributing

I do not accept PRs with code changes at the moment. But feel free to post issues (with full workflows attached) in case you think there is an error in valn8n, or if you see an opportunity to improve it.
