Configuration

decanter.config.json is searched upward from the current directory; credentials come from .env / .decanter-auth.json next to it or from the environment.

{
  "root": "./workflows",
  "workflows": ["0cXNQKKzmO0pXiCq"],
  "commitOnPush": true,
  "commitOnPull": true,
  "requestTimeoutMs": 30000,
  "n8nVersion": "2.31.4",
  "dataTables": true,
  "liveMirror": true,
  "backupLimit": 20,
  "bundleDependencies": ["zod"]
}

Key	Default	Meaning
`root`	—	Directory holding the workflow folders.
`workflows`	`[]`	Workflow ids processed when a command gets no refs.
`commitOnPush`	`true`	Auto-commit the workflow folder after a successful push.
`commitOnPull`	`true`	Same for pull.
`requestTimeoutMs`	`30000`	Request timeout (MCP and API) — raise for slow instances.
`n8nVersion`	unset	n8n version the local engine behind `preflight --simulate` pins to (e.g. `"2.31.4"`); `--n8n-version` overrides it per run. Unset falls back to the project’s default with a hint.
`dataTables`	`true`	Whether the read-only data-tables fetch is available. `false` refuses it (and the API key needn’t carry the data-table read scopes); `data-tables clean` still works.
`liveMirror`	`true`	Refresh the read-only `workflow.json` snapshot in the background after an agent restructures a workflow through the guard (a forwarded `update_workflow`). `false` disables the auto-refresh (CI / deterministic setups).
`backupLimit`	`20`	Cap on the retained `backups/` working set per workflow. Each `backup create` rolling-prunes the oldest beyond this; `0` keeps all (git holds the full history regardless).
`bundleDependencies`	`[]`	npm packages `.ts` nodes may import; bundled on push. Pure-JS only.

Credentials

The sync rides n8n’s MCP server; the public API key is an optional extra. In order of resolution:

N8N_HOST — always required for online verbs (.env or environment).
MCP credentials (the sync verbs — pull, push, diff, watch, publish, unpublish, test, and preflight without --offline — plus the mcp connect/mcp serve guard):
- N8N_MCP_TOKEN (.env or environment) — a rotatable token from n8n → Settings → MCP → API key. Takes precedence when set.
- Otherwise .decanter-auth.json — the OAuth client id + refresh token init minted via browser consent. The refresh token rotates on every use; the file is rewritten automatically. Delete it and re-run init to re-consent (also the fix for a “MCP session expired” error).
N8N_API_KEY (optional) — only for the verbs MCP cannot serve: executions, data-tables, and backup. Scope it minimally: execution:read, execution:list, workflow:list (init’s connection check), the dataTable:* read scopes (only while dataTables is on), and workflow:read + workflow:create (only for backup create/restore’s full-fidelity GET/POST).

The instance needs MCP access enabled once (n8n → Settings → MCP; requires an n8n with the built-in MCP server, ~2.20+), and each synced workflow needs its “Available in MCP” flag (workflow card ⋯ menu, or workflow settings) — list —remote and the picker show which workflows still need it.

preflight --offline, node run, scenario check, and plain list need no credentials at all (scenario create --scaffold is the exception — it needs MCP).