sc-n8n · diff
git:20260802.01d4ada to git:20260902.cfd6b22
59 added, 63 removed. Audit A to A.
---
name: sc-n8n
- description: "Drive the self-hosted n8n instance (https://n8n.rahmanef.com) from the CLI via @n8n/cli. List/inspect/create/update/activate workflows, check executions, manage credentials, projects, tags, variables, data-tables, and export/import packages — all over the n8n public API with an API key. Trigger on /sc-n8n, 'n8n workflow', 'n8n cli', 'list n8n workflows', 'create n8n workflow', 'n8n executions', 'n8n credential', 'connect n8n', 'self-hosted n8n'."
+ description: "Drive a user-configured self-hosted or cloud n8n instance through the official @n8n/cli. List, inspect, create, update, activate, and verify workflows; inspect executions; manage projects, tags, variables, data tables, and packages without assuming a specific server, deployment platform, or account."
+ use_when: "Use for n8n workflow, execution, project, variable, data-table, package, CLI connection, or self-hosted n8n administration tasks."
+ do_not_use_when: "Do not use when the task is outside n8n or when SI-Coder does not have an explicitly configured n8n endpoint/account for the requested operation."
+ required_tools: ["n8n-cli"]
+ security_constraints: "Never request, print, or persist an n8n API key in chat/tool payloads. Resolve access from SI-Coder's selected user/connection or another explicitly secure local credential channel."
+ references: []
+ compatibility: "Standalone SI-Coder; supports any n8n instance compatible with the configured CLI/public API."
---
- # /sc-n8n — self-hosted n8n control via @n8n/cli
+ # sc-n8n — n8n control via @n8n/cli
- Drive **n8n.rahmanef.com** (self-hosted, Dokploy) from CLI. Wrapper around the official
- `@n8n/cli` binary (`n8n-cli`). No reinvented scripts — the binary is the engine.
+ Use the official `@n8n/cli` binary (`n8n-cli`) against the **user-selected n8n instance**. Do not assume a fixed hostname, backup location, deployment platform, shell profile, project, or workflow set.
- ## Instance
+ ## Required connection state
- | Thing | Value |
+ | Setting | Purpose |
|---|---|
- | URL | `https://n8n.rahmanef.com` |
- | Health | `curl https://n8n.rahmanef.com/healthz` → `{"status":"ok"}` |
- | API key | env `N8N_API_KEY` (`~/.bashrc` line 6) — public-api JWT, no `exp` |
- | CLI config | `~/.n8n-cli/config.json` (`0600`); URL already set |
- | Backups | `~/backups/n8n/` — `n8n-db-YYYY-MM-DD.sql` + `n8n-workflows-*.json` |
- | SSH deploy key | `~/.ssh/id_n8n` |
+ | `N8N_URL` | Base URL of the selected n8n instance, for example `https://n8n.example.com` |
+ | `N8N_API_KEY` | Public API key for that instance; keep it in the selected SI-Coder credential store or another secure local source |
+ | `~/.n8n-cli/config.json` | Optional CLI-local configuration; never treat it as the only possible source of truth |
- Binary: `~/.local/bin/n8n-cli` (`npm i -g @n8n/cli`; or zero-install `npx @n8n/cli ...`).
+ Install the binary only when needed:
- ## Auth resolution order
+ ```bash
+ npm i -g @n8n/cli
+ # or use: npx @n8n/cli ...
+ ```
- 1. flags `--url` / `--api-key`
- 2. env `N8N_URL` / `N8N_API_KEY` ← **wins over config file**
- 3. `~/.n8n-cli/config.json`
+ ## Auth resolution
- ⚠️ **GOTCHA: env key overrides config key.** `N8N_API_KEY` is exported in `~/.bashrc`.
- Setting a new key via `n8n-cli config set-api-key` is **silently ignored** in any shell that
- sourced `.bashrc`. To rotate → edit `~/.bashrc` line 6, not the config file.
+ When diagnosing which account/instance is active, inspect explicit CLI flags first, then environment variables, then CLI config. Environment variables can override a value saved in the CLI config, so a newly written config value may appear ignored when an older environment variable is still present.
- ⚠️ **`invalid signature (401)` = dead key, not wrong header.** n8n signs public-api keys with
- `N8N_USER_MANAGEMENT_JWT_SECRET`. Redeploy that regenerates the secret kills every existing key.
- Fix = regenerate in **n8n → Settings → n8n API → Create an API key**, then replace `.bashrc` line 6.
- (The `~/backups/n8n/*.sql` dump holds only expired `mcp-server-api` OAuth tokens — no recoverable
- public-api key.)
+ If the API returns `401` or an invalid-signature error, do not guess that the header format is wrong. Verify the selected instance/account, then create or rotate an API key from the official n8n UI and store it through the safe SI-Coder credential handoff. Never print the key during verification.
## Connect / verify
```bash
- n8n-cli config show # URL + whether key set
- n8n-cli workflow list --format=id-only # smoke test; 401 => rotate key (above)
+ n8n-cli config show
+ n8n-cli workflow list --format=id-only
```
+ A successful read-only workflow listing is the preferred smoke check before mutations.
+
## Command surface
- Every command supports `--help`. Formats: `--format=table|json|id-only`.
+ Every command supports `--help`. Common output formats are `table`, `json`, and `id-only` when supported by the installed CLI version.
- | Topic | Commands |
+ | Topic | Typical commands |
|---|---|
| `workflow` | list · get · create · update · delete · activate · deactivate · tags · transfer |
| `execution` | list · get · retry · stop · delete |
| `credential` | list · get · schema · create · delete · transfer |
- | `project` | list · get · create · update · delete · members · add-member · remove-member |
+ | `project` | list · get · create · update · delete · members |
| `tag` | list · create · update · delete |
| `variable` | list · create · update · delete |
- | `data-table` | list · get · create · delete · rows · add-rows · update-rows · upsert-rows · delete-rows |
+ | `data-table` | list · get · create · delete · rows operations |
| `user` | list · get |
| `config` | set-url · set-api-key · show |
| `source-control` | pull |
- | `package` (beta) | export · import |
- | `audit` · `login` · `logout` · `skill` | top-level |
+ | `package` | export · import when supported by the installed CLI |
+ | `audit` / auth | inspect with `--help` because availability can vary by CLI version |
- ## Recipes
+ ## Safe recipes
```bash
- # inspect
+ # inspect before changing
n8n-cli workflow list
n8n-cli workflow get <id> --format=json
- # only-active workflow ids
- n8n-cli workflow list --format=json | jq -r '.[] | select(.active) | .id'
-
- # create from JSON (backup format works)
- cat workflow.json | n8n-cli workflow create --stdin
-
# recent failures
n8n-cli execution list --status=error --limit=10
- # credential — see fields first, then create
- n8n-cli credential schema gmailOAuth2
- n8n-cli credential create --type=gmailOAuth2 --name='My Gmail' --file=cred.json
+ # create from reviewed JSON
+ cat workflow.json | n8n-cli workflow create --stdin
- # projects
- n8n-cli project create --name="My Project"
- n8n-cli workflow transfer <id> --project=<projectId>
+ # inspect a credential schema before creating metadata
+ n8n-cli credential schema <credentialType>
- # package (beta) — portable bundle w/ deps
+ # portable workflow package when supported
n8n-cli package export --workflow-id=<id> --output=export.n8np
- n8n-cli package import --file=export.n8np --conflict-policy=fail
-
- # bulk deactivate everything
- n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}
```
- ## Backup / restore this instance
+ ## Backup / restore policy
- - Workflows snapshot lives at `~/backups/n8n/n8n-workflows-*.json` (array of workflow objects).
- - Re-import one: `jq -c '.[N]' n8n-workflows-*.json | n8n-cli workflow create --stdin`.
- - Full DB restore = `~/backups/n8n/*.sql` against the Postgres behind Dokploy (server-side, not this CLI).
+ Do not assume backups live in a particular directory or that n8n is deployed with a particular provider. Before a destructive or broad workflow change:
+ 1. identify the selected n8n instance;
+ 2. inspect the affected workflow/project IDs;
+ 3. export the relevant workflow/package when the CLI supports it, or use the deployment provider's existing backup mechanism;
+ 4. record an Evidence Receipt for high-risk changes;
+ 5. verify the workflow after the mutation.
+
## Rules
- 1. **Never delete workflows/executions without `--dry-run` first** where the subcommand offers it, else confirm the id.
- 2. **Beta CLI** — experiments/personal only, not prod-critical automation (n8n's own caveat).
- 3. **Key rotation edits `.bashrc` line 6**, not `config.json` (env overrides — see GOTCHA).
- 4. **Webhooks are live prod** — `n8n.rahmanef.com/webhook/*` feed convex-backup, dual-sync, openclaw-sync, rqa-broadcast. Don't deactivate their workflows casually.
+ 1. Read before write; use dry-run functionality when the installed subcommand provides it.
+ 2. Require explicit confirmation for delete, bulk deactivate, transfer, or other destructive/broad operations.
+ 3. Never bulk-edit workflows based on names alone when IDs can disambiguate them.
+ 4. Never assume production webhooks, workflows, projects, credentials, URLs, or backup paths from repository documentation.
+ 5. Treat CLI capabilities as version-dependent; check `n8n-cli <command> --help` when behavior matters.
+ 6. Keep credentials outside memory, evidence, recipes, logs, and tool payloads.
- ## Linked skills
- - `[[sc-dokploy]]` — the n8n app + Postgres run on Dokploy; restart/redeploy there.
- - `[[sc-git]]` — cron/webhook replacement patterns overlap with n8n triggers.
+ ## Linked SI-Coder skills
+
+ - `sc-dokploy` may be used when the **user-selected** n8n deployment actually runs on Dokploy.
+ - `sc-git` may help when a workflow is intentionally replaced by a repository-native automation.
+
+ These are optional internal SI-Coder capabilities, not external project dependencies.