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/n8n_community-package_install.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ such as latest or beta; omit it to let npm select the version. Whether
unverified packages may be installed is an instance setting: when it is off,
only versions verified by n8n install. Installed package code runs inside n8n.

A node type policy does not stop the install. When the instance evaluates its
policies, the output lists each blocked node type of the package, or "none";
JSON output carries them as policyRestrictions.

Interactive runs ask before installing. Non-interactive runs fail unless --yes
is passed. Requires API-key authentication and communityPackage:install.
Next step: 'n8n community-package list'.
Expand Down
5 changes: 3 additions & 2 deletions docs/n8n_credential_create.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@ Create a credential from one JSON document. Required fields are name, type and
data; optional fields are projectId, isResolvable, description (plain text, at
most 512 characters; ignored when the instance has descriptions disabled) and
id (1 to 16 letters, digits, underscores or hyphens, kept exactly; omit it to
have one generated). Because data contains secrets, JSON is accepted only
through --file or piped --stdin, never argv.
have one generated). data fields also accept n8n expressions: strings that
start with "=". Because data contains secrets, JSON is accepted only through
--file or piped --stdin, never argv.

The request body is excluded from debug logs. Output contains metadata only.
Requires credential:create; project creation can have additional role restrictions.
Expand Down
3 changes: 2 additions & 1 deletion docs/n8n_credential_update.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ Update a credential from secret JSON
Update an owned credential from one JSON document. Accepted fields are name,
description, type, data, isGlobal, isResolvable and isPartialData. Set
isPartialData=true to merge provided data with stored data; false replaces the
full data object. Changing type requires data. description is at most 512
full data object. Changing type requires data. data fields also accept n8n
expressions: strings that start with "=". description is at most 512
characters; null or "" clears it and omitting it keeps it. Managed credentials
cannot be edited.

Expand Down
6 changes: 4 additions & 2 deletions docs/n8n_execution_retry.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ workflow definition stored with the original execution, making the retry
reproducible. --latest-workflow instead loads the workflow currently saved on
the instance.

The original execution is retained and the response identifies the new run. A
run that cannot be retried returns a conflict. This starts workflow work and may
The original execution is retained and the response identifies the new run. Its
run data, workflowData and customData are absent when the caller cannot read the
workflow's executions; the retry still starts. A run that cannot be retried
returns a conflict. This starts workflow work and may
repeat its external side effects. Requires execution:retry.

--idempotency-key KEY makes a retry after a timeout or lost response safe:
Expand Down
7 changes: 4 additions & 3 deletions docs/n8n_workflow_create.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,10 @@ nodes, ready to be edited in the UI or filled in by a later update.
The input may be a document produced by 'n8n workflow get --output json': the
read-only fields (id, versionId, active, timestamps, tags, sharing, node
timestamps) and settings set to "DEFAULT" are dropped before sending, because
the API answers them with 400, and the dropped names are reported on stderr. A
null settings is sent as {}. --name, --project-id and --parent-folder-id
override what the document says.
the API answers them with 400, and the dropped names are reported on stderr.
settings.engineType is dropped too: n8n ignores it on write and instances
before 2.46 reject it. A null settings is sent as {}. --name, --project-id and
--parent-folder-id override what the document says.

A created workflow is never published: publish it with 'n8n workflow publish'.
Requires workflow:create.
Expand Down
8 changes: 5 additions & 3 deletions docs/n8n_workflow_update.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,11 @@ Read-only fields in the document (id, versionId, active, timestamps, tags,
sharing, node timestamps) and settings set to "DEFAULT" are dropped before
sending and reported on stderr, because the API answers them with 400; an
omitted setting keeps the instance default, which is what "DEFAULT" means.
A null settings is sent as {}. Add "parentFolderId": "FOLDER_ID" to move
the workflow into a folder, or "parentFolderId": null to move it to the
project root; without the field the folder is unchanged.
settings.engineType is dropped and reported too: n8n ignores it on write and
instances before 2.46 reject it. A null settings is sent as {}. Add
"parentFolderId": "FOLDER_ID" to move the workflow into a folder, or
"parentFolderId": null to move it to the project root; without the field the
folder is unchanged.

