From 2ac6e710ddee88961a8d36b1bd3a189ea469a5db Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 13:09:48 +0200 Subject: [PATCH 1/7] docs: document n8nctl version, data table, and admin commands --- lib/llm/index.js | 52 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index fec8d0c..653dc0b 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -588,7 +588,7 @@ The \`--body\` flag replaces the whole page content; pass \`--append\` to add to n8nctl: { filename: 'cli-n8nctl.md', name: 'n8nctl', - purpose: 'n8n workflow management, execution, variables, and source control', + purpose: 'n8n workflows, versions, executions, data tables, variables, and source control', content: `## n8n Workflow CLI (n8nctl) CLI for managing n8n workflows - pull/push for version control, execute workflows, and manage multiple instances. @@ -641,6 +641,23 @@ n8nctl workflow deactivate n8nctl workflow transfer \`\`\` +### Workflow versions and publishing + +n8n keeps a draft (\`versionId\`) and a published version (\`activeVersionId\`). \`workflow view\` shows both and whether the draft has unpublished changes. + +\`\`\`bash +n8nctl workflow history # Saved versions, newest first +n8nctl workflow version # One saved version as JSON +n8nctl workflow publish # Publish the current draft +n8nctl workflow publish --version # Publish / roll back to a specific version +n8nctl workflow unpublish +n8nctl workflow archive # Soft delete (unpublishes) +n8nctl workflow unarchive +n8nctl workflow delete # Permanent; archive or unpublish first +\`\`\` + +- \`workflow push\` to a published workflow publishes the new version immediately. + ### Projects \`\`\`bash @@ -670,6 +687,8 @@ n8nctl execution list --resolve-names # Show workflow names (slower) n8nctl execution view # View execution details n8nctl execution retry # Retry failed execution n8nctl execution delete # Delete execution +n8nctl execution stop # Stop a running/waiting execution +n8nctl execution stop --status running,waiting --workflow # Bulk stop \`\`\` ### Source control (instance Git connection) @@ -690,10 +709,39 @@ n8nctl source-control pull --force # Discard conflicting local changes - A 409 lists the conflicting items; check them before rerunning with \`--force\`. - 403 means the API key lacks \`sourceControl:read\` / \`sourceControl:push\` / \`sourceControl:pull\`, or source control is not connected. +### Data tables + +\`\`\`bash +n8nctl dt list # Data tables (alias of datatable) +n8nctl dt view # Columns +n8nctl dt rows --where 'status=pending' --where 'n>=10' [--or] [--sort n:desc] [--search x] +n8nctl dt insert --data '{"k":"a"}' # Object or array; --data - reads stdin +n8nctl dt update --where 'k=a' --data '{"status":"done"}' --dry-run +n8nctl dt upsert --where 'k=a' --data '{"k":"a","n":1}' +n8nctl dt delete-rows --where 'k=a' --dry-run +\`\`\` + +- \`--where\` operators: \`= != > >= < <= ~\` (\`~\` = case-insensitive LIKE, \`%\` wildcard); use \`--filter ''\` for typed values. +- Run writes with \`--dry-run\` first; date-column comparisons do not match stored UTC timestamps exactly. + +### Credentials, tags, folders, users, audit + +\`\`\`bash +n8nctl cred list / test / schema / delete +n8nctl tag list / create / rename / delete +n8nctl folder list|view|create|update|delete ... --project # delete without --transfer-to archives its workflows +n8nctl user list [--project ] / user view +n8nctl project member list +n8nctl project member add --role project:editor # changes access: confirm with the user first +n8nctl audit [--categories credentials,nodes] # Security audit JSON +\`\`\` + +- A 403 means the API key lacks the scope for that command (e.g. \`folder:list\`, \`dataTableRow:read\`). + ### Tips - Use \`--json\` flag on any command for JSON output (useful for scripting) -- Aliases: \`workflow\` → \`wf\`, \`execution\` → \`exec\`, \`variable\` → \`var\`, \`source-control\` → \`sc\` +- Aliases: \`workflow\` → \`wf\`, \`execution\` → \`exec\`, \`variable\` → \`var\`, \`source-control\` → \`sc\`, \`datatable\` → \`dt\`, \`credential\` → \`cred\` - Recursive pull creates \`manifest.json\` tracking workflow dependencies - Push with manifest handles sub-workflow ID remapping automatically `, From a96d76a97b9e2d6a3e15ff4dacb57c5ce551793d Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 13:16:53 +0200 Subject: [PATCH 2/7] docs: one runnable n8nctl command per line --- lib/llm/index.js | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index 653dc0b..fa32edf 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -714,7 +714,9 @@ n8nctl source-control pull --force # Discard conflicting local changes \`\`\`bash n8nctl dt list # Data tables (alias of datatable) n8nctl dt view # Columns -n8nctl dt rows --where 'status=pending' --where 'n>=10' [--or] [--sort n:desc] [--search x] +n8nctl dt rows --where 'status=pending' --where 'n>=10' --sort n:desc +n8nctl dt rows --where 'name~%inv%' --where 'name~%rech%' --or # --or: match any condition +n8nctl dt rows --search foo n8nctl dt insert --data '{"k":"a"}' # Object or array; --data - reads stdin n8nctl dt update --where 'k=a' --data '{"status":"done"}' --dry-run n8nctl dt upsert --where 'k=a' --data '{"k":"a","n":1}' @@ -727,13 +729,24 @@ n8nctl dt delete-rows --where 'k=a' --dry-run ### Credentials, tags, folders, users, audit \`\`\`bash -n8nctl cred list / test / schema / delete -n8nctl tag list / create / rename / delete -n8nctl folder list|view|create|update|delete ... --project # delete without --transfer-to archives its workflows -n8nctl user list [--project ] / user view +n8nctl cred list # ID, type, owning project (alias of credential) +n8nctl cred test # Exits non-zero when the test fails +n8nctl cred schema # JSON schema of a credential type +n8nctl cred delete +n8nctl tag list +n8nctl tag create +n8nctl tag rename +n8nctl tag delete +n8nctl folder list --project +n8nctl folder view --project +n8nctl folder create --project --parent +n8nctl folder update --project --name +n8nctl folder delete --project --transfer-to # without --transfer-to its workflows are archived +n8nctl user list --project # omit --project for all users +n8nctl user view n8nctl project member list n8nctl project member add --role project:editor # changes access: confirm with the user first -n8nctl audit [--categories credentials,nodes] # Security audit JSON +n8nctl audit --categories credentials,nodes # Security audit JSON; omit --categories for all \`\`\` - A 403 means the API key lacks the scope for that command (e.g. \`folder:list\`, \`dataTableRow:read\`). From 022b37ca2a125f1722bde7f444aa311219012e58 Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 14:44:48 +0200 Subject: [PATCH 3/7] docs: clearer n8nctl placeholders --- lib/llm/index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index fa32edf..dd9a787 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -649,7 +649,7 @@ n8n keeps a draft (\`versionId\`) and a published version (\`activeVersionId\`). n8nctl workflow history # Saved versions, newest first n8nctl workflow version # One saved version as JSON n8nctl workflow publish # Publish the current draft -n8nctl workflow publish --version # Publish / roll back to a specific version +n8nctl workflow publish --version # Publish / roll back to a specific version n8nctl workflow unpublish n8nctl workflow archive # Soft delete (unpublishes) n8nctl workflow unarchive @@ -741,7 +741,7 @@ n8nctl folder list --project n8nctl folder view --project n8nctl folder create --project --parent n8nctl folder update --project --name -n8nctl folder delete --project --transfer-to # without --transfer-to its workflows are archived +n8nctl folder delete --project --transfer-to # without --transfer-to its workflows are archived n8nctl user list --project # omit --project for all users n8nctl user view n8nctl project member list From bae50c53359127cab7bd4fee51b7da2f05f9e674 Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 15:04:22 +0200 Subject: [PATCH 4/7] docs: n8nctl safety rules for prod and clearer stdin note --- lib/llm/index.js | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index dd9a787..18173e1 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -717,7 +717,7 @@ n8nctl dt view # Columns n8nctl dt rows --where 'status=pending' --where 'n>=10' --sort n:desc n8nctl dt rows --where 'name~%inv%' --where 'name~%rech%' --or # --or: match any condition n8nctl dt rows --search foo -n8nctl dt insert --data '{"k":"a"}' # Object or array; --data - reads stdin +n8nctl dt insert --data '{"k":"a"}' # Object or array (use --data - to read stdin) n8nctl dt update --where 'k=a' --data '{"status":"done"}' --dry-run n8nctl dt upsert --where 'k=a' --data '{"k":"a","n":1}' n8nctl dt delete-rows --where 'k=a' --dry-run @@ -751,6 +751,13 @@ n8nctl audit --categories credentials,nodes # Security audit JSON; omit --cate - A 403 means the API key lacks the scope for that command (e.g. \`folder:list\`, \`dataTableRow:read\`). +### Safety Rules + +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +1. Check the active instance: \`n8nctl config list\` +2. Show the command and the target instance to the user +3. Ask for explicit confirmation before executing + ### Tips - Use \`--json\` flag on any command for JSON output (useful for scripting) @@ -1324,6 +1331,11 @@ ${rows} \`atl --context \`. Never rely on or mutate atl's shared persistent context from an agent session. +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +1. Check the active instance: \`n8nctl config list\` +2. Show the command and the target instance to the user +3. Ask for explicit confirmation before executing + **Safety**: Before executing any M365 write or delete operation (add, set, remove, copy, move): 1. Show the full command and target URL to the user 2. Ask for explicit confirmation before executing From c285f88f5a2050f7c0ee9679a99134500c717c10 Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 15:14:55 +0200 Subject: [PATCH 5/7] docs: n8nctl safety covers workflow push; document member set-role and remove --- lib/llm/index.js | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index 18173e1..e34fd2c 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -746,6 +746,8 @@ n8nctl user list --project # omit --project for all users n8nctl user view n8nctl project member list n8nctl project member add --role project:editor # changes access: confirm with the user first +n8nctl project member set-role project:viewer # role is positional +n8nctl project member remove n8nctl audit --categories credentials,nodes # Security audit JSON; omit --categories for all \`\`\` @@ -753,7 +755,7 @@ n8nctl audit --categories credentials,nodes # Security audit JSON; omit --cate ### Safety Rules -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing @@ -1331,7 +1333,7 @@ ${rows} \`atl --context \`. Never rely on or mutate atl's shared persistent context from an agent session. -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing From ce795d47c2877b6398e802cf1747278b1113aac8 Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 15:23:59 +0200 Subject: [PATCH 6/7] docs: n8nctl safety rule covers variable and tag deletes --- lib/llm/index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index e34fd2c..45fa5e8 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -755,7 +755,7 @@ n8nctl audit --categories credentials,nodes # Security audit JSON; omit --cate ### Safety Rules -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing @@ -1333,7 +1333,7 @@ ${rows} \`atl --context \`. Never rely on or mutate atl's shared persistent context from an agent session. -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (\`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing From 1c58bfebc9cbd465de6bebe1d8d3d5e6f5bb5574 Mon Sep 17 00:00:00 2001 From: Hinne Stolzenberg Date: Tue, 13 Oct 2026 15:32:47 +0200 Subject: [PATCH 7/7] docs: n8nctl safety rule covers workflow deactivate --- lib/llm/index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/llm/index.js b/lib/llm/index.js index 45fa5e8..9703797 100644 --- a/lib/llm/index.js +++ b/lib/llm/index.js @@ -755,7 +755,7 @@ n8nctl audit --categories credentials,nodes # Security audit JSON; omit --cate ### Safety Rules -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deactivates, deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow deactivate\`, \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing @@ -1333,7 +1333,7 @@ ${rows} \`atl --context \`. Never rely on or mutate atl's shared persistent context from an agent session. -**Safety**: Before any n8nctl operation on a production instance that deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): +**Safety**: Before any n8nctl operation on a production instance that deactivates, deletes, archives, unpublishes, changes access, or pulls source control (for example \`workflow deactivate\`, \`workflow push\`, \`workflow delete\`, \`workflow archive\`, \`workflow unpublish\`, \`credential delete\`, \`folder delete\`, \`variable delete\`, \`tag delete\`, \`dt delete-rows\`, \`project member add\`/\`set-role\`/\`remove\`, \`source-control pull\`): 1. Check the active instance: \`n8nctl config list\` 2. Show the command and the target instance to the user 3. Ask for explicit confirmation before executing