n8n-nodes-self-cloud-cli

An n8n community node for a self-hosted CloudCLI 1.37.3 or newer. It combines the public Agent API with CloudCLI's authenticated project/session APIs and WebSocket chat gateway. The node buffers SSE/WebSocket events internally; downstream n8n nodes receive data only after the operation finishes.

Install

From this directory:

npm install
npm run build

Install the package into the same environment as n8n, then restart n8n. Configure a Self-Hosted CloudCLI API credential with the root URL (for example http://localhost:3001), CloudCLI username/password, and an Agent API key when /api/agent or global API-key protection is used.

The node checks /health, requires CloudCLI 1.37.3+, checks /api/auth/status, and logs in. It never registers a user. JWTs and refreshed JWTs are cached only for the current n8n execution.

Coverage

The node exposes explicit operations for:

• projects (active/archived/session lists, path creation, GitHub clone, rename, favorite, archive, restore, permanent delete, TaskMaster status);
• continuous conversations (create, send/continue, edit and resend, abort, list/detail/history/search, token usage, rename, fork, archive/restore/delete);
• public Agent jobs, including provider/model/effort/session, temporary clone, cleanup, GitHub token, branch and pull-request options;
• chat attachments and project-file binary upload/download;
• provider capabilities/auth/models, Skills, MCP servers and plugins;
• project files, Git, worktrees, TaskMaster, scheduled messages and commands;
• Browser Use management and every CloudCLI Browser MCP tool.

For Agent jobs, enabling Create Pull Request also enables branch creation and push so CloudCLI always has a remote head branch for the PR.

Command → Resolve to Agent Prompt parses a built-in/custom command and returns its result or prompt. It does not execute arbitrary shell commands. TaskMaster exposes installation status; CloudCLI 1.37.3 has no TaskMaster installation endpoint.

Advanced Query and Request Body JSON fields preserve access to route-specific options without delaying support for server-compatible additions. Explicit node fields take precedence where noted.

Conversation and attachment behavior

When Send has no Session ID, the node creates an app session first and then sends the real message over /ws. initialMessage is used only for the session title. Binary properties are uploaded to /api/assets/files before chat and their returned descriptors are attached to the message. Existing descriptors can be supplied as JSON.

Limits enforced before upload:

• chat files: 10 files, 10 MB each;
• chat images via Attachment: 5 files, 5 MB each;
• project files: 20 files, 200 MB each.

n8n may hold binary content in memory. CloudCLI 1.37.3 has no chat-attachment delete API, so uploaded files remain in ~/.cloudcli/assets; the deployment operator should define retention/cleanup.

Output modes are Final Result, Full Event Log, and One Item Per Event. Event items contain pairedItem metadata. Final results contain session/status/text/completion/token usage/attachment summaries.

Agent calls always use SSE between the node and CloudCLI because CloudCLI 1.37.3's non-streaming collector does not preserve current normalized provider messages. This is internal transport only: downstream n8n nodes still receive output once the Agent operation finishes. Saved workflows containing the former stream parameter remain compatible; that value is ignored.

Agent output prefers complete assistant messages over streaming deltas, so text is not duplicated, exposes the provider session ID needed to continue a later Agent call, and reports an explicit provider failure as status: error while preserving its completion and error event. Conversation search returns structured title/project results and progress totals. Paginated project-session and recent-conversation operations fetch every server page when Return All is enabled.

Permissions and safety

The default approval policy is Abort and Return. On a Claude permission request the node records it, sends chat.abort, waits for the terminal event, and only then returns approval_required. Auto Approve and Auto Deny are opt-in. bypassPermissions is explicitly high risk. A standalone Abort first subscribes to the active run so it can observe the terminal event; it returns not_running immediately when the session is already idle. If a run finishes while the WebSocket is disconnected, CloudCLI 1.37.3 does not expose enough persisted run state to verify its outcome, so the node fails explicitly instead of returning an older assistant message as the result.

Destructive or code-executing operations default to Do Not Execute and make no request until I Understand, Execute is selected. This covers permanent deletion, destructive Git/worktree actions, Skill installation/replacement/deletion, plugin install/update/uninstall/RPC, Browser runtime installation, and browser navigation/click/type/form actions.

Skill installation performs a case-insensitive, Unicode-normalized conflict check against user-scope Skills returned by CloudCLI and refuses known conflicts. Every installed/replaced entry must provide an explicit directoryName; Replace is a separately confirmed operation. Supporting paths reject absolute paths, traversal, empty names, and SKILL.md. CloudCLI replaces the complete target directory when installing, while malformed or unreadable Skills are omitted from its list API, so Install also requires confirmation and cannot provide an atomic If Exists=Fail guarantee for unlisted directories.

MCP output is redacted by default. Passwords, JWT/API/GitHub/Browser tokens, authorization headers, environment/header containers, sensitive URL parameters and common secret fields are removed from normal output and errors. Include Sensitive Configuration is an explicit MCP-only escape hatch and should be used carefully because n8n stores execution data.

Browser tools use the independent Browser MCP token, not the login JWT, and also send X-API-Key when global API-key protection is configured. The Browser token is discovered in memory from the user-scope cloudcli-browser MCP registration and is never emitted. Run Browser Use → Enable first if the registration is absent. Screenshot Data URLs are moved exclusively into n8n binary output and removed from execution JSON.

Testing

npm test
npm run lint

Unit and contract tests are non-mutating. Live integration tests should use a disposable CloudCLI workspace and credentials. Do not enable write/destructive integration scenarios against production data.

Scope

Account registration/preferences, API-key and third-party credential management, notifications/Web Push, voice, CloudCLI self-update, interactive shell WebSocket, and plugin frontend WebSocket proxy are intentionally excluded. This package calls CloudCLI APIs and does not copy or modify the CloudCLI server implementation.