| name | umbraco-automate |
| description | Umbraco Automate operations (event-driven workflow automation) |
| metadata | {"version":"0.4.8","requires":{"bins":["umbraco"],"skills":["umbraco-shared"]}} |
automate
PREREQUISITE: Read ../umbraco-shared/SKILL.md for auth, global flags, and security rules.
umbraco automate <command> [flags]
Read Commands
| Command | Description |
|---|
automate approvals pending | List approvals waiting for a decision |
automate automation ancestors <id> | Get an automation's location (workspace and group breadcrumb) |
automate automation export <id> | Export an automation as a portable definition |
automate automation get <id> | Get an automation by ID (trigger, steps, connections, state) |
automate automation list | List automations (paginated; --skip/--take/--all) |
automate automation runs <id> | List runs for an automation (paginated; --skip/--take/--all) |
automate automation validate --workspace-id <id> --file <export.json> | Validate a new automation import server-side without writing anything |
automate catalogue actions | List action step types |
automate catalogue connection-types | List connection types |
automate catalogue control-flows | List control-flow step types |
automate catalogue notification-channels | List notification channels |
automate catalogue operators | List condition/filter operators for automation export models |
automate catalogue output-schema <alias> | Resolve a step type's dynamic output schema |
automate catalogue step-types | List step types, optionally filtered by kind |
automate catalogue triggers | List trigger step types |
automate catalogue webhook-authenticators | List webhook authenticators |
automate connection get <id> | Get a connection by ID |
automate connection list | List connections (paginated; --skip/--take/--all) |
automate metrics by-automation | Get run metrics grouped by automation |
automate metrics summary | Get run summary metrics |
automate run get <id> | Get a run by ID (per-step status, errors, retries, timing -- resolved step values are not exposed by the API) |
automate version-history compare <entity-type> <entity-id> <from-version> <to-version> | Compare two stored versions of an entity |
automate version-history get <entity-type> <entity-id> <version> | Get one stored version of an entity (the full payload as it was) |
automate version-history list <entity-type> <entity-id> | List stored versions of an entity (paginated; --skip/--take) |
automate version-history types | List the entity types that keep version history |
automate workspace get <id> | Get a workspace by ID |
automate workspace group get <workspace-id> <group-id> | Get an automation group |
automate workspace group list <workspace-id> | List automation groups in a workspace |
automate workspace list | List workspaces (paginated; --skip/--take/--all) |
approvals pending
umbraco automate approvals pending
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
automation ancestors
umbraco automate automation ancestors <id>
automation export
umbraco automate automation export <id>
GET /automations/{id}/export. The export model is the template format for 'automation validate', 'automation import', and 'automation import-update'. Filter conditions use string operators such as "NotEquals" in the lowercase operator field; Deploy .uda files use integer Operator values, so do not paste .uda condition JSON directly into import/update payloads. Use 'automate catalogue operators' for the mapping.
| Flag | Type | Default | Description |
|---|
--include | string | — | Export include option |
automation get
umbraco automate automation get <id>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
automation list
umbraco automate automation list
| Flag | Type | Default | Description |
|---|
--all | bool | false | Walk every page until exhausted (auto-paginates with --take as the page size, default 500; combine with --skip to start partway through). Bounded by an internal 100k-item ceiling. |
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--filter | string | — | Text filter |
--first-n | int | 0 | Return only the first N items from item collections |
--group-id | string | — | Group ID |
--ids-only | bool | false | Return only item IDs for item collections |
--params | string | — | Query parameters as JSON |
--skip | int | -1 | Skip count (passes through as ?skip=N; lets you walk past the server page size on large children/root collections) |
--summarize | bool | false | Return only id/name/alias fields for item collections |
--take | int | -1 | Take count (passes through as ?take=N; combine with --skip to page) |
--workspace-id | string | — | Workspace ID |
automation runs
umbraco automate automation runs <id>
| Flag | Type | Default | Description |
|---|
--all | bool | false | Walk every page until exhausted (auto-paginates with --take as the page size, default 500; combine with --skip to start partway through). Bounded by an internal 100k-item ceiling. |
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--first-n | int | 0 | Return only the first N items from item collections |
--ids-only | bool | false | Return only item IDs for item collections |
--params | string | — | Query parameters as JSON |
--skip | int | -1 | Skip count (passes through as ?skip=N; lets you walk past the server page size on large children/root collections) |
--summarize | bool | false | Return only id/name/alias fields for item collections |
--take | int | -1 | Take count (passes through as ?take=N; combine with --skip to page) |
automation validate
umbraco automate automation validate --workspace-id <id> --file <export.json>
POST /automations/import/validate. Checks an export model against a workspace -- step aliases, connection references, binding syntax -- and reports success/errors/warnings for creating/importing a new automation. It does not validate overwriting an existing automation; for edits use 'automation import-update --dry-run' to preflight the update request shape.
| Flag | Type | Default | Description |
|---|
--file | string | — | Path to an export-model JSON file (from 'automation export') |
--json | string | — | Export model as inline JSON |
--workspace-id | string | — | Workspace the definition would be imported into (required) |
catalogue actions
umbraco automate catalogue actions
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--workspace-id | string | — | Scope to one workspace |
catalogue connection-types
umbraco automate catalogue connection-types
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
catalogue control-flows
umbraco automate catalogue control-flows
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
catalogue notification-channels
umbraco automate catalogue notification-channels
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
catalogue operators
umbraco automate catalogue operators
Lists the ConditionOperator values accepted by automation export/import/update payloads. Use the string in the operator field, e.g. {"operator":"NotEquals"}; Deploy .uda files use integer Operator values, exposed here only as a mapping aid.
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
catalogue output-schema
umbraco automate catalogue output-schema <alias>
POST /catalogue/step-types/{alias}/output-schema. Steps with hasDynamicOutputSchema=true shape their output by their settings; pass the intended settings via --json to see the fields available for ${...} bindings in later steps.
| Flag | Type | Default | Description |
|---|
--json | string | — | JSON body; defaults to {"settings":{}} |
catalogue step-types
umbraco automate catalogue step-types
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--type | string | — | Step type filter |
catalogue triggers
umbraco automate catalogue triggers
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--workspace-id | string | — | Scope to one workspace |
catalogue webhook-authenticators
umbraco automate catalogue webhook-authenticators
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
connection get
umbraco automate connection get <id>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
connection list
umbraco automate connection list
| Flag | Type | Default | Description |
|---|
--all | bool | false | Walk every page until exhausted (auto-paginates with --take as the page size, default 500; combine with --skip to start partway through). Bounded by an internal 100k-item ceiling. |
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--first-n | int | 0 | Return only the first N items from item collections |
--ids-only | bool | false | Return only item IDs for item collections |
--params | string | — | Query parameters as JSON |
--skip | int | -1 | Skip count (passes through as ?skip=N; lets you walk past the server page size on large children/root collections) |
--summarize | bool | false | Return only id/name/alias fields for item collections |
--take | int | -1 | Take count (passes through as ?take=N; combine with --skip to page) |
metrics by-automation
umbraco automate metrics by-automation
| Flag | Type | Default | Description |
|---|
--from | string | — | Start date (ISO) |
--take | int | -1 | Take count |
--to | string | — | End date (ISO) |
--workspace-id | string | — | Workspace ID |
metrics summary
umbraco automate metrics summary
| Flag | Type | Default | Description |
|---|
--from | string | — | Start date (ISO) |
--to | string | — | End date (ISO) |
--workspace-id | string | — | Workspace ID |
run get
umbraco automate run get <id>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
version-history compare
umbraco automate version-history compare <entity-type> <entity-id> <from-version> <to-version>
version-history get
umbraco automate version-history get <entity-type> <entity-id> <version>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
version-history list
umbraco automate version-history list <entity-type> <entity-id>
GET /version-history/{entityType}/{entityId}. entity-type is one of 'version-history types' (e.g. Automation); entity-id is the entity's GUID. The response wraps the versions array with currentVersion/publishedVersion/totalVersions, so it does not follow the standard {items,total} envelope.
| Flag | Type | Default | Description |
|---|
--skip | int | -1 | Skip count (passes through as ?skip=N; lets you walk past the server page size on large children/root collections) |
--take | int | -1 | Take count (passes through as ?take=N; combine with --skip to page) |
version-history types
umbraco automate version-history types
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
workspace get
umbraco automate workspace get <id>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
workspace group get
umbraco automate workspace group get <workspace-id> <group-id>
workspace group list
umbraco automate workspace group list <workspace-id>
| Flag | Type | Default | Description |
|---|
--fields | string | — | Limit response fields (comma-separated top-level keys) |
workspace list
umbraco automate workspace list
| Flag | Type | Default | Description |
|---|
--all | bool | false | Walk every page until exhausted (auto-paginates with --take as the page size, default 500; combine with --skip to start partway through). Bounded by an internal 100k-item ceiling. |
--fields | string | — | Limit response fields (comma-separated top-level keys) |
--first-n | int | 0 | Return only the first N items from item collections |
--ids-only | bool | false | Return only item IDs for item collections |
--params | string | — | Query parameters as JSON |
--skip | int | -1 | Skip count (passes through as ?skip=N; lets you walk past the server page size on large children/root collections) |
--summarize | bool | false | Return only id/name/alias fields for item collections |
--take | int | -1 | Take count (passes through as ?take=N; combine with --skip to page) |
Mutation Commands
Safety: Always use --dry-run first. Remove the flag only after verifying the dry-run output.
| Command | Description |
|---|
automate approvals decide <run-id> <step-id> | Submit an approval decision for a suspended run step |
automate automation create | Create an automation (draft; publish separately) |
automate automation delete <id> | Permanently delete an automation (including its run history) |
automate automation import --workspace-id <id> --file <export.json> | Import an automation definition as a new automation |
automate automation import-update <id> --file <export.json> | Overwrite an existing automation from an export model |
automate automation publish <id> | Publish the automation's current draft so it goes live |
automate automation re-enable <id> | Re-enable an automation disabled after repeated failures |
automate automation trigger <id> | Trigger a published automation manually |
automate automation unpublish <id> | Unpublish the automation so it stops triggering |
automate automation update <id> | Update an automation |
automate connection create | Create a connection |
automate connection delete <id> | Permanently delete a connection (automations referencing it will fail) |
automate connection test <id> | Test that a connection's credentials work against the external service |
automate connection update <id> | Update a connection |
automate run replay <id> | Replay a run |
automate run resume <id> | Resume a suspended run |
automate run suspend <id> | Suspend a run |
automate run terminate <id> | Terminate a run |
automate version-history rollback <entity-type> <entity-id> <version> | Roll an entity back to a stored version |
automate workspace create | Create a workspace |
automate workspace delete <id> | Permanently delete a workspace |
automate workspace group add <workspace-id> | Add an automation group to a workspace |
automate workspace group remove <workspace-id> <group-id> | Remove an automation group from a workspace |
automate workspace group update <workspace-id> <group-id> | Rename or move an automation group |
automate workspace update <id> | Update a workspace |
approvals decide
umbraco automate approvals decide <run-id> <step-id>
| Flag | Type | Default | Description |
|---|
--comment | string | — | Approval comment |
--dry-run | bool | false | Print the planned request without executing |
--outcome | string | — | Approval outcome: Approved or Rejected |
Safe pattern:
umbraco automate approvals decide <run-id> <step-id> --dry-run
umbraco automate approvals decide <run-id> <step-id>
automation create
umbraco automate automation create
POST /automations. Required: alias, name, workspaceId (from 'workspace list'), steps (the action sequence), connections (connection GUIDs used by the steps; [] for none). trigger defines what starts the flow; step aliases come from the catalogue commands.
Creating leaves the automation as a draft -- 'automation publish ' makes it live. For building from an existing automation, prefer the export/validate/import round-trip.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Create payload as JSON |
--print-template | bool | false | Print an annotated JSON skeleton; substitute placeholders before passing to --json |
Safe pattern:
umbraco automate automation create --dry-run
umbraco automate automation create
automation delete
umbraco automate automation delete <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--force | bool | false | Confirm permanent deletion |
Safe pattern:
umbraco automate automation delete <id> --dry-run
umbraco automate automation delete <id> --force
automation import
umbraco automate automation import --workspace-id <id> --file <export.json>
POST /automations/import. Creates a new draft automation from an export model. Run 'automation validate' first -- it performs the same create/import checks without writing.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--file | string | — | Path to an export-model JSON file (from 'automation export') |
--json | string | — | Export model as inline JSON |
--workspace-id | string | — | Workspace to import into (required) |
Safe pattern:
umbraco automate automation import --workspace-id <id> --file <export.json> --dry-run
umbraco automate automation import --workspace-id <id> --file <export.json>
automation import-update
umbraco automate automation import-update <id> --file <export.json>
PUT /automations/{id}/import. Unlike 'automation import' this takes the bare export model as the body (no workspace wrapper -- the automation already lives somewhere) and replaces the automation's definition with it. Use --dry-run as the update preflight path; 'automation validate' targets only new imports and can reject existing automation IDs.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--file | string | — | Path to an export-model JSON file (from 'automation export') |
--json | string | — | Export model as inline JSON |
Safe pattern:
umbraco automate automation import-update <id> --file <export.json> --dry-run
umbraco automate automation import-update <id> --file <export.json>
automation publish
umbraco automate automation publish <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate automation publish <id> --dry-run
umbraco automate automation publish <id>
automation re-enable
umbraco automate automation re-enable <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate automation re-enable <id> --dry-run
umbraco automate automation re-enable <id>
automation trigger
umbraco automate automation trigger <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate automation trigger <id> --dry-run
umbraco automate automation trigger <id>
automation unpublish
umbraco automate automation unpublish <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate automation unpublish <id> --dry-run
umbraco automate automation unpublish <id>
automation update
umbraco automate automation update <id>
PUT /automations/{id}. The update model requires the automation's current version field for optimistic concurrency; --merge-json picks it up from the fetch automatically, making it the safe default for partial edits (e.g. renaming, tweaking one step's settings).
Updating creates a new draft version; 'automation publish ' makes it live.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Full replacement payload as JSON (fields not mentioned are reset by the server) |
--merge-json | string | — | Partial JSON deep-merged into the current resource before update (fields not mentioned are preserved) |
Safe pattern:
umbraco automate automation update <id> --dry-run
umbraco automate automation update <id>
connection create
umbraco automate connection create
POST /connections. Required: alias, name, type (from 'catalogue connection-types'), settings (the type's credential fields). Verify it works afterwards with 'connection test'.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Create payload as JSON |
--print-template | bool | false | Print an annotated JSON skeleton; substitute placeholders before passing to --json |
Safe pattern:
umbraco automate connection create --dry-run
umbraco automate connection create
connection delete
umbraco automate connection delete <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--force | bool | false | Confirm permanent deletion |
Safe pattern:
umbraco automate connection delete <id> --dry-run
umbraco automate connection delete <id> --force
connection test
umbraco automate connection test <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate connection test <id> --dry-run
umbraco automate connection test <id>
connection update
umbraco automate connection update <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Full replacement payload as JSON (fields not mentioned are reset by the server) |
--merge-json | string | — | Partial JSON deep-merged into the current resource before update (fields not mentioned are preserved) |
Safe pattern:
umbraco automate connection update <id> --dry-run
umbraco automate connection update <id>
run replay
umbraco automate run replay <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate run replay <id> --dry-run
umbraco automate run replay <id>
run resume
umbraco automate run resume <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate run resume <id> --dry-run
umbraco automate run resume <id>
run suspend
umbraco automate run suspend <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate run suspend <id> --dry-run
umbraco automate run suspend <id>
run terminate
umbraco automate run terminate <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate run terminate <id> --dry-run
umbraco automate run terminate <id>
version-history rollback
umbraco automate version-history rollback <entity-type> <entity-id> <version>
POST /version-history/{entityType}/{entityId}/{entityVersion}/rollback. The undo path after an agent edit goes wrong: pick the version from 'version-history list', confirm with 'get' or 'compare', then roll back.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
Safe pattern:
umbraco automate version-history rollback <entity-type> <entity-id> <version> --dry-run
umbraco automate version-history rollback <entity-type> <entity-id> <version>
workspace create
umbraco automate workspace create
POST /workspaces. Required: alias, name, serviceAccountKey (a backoffice user GUID automations run as), userGroups (who may edit), allowedConnections (connection GUIDs automations here may use; [] for none). Use --print-template for the shape.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Create payload as JSON |
--print-template | bool | false | Print an annotated JSON skeleton; substitute placeholders before passing to --json |
Safe pattern:
umbraco automate workspace create --dry-run
umbraco automate workspace create
workspace delete
umbraco automate workspace delete <id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--force | bool | false | Confirm permanent deletion |
Safe pattern:
umbraco automate workspace delete <id> --dry-run
umbraco automate workspace delete <id> --force
workspace group add
umbraco automate workspace group add <workspace-id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--name | string | — | Group name (required) |
--parent-id | string | — | Parent group ID for nesting |
Safe pattern:
umbraco automate workspace group add <workspace-id> --dry-run
umbraco automate workspace group add <workspace-id>
workspace group remove
umbraco automate workspace group remove <workspace-id> <group-id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--force | bool | false | Confirm permanent deletion |
Safe pattern:
umbraco automate workspace group remove <workspace-id> <group-id> --dry-run
umbraco automate workspace group remove <workspace-id> <group-id> --force
workspace group update
umbraco automate workspace group update <workspace-id> <group-id>
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--name | string | — | Group name (required) |
--parent-id | string | — | Parent group ID for nesting |
Safe pattern:
umbraco automate workspace group update <workspace-id> <group-id> --dry-run
umbraco automate workspace group update <workspace-id> <group-id>
workspace update
umbraco automate workspace update <id>
PUT /workspaces/{id}. The update model requires the workspace's current version field for optimistic concurrency; --merge-json picks it up from the fetch automatically.
| Flag | Type | Default | Description |
|---|
--dry-run | bool | false | Print the planned request without executing |
--json | string | — | Full replacement payload as JSON (fields not mentioned are reset by the server) |
--merge-json | string | — | Partial JSON deep-merged into the current resource before update (fields not mentioned are preserved) |
Safe pattern:
umbraco automate workspace update <id> --dry-run
umbraco automate workspace update <id>
Discovering Commands
umbraco automate --help
umbraco schema automate.<method>
