Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,7 @@ edit the command's Short, Long, Example or flag usage and run `make docs`.
| [`n8n promotion environment disconnect`](n8n_promotion_environment_disconnect.md) | Remove the local checkout of a promotion environment |
| [`n8n promotion environment get`](n8n_promotion_environment_get.md) | Show one promotion environment |
| [`n8n promotion environment list`](n8n_promotion_environment_list.md) | List promotion environments |
| [`n8n promotion environment missing-projects`](n8n_promotion_environment_missing-projects.md) | List branch projects missing on this instance (n8n 2.47 and later) |
| [`n8n promotion environment project add`](n8n_promotion_environment_project_add.md) | Link a project to a promotion environment |
| [`n8n promotion environment project list`](n8n_promotion_environment_project_list.md) | List projects linked to a promotion environment |
| [`n8n promotion environment project remove`](n8n_promotion_environment_project_remove.md) | Unlink a project from a promotion environment |
Expand All @@ -203,6 +204,9 @@ edit the command's Short, Long, Example or flag usage and run `make docs`.
| [`n8n promotion provider update`](n8n_promotion_provider_update.md) | Update a promotion provider |
| [`n8n promotion provider`](n8n_promotion_provider.md) | Manage promotion providers |
| [`n8n promotion`](n8n_promotion.md) | Manage promotion providers, environments, connections, and apply/promote sync |
| [`n8n rate-limit get`](n8n_rate-limit_get.md) | Get Public API rate-limit settings |
| [`n8n rate-limit set`](n8n_rate-limit_set.md) | Fully replace Public API rate-limit settings |
| [`n8n rate-limit`](n8n_rate-limit.md) | Manage Public API rate limits |
| [`n8n role create`](n8n_role_create.md) | Create a custom role |
| [`n8n role delete`](n8n_role_delete.md) | Permanently delete a custom role |
| [`n8n role get`](n8n_role_get.md) | Get one role |
Expand Down
1 change: 1 addition & 0 deletions docs/n8n.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ n8n [flags]
* [n8n package](n8n_package.md) - Export and import n8n packages (beta)
* [n8n project](n8n_project.md) - Manage projects and their members
* [n8n promotion](n8n_promotion.md) - Manage promotion providers, environments, connections, and apply/promote sync
* [n8n rate-limit](n8n_rate-limit.md) - Manage Public API rate limits
* [n8n role](n8n_role.md) - Manage global and project roles
* [n8n role-mapping](n8n_role-mapping.md) - Manage identity-provider role-mapping rules
* [n8n saml](n8n_saml.md) - Manage licensed SAML SSO settings
Expand Down
24 changes: 16 additions & 8 deletions docs/n8n_package_import-selection.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,16 +21,24 @@ executions permanently, so prefer archive). --workflow-id may be omitted
for a delete-only run. Selected IDs from another project are dropped,
absent delete IDs are a no-op, and an ID cannot be both imported and
deleted. Folder, tag, and project policies are fixed by the server; only
the workflow conflict, workflow ID, and deletion policies are settable.
A workflow package is rejected with a 400: export a project package with
'n8n package export --project-id'.
the conflict, ID, and deletion policies are settable, and publication
follows match-source. A workflow package is rejected with a 400: export a
project package with 'n8n package export --project-id'. Packages that
contain Agents are rejected before writes on n8n 2.47 and later: import
selected-Agent exports with 'n8n package import'. n8n 2.47 renamed
--workflow-conflict-policy and --workflow-id-policy to --conflict-policy
and --id-policy (the old flags remain as deprecated aliases); older
instances get the old field names automatically, which needs --file
PATH because stdin cannot be sent twice.

Beta: breaking changes may still occur without a major version bump.
This mutates the instance, so interactive runs ask for confirmation and
non-interactive runs require --yes; --file - also requires --yes because
stdin cannot answer. Needs workflow:import, plus workflow:delete when
deleting or when an update changes a workflow's archive state, and the
licensed Packages feature. Output is the same import result as
deleting or when an update changes a workflow's archive state,
workflow:activate or workflow:deactivate when match-source changes
publication, and the licensed Packages feature. Output is the same
import result as
'n8n package import'.

