Self-improving AI Employees for everyone
Cloudflare (cloudflareAction)
| Field | Value |
|---|---|
| Category | deployment (palette group deployment; class group = ("deployment", "tool")) |
| Backend handler | server/nodes/cloudflare/cloudflare_action.py (CloudflareActionNode, on ActionNode); env / credential routing and the neutral working directory in _service.py; installer _install.py; login WS handlers _handlers.py |
| Tests | server/tests/test_cloudflare_plugin.py |
| Skill (if any) | server/skills/cloudflare/cloudflare-skill/SKILL.md (allowed-tools: "cloudflare") |
| Dual-purpose tool | yes - tool name cloudflare |
Purpose
Drive Cloudflare through the official cf CLI (npm [email protected], in
open beta) from a workflow or from an agent. Typed operations cover the
CLI identity, a command search, zone listing and DNS record list / create /
edit / delete; one operation posts directly to the GraphQL Analytics API
(cf has no GraphQL command); custom passes any other cf ... command
through. The CLI owns its own auth: the node performs no credential
pre-flight and never puts a token in argv.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Declared, so it renders on the canvas although hideInputHandle is auto-set (usable_as_tool = True); the node is usually reached through output-tool |
Parameters
extra="ignore" on the model. A mode="before" model validator
(coerce_blank_params) drops panel blanks for the integer fields, and
record_body / graphql_variables have a mode="before" validator that
json.dumps a dict / list (LLM tool calls pass real objects; the CLI flag
and HTTP body want a string).
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
operation |
whoami | search_commands | zones_list | dns_records_list | dns_record_create | dns_record_edit | dns_record_delete | graphql_query | custom |
whoami |
no | - | Operation dispatch key |
account_id |
string | "" |
no | zones_list, the four dns_* ops, custom |
Sent as CLOUDFLARE_ACCOUNT_ID (cf has no --account-id flag on most commands); zones_list also passes it as --account-id |
zone |
string | "" |
yes* | the four dns_* ops |
Zone ID or domain; a domain is resolved to its ID first (see Decision Logic). Empty raises NodeUserError |
name_filter |
string | "" |
no | zones_list, dns_records_list |
--name <f> (a domain for zones, a full record name for DNS) |
record_type |
string | "" |
no | dns_records_list |
--type, upper-cased |
page |
int | null | null |
no | zones_list, dns_records_list |
--page N (>= 1) |
per_page |
int | null | null |
no | zones_list, dns_records_list |
--per-page N (>= 1) |
record_body |
string (JSON object) | "" |
yes* | dns_record_create, dns_record_edit |
Passed as --body; must parse as a JSON object |
record_id |
string | "" |
yes* | dns_record_edit, dns_record_delete |
Positional record id |
graphql_query |
string | "" |
yes* | operation=graphql_query |
GraphQL Analytics API query text |
graphql_variables |
string (JSON object) | "" |
no | operation=graphql_query |
Parsed with json.loads; invalid JSON raises NodeUserError |
search_query |
string | "" |
yes* | operation=search_commands |
The task to find a command for (cf cli search) |
command |
string | "" |
yes* | operation=custom |
Everything after cf , split with shlex.split |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | CloudflareActionOutput; declared, so it renders although hideOutputHandle is auto-set |
output-tool |
- | Auto-appended for usable_as_tool |
Output payload (TypeScript shape)
Keys are omitted when empty (_shape never writes None; exclude_unset
preserves that). extra="allow".
{
operation: string;
success: true; // failures raise instead of returning
url?: string; // custom only: stdout that is one line starting with "http"
result?: unknown; // parsed JSON stdout (cf prints the unwrapped API result), or the GraphQL body
stdout?: string; // raw stdout ONLY when it did not parse as JSON (e.g. a BIND export)
stderr_tail?: string; // last 2000 chars of stderr when cf printed status lines
}
Logic Flow
flowchart TD
A[Validate params] --> B{operation}
B -- whoami --> R[_run: ensure_cf_cli -> run_cli_command argv, env=cf_env token,account_id, cwd=cf_workdir]
B -- search_commands --> Q[require search_query, argv cli search query] --> R
B -- zones_list --> Z[argv zones list + optional --name / --account-id / --page / --per-page] --> R
B -- dns_records_list / create / edit / delete --> D[require record_id / record_body where needed]
D --> ZI{zone is a 32-hex ID or UUID?}
ZI -- no --> ZL[_run zones list --name domain] --> ZR{exactly one zone id?}
ZR -- none or several --> ERR3[NodeUserError: zone not found / set account_id]
ZR -- one --> ZID[zone id]
ZI -- yes --> ZID
ZID --> R
B -- custom --> C[shlex.split, drop leading cf, refuse sign-in / dev, cwd = workspace, timeout 300s] --> R
B -- graphql_query --> G[require graphql_query, parse graphql_variables]
G --> K{stored token or CLOUDFLARE_API_TOKEN / CLOUDFLARE_API_KEY env}
K -- none, or cfk_ without email --> ERR[NodeUserError: credential guidance, requires_user_action]
K -- ok --> P[POST client/v4/graphql, 60s httpx]
P -- 401/403 --> ERR
P -- non-JSON, >=400, or data null with errors --> ERR
P -- ok --> S[_shape: result = body]
R -- install raised --> RT[NodeUserError cf CLI install failed]
R -- exit != 0 or timeout --> ERR2[NodeUserError cf command failed: stderr tail + hint]
R -- exit 0 but Aborted --> ERR4[NodeUserError: add --force]
R -- ok --> S2[_shape: parsed JSON -> result, else stdout; stderr_tail]
S --> OUT[Return envelope]
S2 --> OUT
Decision Logic
- Validation (all
NodeUserError, raised before any CLI call): blankzoneon a DNS op; blank or non-objectrecord_body; blankrecord_id; blanksearch_query; blankgraphql_query;graphql_variablesthat is not JSON; blank or unparseablecommand. - No auth pre-flight:
_runnever checks whether cf is logged in. cf's own "No authentication token found" text arrives on stderr and is surfaced by the failure wrap. - Zone resolution (
_zone_id): a 32-hex ID or UUID is used as-is. Anything else is a domain: lower-cased, trailing dot dropped, looked up withzones list --name <domain> [--account-id <id>](exact match across every account the credential sees). No match -> "Zone not found"; matches with different ids -> "set account_id". cf's own domain lookup is avoided because it needs an account selected and searches only the first page of that account's zones. - Credential routing for CLI ops (
cf_env): a stored key that does not start withcfk_becomesCLOUDFLARE_API_TOKEN(beats the OAuth login and an ambient token); acfk_Global API Key is not injected (cf does not accept Global API Keys).account_idbecomesCLOUDFLARE_ACCOUNT_ID.CF_DELEGATION=1,CF_SEND_TELEMETRY=falseandNO_COLOR=1are always set. Ambient env vars are otherwise left in place. - Working directory: typed ops run from
cf_workdir()(<DATA_DIR>/cloudflare), so no stray.envorcloudflare.config.tsis read;customruns from the workflow workspace when it exists (elsecf_workdir()), so relative--body @file/--file/--dirpaths resolve there. - Credential routing for
graphql_query(api_auth_headers): key from the storedcloudflarerow, elseCLOUDFLARE_API_TOKEN, elseCLOUDFLARE_API_KEYenv; email from the storedcloudflare_emailrow, elseCLOUDFLARE_EMAIL.cfk_+ email sendsX-Auth-Email/X-Auth-Key; any other key sendsAuthorization: Bearer;cfk_without email yields no headers and the op fails before any request. - GraphQL response: HTTP 401/403 ->
NodeUserErrornaming the required token permission; non-JSON body ->NodeUserError; status >= 400 or (datais null anderrorspresent) ->NodeUserErrorwith the first error'smessage; otherwise the whole body (including partialerrors) is returned asresult. - Failure hints (
_failure, on theNodeUserError): no login / 401 -> connect in Credentials -> Cloudflare,requires_user_action=True(plus a note when only acfk_key is stored); "More than one account" -> setaccount_id; 403 -> missing token permission; "not supported on Bun" -> the command needs Node.js 22.18+; "Zone not found" -> pass the zone ID. - Unconfirmed destructive commands: cf exits 0 with "Aborted." when a
destructive command lacks
--force;_runraises aNodeUserErrorasking for--force.dns_record_deletealways passes--force. customguards:auth login|logout|create|delete|activate|deactivateandloginare refused (sign-in belongs to the Credentials modal), as isdev(a long-running local server). A leadingcf/cloudflareword is dropped.- Output shaping (
_shape):run_cli_commandalready ranjson.loadson stdout (cf prints one pretty-printed document); when that isNone, non-empty stdout ships as text.urlis set only bycustom, and only when stdout is a single line starting withhttp. - Timeouts: 120 s for the typed CLI ops (and the zone lookup), 300 s for
custom, 60 s for the GraphQL POST.run_cli_commandkills the process tree on timeout; the wrap reportscf <command> timed out after Ns. - Error paths:
ensure_cf_cli()raising (bun missing,bun addfailing) ->NodeUserError("cf CLI install failed: ...")with a hint. Non-zero exit ->NodeUserError("cf <command> failed: <last 2000 chars of stderr>"), falling back to the envelopeerrorwhen stderr is empty.
Side Effects
- Subprocess: one
cfprocess per operation (two for a DNS op given a domain) from the project-local shim<DATA_DIR>/packages/node_modules/.bin/cf(cf.exeplus acf.bunxfile on Windows — bun's shims, never.cmd), which runs the CLI on bun (or Node when one is on PATH). The system-globalcfis never consulted. Child env is a copy of the server env plus the vars above. - Install: on first use, or when another cf version is installed,
core.js_runtime.add_package("[email protected]")—bun add --cwd <DATA_DIR>/packages --no-progress [email protected](about 300 MB with miniflare + workerd) — runs in a worker thread under an install lock. A version change also clears the Cloudflare login marker and broadcastscredential.oauth.disconnected. - Files: cf may cache the auto-selected account under
<DATA_DIR>/cloudflare/.cloudflare/cache/(or the workspace, forcustom). - External API calls: cf's own calls to
api.cloudflare.com(30 s per request, no retries);POST https://api.cloudflare.com/client/v4/graphqlwith{query, variables}(graphql_queryonly).search_commandsis local. - Credential reads:
auth_service.get_api_key("cloudflare")on every CLI call, plusget_api_key("cloudflare_email")for GraphQL. - Cost metadata: every operation declares
cost={"service": "cloudflare", "action": "<operation>", "count": 1}. - Broadcasts: standard node status via
BaseNode.execute; nothing plugin-specific beyond the upgrade marker clear. (Login / logout / status belong to the WS handlerscloudflare_login/cloudflare_logout/cloudflare_status, not to this node.) - Database writes: none by the node, apart from the upgrade marker clear.
External Dependencies
- Credentials:
CloudflareCredential(id = "cloudflare",auth = "custom").resolve()returns the optionalcloudflare_api_token(stored under the provider idcloudflare; an API token or acfk_Global API Key) andcloudflare_email. The cf OAuth login lives in cf's own profile store (<xdg-config>/cloudflare/config/default.json) and is never read by OpenCompany; the modal badge is a syntheticcli-managedmarker OAuth row written by_handlers.py. - Services: the
cfCLI (declaresengines.node >= 22; its API commands run on bun — only commands that load acloudflare.config.tsneed Node 22.18+;bunon PATH orOPENCOMPANY_BUN_BINfor the install); Cloudflare's OAuth device authorization for login (URL + code shown in the modal; see_handlers.py). - Python packages:
httpx,pydantic;services.events.run_cli_command. - Environment variables:
CLOUDFLARE_API_TOKEN,CF_API_TOKEN(ambient values honoured for ops, stripped for login / whoami / logout),CLOUDFLARE_ACCOUNT_ID,CLOUDFLARE_ZONE_ID(read by cf), andCLOUDFLARE_API_KEY/CLOUDFLARE_EMAIL(GraphQL fallback only). Set for the child:NO_COLOR,CF_DELEGATION,CF_SEND_TELEMETRY.
Edge cases & known limits
annotationsdeclaredestructive: True(dns_record_delete, andcustomcan run any destructive command with--force).ui_hints = {"outputMode": "terminal"}: text output renders preformatted; JSONresultrenders as a tree.- Lists return one page;
result_info(totals, cursors) is dropped by cf, so cursor-paginated lists (kv keys list,r2 objects list) cannot be followed past the first page from CLI output. - Project commands (
init,build,dev,deploy) need Node.js 22.18+; under bun, any command that finds acloudflare.config.tsabove its working directory fails.customruns from the workspace, so acloudflare.config.tswritten there affects latercustomcalls. - The GraphQL op ignores the cf OAuth login entirely: the token never leaves the CLI, so only a stored / ambient token or Global API Key can satisfy it.
whoamiunder a stored or ambient API token reports that token, not the OAuth login (that is why the WS status handler useslogin_env).- Argv shapes are verified only against the pinned
[email protected]; the beta CLI's surface can change between releases.
Related
- Skills using this as a tool: cloudflare-skill
- Siblings:
gcloudAction,vercelAction,githubAction- the same CLI-managed-auth pattern - Also in the deployment group:
awsAction(boto3 SDK with an IAM access key, no CLI) - Architecture docs: Cloudflare Service, Plugin System