A published workflow is republished with the new version unless --no-publish is
given. Republishing additionally needs the workflow:activate scope and the
Expand Down
41 changes: 40 additions & 1 deletion internal/cli/community_package.go
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,9 @@ func newCommunityPackageInstallCommand(opts Options) *cobra.Command {
"such as latest or beta; omit it to let npm select the version. Whether\n" +
"unverified packages may be installed is an instance setting: when it is off,\n" +
"only versions verified by n8n install. Installed package code runs inside n8n.\n\n" +
"A node type policy does not stop the install. When the instance evaluates its\n" +
"policies, the output lists each blocked node type of the package, or \"none\";\n" +
"JSON output carries them as policyRestrictions.\n\n" +
"Interactive runs ask before installing. Non-interactive runs fail unless --yes\n" +
"is passed. Requires API-key authentication and communityPackage:install.\n" +
"Next step: 'n8n community-package list'.",
Expand Down Expand Up @@ -332,7 +335,43 @@ func writeCommunityPackageText(opts Options, resolution config.Resolution, actio
if pkg.FailedLoading {
fmt.Fprintln(tw, "Status:\tfailed to load")
}
return tw.Flush()
if restrictions := pkg.PolicyRestrictions; restrictions != nil {
if len(restrictions.NodeTypes) == 0 {
fmt.Fprintln(tw, "Blocked node types:\tnone")
}
for _, blocked := range restrictions.NodeTypes {
fmt.Fprintf(tw, "Blocked node type:\t%s (%s)\n", blocked.Type, describeBlockedNodeType(blocked))
}
}
if err := tw.Flush(); err != nil {
return err
}
if pkg.PolicyRestrictions != nil && len(pkg.PolicyRestrictions.NodeTypes) > 0 {
count := fmt.Sprintf("%d node types", len(pkg.PolicyRestrictions.NodeTypes))
if len(pkg.PolicyRestrictions.NodeTypes) == 1 {
count = "1 node type"
}
fmt.Fprintf(opts.Streams.Err, "Node type policies block %s of %s; the package is still %s. Review the policies with 'n8n node-policy instance get' or 'n8n node-policy project get PROJECT_ID'.\n", count, pkg.PackageName, strings.ToLower(action))
}
return nil
}

// describeBlockedNodeType says where a policy blocks a node type and whether a
// project can still allow it.
func describeBlockedNodeType(blocked n8n.CommunityPackageBlockedNodeType) string {
var where string
switch blocked.BlockedOn {
case n8n.BlockedOnInstance:
where = "blocked on the instance"
case n8n.BlockedOnProjects:
where = "blocked in one or more projects"
default:
where = "blocked on " + emptyDash(blocked.BlockedOn)
}
if blocked.OptInAvailable {
where += "; a project can allow it"
}
return where
}

func validateCommunityPackageArgument(name string) error {
Expand Down
75 changes: 75 additions & 0 deletions internal/cli/community_package_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,81 @@ func TestCommunityPackageInstallJSONNonInteractive(t *testing.T) {
assertCLIJSON(t, `{"name":"n8n-nodes-example"}`, f.lastBody())
}

func TestCommunityPackageInstallPolicyRestrictionsText(t *testing.T) {
body := strings.TrimSuffix(cliCommunityPackage, "}") + `,"policyRestrictions":{"nodeTypes":[
{"type":"n8n-nodes-example.example","blockedOn":"instance","optInAvailable":true},
{"type":"n8n-nodes-example.other","blockedOn":"projects","optInAvailable":false}]}}`
f := communityPackageFixture(t, body)
got := f.run("community-package", "install", "n8n-nodes-example", "--yes")
if got.code != ExitSuccess {
t.Fatalf("exit code = %d, want %d (stderr: %s)", got.code, ExitSuccess, got.stderr)
}
for _, want := range []string{
"Blocked node type: n8n-nodes-example.example (blocked on the instance; a project can allow it)",
"Blocked node type: n8n-nodes-example.other (blocked in one or more projects)",
} {
if !strings.Contains(got.stdout, want) {
t.Errorf("stdout missing %q\n%s", want, got.stdout)
}
}
for _, want := range []string{"block 2 node types of n8n-nodes-example", "still installed", "n8n node-policy instance get"} {
if !strings.Contains(got.stderr, want) {
t.Errorf("stderr missing %q\n%s", want, got.stderr)
}
}
if strings.Contains(got.stdout, "node-policy") {
t.Errorf("stdout carries the hint; it belongs on stderr\n%s", got.stdout)
}
}

func TestCommunityPackageInstallPolicyRestrictionsNone(t *testing.T) {
f := communityPackageFixture(t, strings.TrimSuffix(cliCommunityPackage, "}")+`,"policyRestrictions":{"nodeTypes":[]}}`)
got := f.run("community-package", "install", "n8n-nodes-example", "--yes")
if got.code != ExitSuccess {
t.Fatalf("exit code = %d, want %d (stderr: %s)", got.code, ExitSuccess, got.stderr)
}
if !strings.Contains(got.stdout, "Blocked node types: none") {
t.Errorf("stdout missing empty policy result\n%s", got.stdout)
}
if got.stderr != "" {
t.Errorf("stderr = %q, want empty when nothing is blocked", got.stderr)
}
}

func TestCommunityPackageInstallWithoutPolicyRestrictions(t *testing.T) {
f := communityPackageFixture(t, cliCommunityPackage)
got := f.run("community-package", "install", "n8n-nodes-example", "--yes")
if got.code != ExitSuccess {
t.Fatalf("exit code = %d, want %d (stderr: %s)", got.code, ExitSuccess, got.stderr)
}
if strings.Contains(got.stdout, "Blocked") {
t.Errorf("stdout = %q, want no policy lines when the instance evaluated no policy", got.stdout)
}
}

func TestCommunityPackageInstallPolicyRestrictionsJSON(t *testing.T) {
f := communityPackageFixture(t, strings.TrimSuffix(cliCommunityPackage, "}")+
`,"policyRestrictions":{"nodeTypes":[{"type":"n8n-nodes-example.example","blockedOn":"instance","optInAvailable":false}]}}`)
got := f.run("community-package", "install", "n8n-nodes-example", "--yes", "--output", "json")
if got.code != ExitSuccess {
t.Fatalf("exit code = %d, want %d (stderr: %s)", got.code, ExitSuccess, got.stderr)
}
if got.stderr != "" {
t.Errorf("stderr = %q, want JSON output to stay quiet", got.stderr)
}
var out struct {
PolicyRestrictions struct {
NodeTypes []map[string]any `json:"nodeTypes"`
} `json:"policyRestrictions"`
}
if err := json.Unmarshal([]byte(got.stdout), &out); err != nil {
t.Fatalf("stdout is not JSON: %v\n%s", err, got.stdout)
}
if len(out.PolicyRestrictions.NodeTypes) != 1 || out.PolicyRestrictions.NodeTypes[0]["blockedOn"] != "instance" {
t.Errorf("policyRestrictions = %+v, want the blocked node type", out.PolicyRestrictions)
}
}

func TestCommunityPackageInstallScopedName(t *testing.T) {
f := communityPackageFixture(t, cliCommunityPackage)
got := f.run("community-package", "install", "@acme/n8n-nodes-example", "--version", "beta", "--yes")
Expand Down
8 changes: 5 additions & 3 deletions internal/cli/credential.go
Original file line number Diff line number Diff line change
Expand Up @@ -220,8 +220,9 @@ func newCredentialCreateCommand(opts Options) *cobra.Command {
"data; optional fields are projectId, isResolvable, description (plain text, at\n" +
"most 512 characters; ignored when the instance has descriptions disabled) and\n" +
"id (1 to 16 letters, digits, underscores or hyphens, kept exactly; omit it to\n" +
"have one generated). Because data contains secrets, JSON is accepted only\n" +
"through --file or piped --stdin, never argv.\n\n" +
"have one generated). data fields also accept n8n expressions: strings that\n" +
"start with \"=\". Because data contains secrets, JSON is accepted only through\n" +
"--file or piped --stdin, never argv.\n\n" +
"The request body is excluded from debug logs. Output contains metadata only.\n" +
"Requires credential:create; project creation can have additional role restrictions.",
Example: " n8n credential create --file credential.json\n" +
Expand Down Expand Up @@ -265,7 +266,8 @@ func newCredentialUpdateCommand(opts Options) *cobra.Command {
Long: "Update an owned credential from one JSON document. Accepted fields are name,\n" +
"description, type, data, isGlobal, isResolvable and isPartialData. Set\n" +
"isPartialData=true to merge provided data with stored data; false replaces the\n" +
"full data object. Changing type requires data. description is at most 512\n" +
"full data object. Changing type requires data. data fields also accept n8n\n" +
"expressions: strings that start with \"=\". description is at most 512\n" +
"characters; null or \"\" clears it and omitting it keeps it. Managed credentials\n" +
"cannot be edited.\n\n" +
"Secret JSON is accepted only through --file or piped --stdin and is excluded from\n" +
Expand Down
14 changes: 11 additions & 3 deletions internal/cli/execution.go
Original file line number Diff line number Diff line change
Expand Up @@ -633,8 +633,10 @@ func newExecutionRetryCommand(opts Options) *cobra.Command {
"workflow definition stored with the original execution, making the retry\n" +
"reproducible. --latest-workflow instead loads the workflow currently saved on\n" +
"the instance.\n\n" +
"The original execution is retained and the response identifies the new run. A\n" +
"run that cannot be retried returns a conflict. This starts workflow work and may\n" +
"The original execution is retained and the response identifies the new run. Its\n" +
"run data, workflowData and customData are absent when the caller cannot read the\n" +
"workflow's executions; the retry still starts. A run that cannot be retried\n" +
"returns a conflict. This starts workflow work and may\n" +
"repeat its external side effects. Requires execution:retry.\n\n" +
idempotencyHelp,
Example: " n8n execution retry EXECUTION_ID\n" +
Expand Down Expand Up @@ -679,7 +681,13 @@ func runExecutionRetry(ctx context.Context, opts Options, id string, f execution
if f.output == outputJSON {
return writeJSON(opts.Streams.Out, execution)
}
return writeExecutionDetail(opts, resolution, "New execution", execution)
if err := writeExecutionDetail(opts, resolution, "New execution", execution); err != nil {
return err
}
if len(execution.Data) == 0 {
fmt.Fprintf(opts.Streams.Err, "The retry started, but %s returned no run data: the caller cannot read this workflow's executions. Follow it with 'n8n execution get %s' from a user who can.\n", resolution.URL, emptyDash(execution.ID))
}
return nil
}

func newExecutionTagCommand(opts Options) *cobra.Command {
Expand Down
59 changes: 59 additions & 0 deletions internal/cli/execution_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,65 @@ func TestExecutionStopAndRetry(t *testing.T) {
t.Errorf("stdout = %q (error: %v)", got.stdout, err)
}
})

t.Run("retry text with run data", func(t *testing.T) {
f := executionFixture(t, cliExecution)
got := f.run("execution", "retry", "1000")
if got.code != ExitSuccess {
t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr)
}
if !strings.Contains(got.stdout, "Data included: true") {
t.Errorf("stdout = %q, want data included", got.stdout)
}
if got.stderr != "" {
t.Errorf("stderr = %q, want empty", got.stderr)
}
})

// n8n 2.46+ leaves data, workflowData and customData out when the caller
// cannot read the workflow's executions.
const withoutData = `{"id":"1001","mode":"retry","startedAt":"2026-09-17T10:00:01Z","workflowId":"wf-1","finished":false,"retryOf":"1000","status":"running","storedAt":"db"}`

t.Run("retry text without run data", func(t *testing.T) {
f := executionFixture(t, withoutData)
got := f.run("execution", "retry", "1000")
if got.code != ExitSuccess {
t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr)
}
for _, want := range []string{"New execution:", "1001", "Retry of:", "1000", "running", "Data included: false"} {
if !strings.Contains(got.stdout, want) {
t.Errorf("stdout missing %q\n%s", want, got.stdout)
}
}
for _, want := range []string{"no run data", "cannot read this workflow's executions", "n8n execution get 1001"} {
if !strings.Contains(got.stderr, want) {
t.Errorf("stderr missing %q\n%s", want, got.stderr)
}
}
})

t.Run("retry json without run data", func(t *testing.T) {
f := executionFixture(t, withoutData)
got := f.run("execution", "retry", "1000", "--output", "json")
if got.code != ExitSuccess {
t.Fatalf("exit = %d, stderr: %s", got.code, got.stderr)
}
if got.stderr != "" {
t.Errorf("stderr = %q, want JSON output to stay quiet", got.stderr)
}
var out map[string]json.RawMessage
if err := json.Unmarshal([]byte(got.stdout), &out); err != nil {
t.Fatalf("stdout is not JSON: %v\n%s", err, got.stdout)
}
if string(out["id"]) != `"1001"` {
t.Errorf("id = %s, want \"1001\"", out["id"])
}
for _, field := range []string{"data", "workflowData", "customData", "annotation"} {
if _, ok := out[field]; ok {
t.Errorf("stdout carries %s = %s, want it absent", field, out[field])
}
}
})
}

func TestExecutionTags(t *testing.T) {
Expand Down
15 changes: 9 additions & 6 deletions internal/cli/workflow.go
Original file line number Diff line number Diff line change
Expand Up @@ -354,9 +354,10 @@ func newWorkflowCreateCommand(opts Options) *cobra.Command {
"The input may be a document produced by 'n8n workflow get --output json': the\n" +
"read-only fields (id, versionId, active, timestamps, tags, sharing, node\n" +
"timestamps) and settings set to \"DEFAULT\" are dropped before sending, because\n" +
"the API answers them with 400, and the dropped names are reported on stderr. A\n" +
"null settings is sent as {}. --name, --project-id and --parent-folder-id\n" +
"override what the document says.\n\n" +
"the API answers them with 400, and the dropped names are reported on stderr.\n" +
"settings.engineType is dropped too: n8n ignores it on write and instances\n" +
"before 2.46 reject it. A null settings is sent as {}. --name, --project-id and\n" +
"--parent-folder-id override what the document says.\n\n" +
"A created workflow is never published: publish it with 'n8n workflow publish'.\n" +
"Requires workflow:create.\n\n" +
idempotencyHelp,
Expand Down Expand Up @@ -472,9 +473,11 @@ func newWorkflowUpdateCommand(opts Options) *cobra.Command {
"sharing, node timestamps) and settings set to \"DEFAULT\" are dropped before\n" +
"sending and reported on stderr, because the API answers them with 400; an\n" +
"omitted setting keeps the instance default, which is what \"DEFAULT\" means.\n" +
"A null settings is sent as {}. Add \"parentFolderId\": \"FOLDER_ID\" to move\n" +
"the workflow into a folder, or \"parentFolderId\": null to move it to the\n" +
"project root; without the field the folder is unchanged.\n\n" +
"settings.engineType is dropped and reported too: n8n ignores it on write and\n" +
"instances before 2.46 reject it. A null settings is sent as {}. Add\n" +
"\"parentFolderId\": \"FOLDER_ID\" to move the workflow into a folder, or\n" +
"\"parentFolderId\": null to move it to the project root; without the field the\n" +
"folder is unchanged.\n\n" +
"A published workflow is republished with the new version unless --no-publish is\n" +
"given. Republishing additionally needs the workflow:activate scope and the\n" +
"project's workflow:publish permission; without them the new version is still\n" +
Expand Down
Loading
Loading