--idempotency-key KEY makes a retry after a timeout or lost response safe:
Expand All @@ -46,25 +54,25 @@ n8n package import-selection [flags]

```
n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --workflow-id 7pQr3sTuVwXyZaBc --yes
n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --workflow-conflict-policy fail --output json --yes
n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --workflow-id 2tUt1wbLX592XDdX --delete-workflow-id 9xKp2mNqRzAbCdEf --conflict-policy fail --output json --yes
n8n package import-selection --file project.n8np --project-id Ox8O54VQrmBrb4qL --delete-workflow-id 9xKp2mNqRzAbCdEf --overwrite-deletion-policy hard-delete
```

### Options

```
--conflict-policy string selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version)
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
--delete-workflow-id stringArray destination workflow ID to remove from the target project, repeatable; needs workflow:delete and must not match a --workflow-id (default: none)
--file string project package archive (.n8np) to import from: a file path, or - for stdin (required; stdin requires --yes)
-h, --help help for import-selection
--id-policy string ID for newly created workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source) (default "source")
--idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency)
--output string output format: text or json (JSON is the full import result) (default "text")
--overwrite-deletion-policy string how --delete-workflow-id removes workflows: archive (recoverable) or hard-delete (also drops executions permanently; prefer archive); needs --delete-workflow-id (default: server default archive)
--project-id string source project ID as it appears in the package; also the target project ID, created if missing (required)
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--workflow-conflict-policy string selected workflow that already exists in the target project: new-version updates it, fail rejects the import, skip leaves it unchanged (default: server default new-version)
--workflow-id stringArray source workflow ID to import from --project-id, repeatable (default: none, for a delete-only run with --delete-workflow-id)
--workflow-id-policy string ID for newly created workflows, always sent: source reuses the package ID, new mints a fresh ID (default: source) (default "source")
--yes confirm importing and deleting the listed workflows without prompting (required when stdin is not interactive)
```

Expand Down
52 changes: 33 additions & 19 deletions docs/n8n_package_import.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,26 @@ Import an n8n package into a project (beta)

### Synopsis

Import a gzip-compressed tar package (.n8np) into the target project.
Send the archive with --file FILE or --file - for stdin, route it with
--project-id and --folder-id (omit both for the caller's personal project
root), and state --workflow-conflict-policy explicitly: new-version
updates matching workflows, fail rejects the import when any matches, and
skip leaves matching workflows unchanged.
Import a gzip-compressed tar package (.n8np) into the target project:
Agent-only, workflow-only, mixed, or whole-project packages (Agents need
the Agents module). Send the archive with --file FILE or --file - for
stdin, route it with --project-id and --folder-id (omit both for the
caller's personal project root), and state --conflict-policy explicitly:
new-version replaces matching Agents and workflows (and saves a changed
skill of an imported Agent as a new version, which every Agent following
that skill picks up), fail rejects the import when any matches, and skip
leaves them unchanged.

n8n 2.47 renamed the workflow-only policies to --conflict-policy,
--id-policy, and --publishing-policy, which cover Agents and workflows;
the old --workflow-* flags remain as deprecated aliases. Older instances
get the old field names automatically, which needs --file PATH: stdin
cannot be sent twice.

Beta: breaking changes may still occur without a major version bump.
This mutates the instance: imported workflows arrive per
--workflow-publishing-policy, new-version follows the package archive
This mutates the instance: imported Agents and workflows arrive per
--publishing-policy (a failed publication keeps the imported definition
and is reported per entity), new-version follows the package archive
state (archiving needs workflow:delete), folder overwrite can remove
workflows the package does not contain (archive is recoverable,
hard-delete also drops executions permanently, so prefer archive),
Expand All @@ -27,11 +37,15 @@ Interactive runs ask for confirmation and non-interactive runs require
--yes; --file - also requires --yes because stdin cannot answer.
Credentials created from incomplete package data are reported on
stderr and keep their workflows unpublished until completed. When the
import is blocked (409 or 422), each issue is listed on stderr. Needs
workflow:import plus, depending on the package and the policies,
credential, variable, tag, data-table, folder, and delete scopes, and
the Packages, Variables, and Folders features where the contents
require them.
import is blocked (409 or 422), each issue is listed on stderr, and
Agent channels that need setup are listed with their setup URL. Needs
workflow:import for workflows and agent:import plus agent:read for
Agents (both for mixed packages; agent:create, agent:update,
agent:publish, or agent:unpublish for the planned Agent actions),
workflow:activate or workflow:deactivate when publication changes, plus,
depending on the package and the policies, credential, variable, tag,
data-table, folder, skill, and delete scopes, and the Packages,
Variables, and Folders features where the contents require them.

--idempotency-key KEY makes a retry after a timeout or lost response safe:
the same request with the same key returns the first result instead of
Expand All @@ -45,15 +59,16 @@ n8n package import [flags]
### Examples

```
n8n package import --file workflows.n8np --workflow-conflict-policy new-version --yes
n8n package import --file project.n8np --workflow-conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json
n8n package import --file update.n8np --workflow-conflict-policy skip --workflow-publishing-policy publish-all --yes
n8n package import --file workflows.n8np --conflict-policy new-version --yes
n8n package import --file project.n8np --conflict-policy fail --project-id Ox8O54VQrmBrb4qL --yes --output json
n8n package import --file agent.n8np --conflict-policy skip --publishing-policy match-source --yes
```

### Options

```
--bindings string explicit credential bindings as JSON, e.g. '{"credentials":{"pkg-id":"target-id"}}' (default: server default {})
--conflict-policy string matching Agent and workflow handling, required: new-version, fail, or skip (before n8n 2.47 workflows only)
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
--credential-conflict-policy string matched credential whose package values differ: keep-existing never changes it, overwrite writes the package name and expression values to credentials a project of the import owns (keeps secrets, other fields, and OAuth connections; reported in credentials.updated), fail rejects the import with a 409 credential-conflict; overwrite and fail need credential:update on matched credentials (default: server default keep-existing)
--credential-matching-mode string how package credential references match: id-only, name-and-type, or type-only (default: server default id-only)
Expand All @@ -65,21 +80,20 @@ n8n package import [flags]
--folder-conflict-policy string existing folder handling: merge, fail, or overwrite; empty follows --project-conflict-policy on project packages, merge otherwise (default: follow)
--folder-id string folder within the target project, from 'n8n folder list PROJECT_ID' (default: the project root)
-h, --help help for import
--id-policy string ID for newly created Agents and workflows, always sent: source reuses the package ID; new mints a fresh ID but only instances before n8n 2.47 accept it (default: source) (default "source")
--idempotency-key string retry key sent as the Idempotency-Key header: 1 to 128 visible ASCII characters, or auto for a random UUID printed on stderr; rerun the same command with the same key to get the first result instead of a second run (default: none, no idempotency)
--missing-node-type-mode string unknown node type handling: fail rejects before anything is written, import-anyway imports without publishing those workflows (default: server default fail)
--output string output format: text or json (JSON is the full import result) (default "text")
--overwrite-deletion-policy string how folder overwrite removes missing workflows: archive (recoverable) or hard-delete (also drops executions; prefer archive) (default: server default archive)
--project-conflict-policy string existing project handling for project packages: merge, fail, or overwrite (default: server default merge)
--project-id string target project ID, from 'n8n project list' (default: the caller's personal project)
--publishing-policy string post-import publishing of Agents and workflows: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state)
--tag-conflict-policy string conflicted tag handling: skip, fail, or rename (default: server default skip)
--tag-missing-mode string missing tag handling: create or do-nothing (default: server default create)
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--variable-conflict-policy string differing variable value handling: keep-existing, overwrite (may rewrite globals), or fail (default: server default keep-existing)
--variable-missing-mode string missing variable handling: do-nothing, must-preexist, create-stub, or create-with-value (default: server default create-with-value)
--variable-parent-policy string where workflow and folder packages create missing variables: project or global; omit for project packages, which reject it (default: import target project)
--workflow-conflict-policy string matching workflow handling, required: new-version, fail, or skip
--workflow-id-policy string ID for newly created workflows, always sent: source reuses the package ID for promotions, new mints a fresh ID for repeat imports (default: source) (default "source")
--workflow-publishing-policy string post-import publishing: preserve-published-state, match-source, publish-all, or unpublish-all (default: server default preserve-published-state)
--yes confirm importing, publishing, archiving, deleting, and overwriting without prompting (required when stdin is not interactive)
```

Expand Down
3 changes: 2 additions & 1 deletion docs/n8n_promotion_environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ each direction.
Sync the whole instance through the connected instance-scope
environment: 'promote' pushes every team project to a promote
environment; 'apply' imports an apply environment's branch, and
'apply-continue' finishes an apply that preflight blocked. For selected
'apply-continue' finishes an apply that its check blocked. For selected
workflows of one project use 'n8n promotion project changes', 'apply',
and 'promote'.

Expand Down Expand Up @@ -59,6 +59,7 @@ n8n promotion environment [flags]
* [n8n promotion environment disconnect](n8n_promotion_environment_disconnect.md) - Remove the local checkout of a promotion environment
* [n8n promotion environment get](n8n_promotion_environment_get.md) - Show one promotion environment
* [n8n promotion environment list](n8n_promotion_environment_list.md) - List promotion environments
* [n8n promotion environment missing-projects](n8n_promotion_environment_missing-projects.md) - List branch projects missing on this instance (n8n 2.47 and later)
* [n8n promotion environment project](n8n_promotion_environment_project.md) - Manage projects linked to a promotion environment
* [n8n promotion environment promote](n8n_promotion_environment_promote.md) - Promote team projects to an environment's Git remote
* [n8n promotion environment update](n8n_promotion_environment_update.md) - Update a promotion environment
Expand Down
16 changes: 9 additions & 7 deletions docs/n8n_promotion_environment_apply-continue.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ Continue a reviewed environment apply after binding setup
### Synopsis

Continue a full environment apply (n8n 2.46 and later) after resolving its
preflight items. Start with 'n8n promotion environment apply ENVIRONMENT_ID
check items. Start with 'n8n promotion environment apply ENVIRONMENT_ID
--output json'. The instance-scope apply environment must still be
connected. Every team project is synchronized: workflows, folders,
credentials, tables, variables, and tags can be created, updated, moved,
renamed, or removed to match. Requires gitConnection:pull and the same
permissions as the initial apply.
renamed, or removed to match. Requires promotions:apply (gitConnection:pull
before n8n 2.47) and the same permissions as the initial apply.

Use --expected-from FILE|- with changes JSON or a blocked apply result,
or supply --expected-environment-id, --expected-branch, and
Expand All @@ -24,10 +24,12 @@ columns and loss of their values; rows and other columns remain.
It also permits deleting team projects with everything in them.
This covers every such change at continue time, including changes absent
from the reviewed result.
Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 other error. Only
applied writes content. Resolve blocked bindings before apply-continue;
review source-changed results again. JSON prints the full status result;
text shows preflight details or counts and warnings. Hints go to stderr.
Exit codes: 0 applied, 3 blocked, 4 source-changed or preview-changed
(n8n 2.47 and later), 1 other error. Only applied writes content.
Resolve blocked items before apply-continue; review source-changed and
preview-changed results again. JSON prints the full status result; text
shows the blocking check (preflight before n8n 2.47) or counts and
warnings. Hints go to stderr.
Read request JSON with --input FILE|- (maximum 1 MiB). Input and document flags are
mutually exclusive. Interactive runs ask for confirmation; non-interactive
runs and stdin input require --yes. JSON returns the server result; text
Expand Down
Loading
Loading