Command reference
156 commands across 15 groups. Each row shows the command name and a one-line description; full per-command argument detail (every flag, every named param) lives in the source registry and is rolling out into per-command pages over time.
Inline SQL on JSON output
Most commands return JSON. The CLI ships a compact SQL engine that operates directly on that JSON. Use it on any read command to filter, project, sort, paginate, and transform.
| Clause | Form | Notes |
|---|
SELECT | select id, name, upper(name) as upper_name | Aliases (with or without as), DISTINCT, scalar functions, JSON paths. |
FROM | from executions · from node1.node2 | Flatten nested arrays. parent.* pulls all parent fields after flattening. |
WHERE | where status != "success" and started > ts("now - 10d") | Full expression engine: =, !=, >, >=, <, <=, AND, OR, NOT, IS [NOT] NULL, LIKE (case-insensitive), IN, BETWEEN. |
ORDER BY | order by created desc, name asc | Multi-field, asc/desc. Supports SELECT aliases. |
LIMIT | limit 10 | Standard. |
Functions
| Group | Functions |
|---|
| String | upper(s) · lower(s) · startswith(s, prefix) · endswith(s, suffix) |
| Time arithmetic (epoch ms) | addSeconds(ts, n) · addMinutes(ts, n) · addHours(ts, n) · addDays(ts, n) |
| Parsing | parseDate(text) · parseDate(text, pattern) · age(ts): "5m ago" |
| Timestamps | ts(value) · now() · date(ts) · date_only(ts) · time_only(ts) · unix(value) |
| Relative ts | ts("now - 1d") · ts("now + 12h") · ts("now - 15m") · ts("now + 20s") · ts("now - 50ms") |
Full grammar + complete function list: Built-in SQL in CLI.
Modifiers
| Modifier | Effect |
|---|
--force | Allow destructive operations without an interactive prompt. |
--silent | Suppress normal output. Errors still surface. |
--silent-if-empty | Suppress output if stdout is null or an empty array. |
--stop-on-error | Halt the script (or loop) on the first failure. |
Confirmation
Roughly 50 commands: every delete-*, every edit-*, every flow run/stop, every agent lifecycle action are flagged as destructive and require --force in scripted runs (or a y at the prompt interactively). Tagged below as (confirms).
Help & info 8 commands
| Command | Description |
|---|
help | List commands or get usage for one. Discoverable via the in-UI Command Palette too. |
version | CLI version + build info. |
whoami | Current user, role, tenant. |
health | Node-level status, memory, thread pools, service availability. |
update | Self-update the CLI engine (where supported). |
get-license-info | License tier, seats, usage caps. |
list-app-releases | Available platform releases. |
print | Print a literal value (useful in scripts with capture vars). |
Flows: define & inspect 10 commands
| Command | Description |
|---|
add-flow | Create a flow from a JSON definition. |
edit-flow | Update an existing flow from a JSON definition. (confirms) |
delete-flow | Delete a flow by id. Optional deleteConnections, deleteSchedules flags. (confirms) |
get-flow | Return the flow JSON by id. |
list-flows | List flows. Apply where + SQL clauses for filtering & projection. |
flow-search | Search a flow hierarchy (including nested flows) for a string. Returns matching flow IDs and per-flow match counts. |
find-flow-schedules | List schedules associated with a specific flow. |
flow-usage | Where this flow is referenced: other flows, schedules, agents. |
inspect-flow | Static inspection. Returns severity-ranked issues with suggestions. |
flow-documentation | Generate Markdown documentation for a flow. |
Flows: run & monitor 14 commands
| Command | Description |
|---|
run-flow | Run a flow by id. Optional sync, debug, retry/email/timeout flags + arbitrary name=value flow parameters. (confirms) |
run-flow-by-name | Run a flow by name. Optional tenant=<name>. (confirms) |
run-agent-flow | Run a flow on a specific on-prem agent. (confirms) |
stop-flow | Graceful stop of a running flow. (confirms) |
stop-agent-flow | Stop a running flow on a specific agent. (confirms) |
kill-flow | Hard stop of a running flow when graceful stop fails. |
get-flow-status | Latest run status for a flow. |
list-running-flows | Currently in-flight flows. SQL-friendly: filter by start time, tenant, etc. |
tail-flow-log | Stream the run log for an in-flight execution. |
flow-executions | Executions for a date or offset, current tenant. |
flow-executions-aggregated | Executions across multiple tenants. tenants=all for everything. |
flows-suspend | Suspend new executions (scheduler + manual). Running flows continue. (confirms) |
flows-suspend-force | Suspend AND attempt to stop running flows. Emergency stop. (confirms) |
flows-resume | Re-enable scheduler and manual executions. (confirms) |
Connections 9 commands
Payloads are metadata-driven: connectionType values like connection.db.postgres and the properties keys come from the platform's connector library. Easiest discovery: build one in the UI, then get-connection <id> to see the exact shape.
| Command | Description |
|---|
add-connection | Create from a JSON payload (single-quoted). |
edit-connection | Update from a JSON payload. (confirms) |
delete-connection | Delete by id. (confirms) |
get-connection | Return the connection JSON by id (credentials redacted). |
get-connection-raw-data | The unsanitized connection record (admin-only). |
list-connections | List connections. SQL clauses supported. |
build-default-connection | Build a connection template from a connectorType descriptor. Accelerates IaC provisioning. |
test-connection | Verify the connection (engine or specific agent). |
find-connection-usage | List flows that reference this connection. |
| Command | Description |
|---|
add-format | Create a format from a JSON payload. |
edit-format | Update a format. (confirms) |
delete-format | Delete by id. (confirms) |
get-format | Return the format JSON. |
list-formats | List formats. SQL-friendly. |
build-default-format | Build a format from descriptor defaults for the given format type. |
find-format-usage | List flows that use this format. |
Schedules 8 commands
| Command | Description |
|---|
add-schedule | Create from a JSON payload. (confirms) |
edit-schedule | Update from a JSON payload. (confirms) |
delete-schedule | Delete by id. (confirms) |
get-schedule | Return the schedule JSON. |
list-schedules | List schedules. SQL-friendly: filter by enabled, etc. |
enable-schedule | Enable a schedule. (confirms) |
disable-schedule | Disable a schedule. (confirms) |
is-schedule-enabled | Boolean check. |
Macros 5 commands
| Command | Description |
|---|
add-macro | Create a macro. |
edit-macro | Update. (confirms) |
delete-macro | Delete by id. (confirms) |
get-macro | Return the macro JSON. |
list-macros | List macros. |
Webhooks 7 commands
Webhooks are outbound: Etlworks POSTs to your URL when listed flow events fire.
| Command | Description |
|---|
add-webhook | Subscribe to flow events. (confirms) |
edit-webhook | Update a subscription. (confirms) |
delete-webhook | Unsubscribe. (confirms) |
get-webhook | Return the webhook JSON. |
list-webhooks | List subscriptions. |
get-webhook-event | One outbound delivery attempt + its HTTP response. |
get-webhook-events | List recent delivery attempts. |
| Command | Description |
|---|
list-tags | All tags in the current account. global=true for all tenants. |
update-tags | Rename / delete tags in the current account. (confirms) |
update-all-tags | Same operation across all tenants (super admin). (confirms) |
update-tenant-tags | Tag operations scoped to a specific tenant. (confirms) |
search | Plain-English search across flows, connections, formats, schedules, and other objects. |
Users & tenants 8 commands
| Command | Description |
|---|
add-user | Create a user from a JSON definition. |
edit-user | Update. (confirms) |
get-user | Return the user record. |
list-users | Users in the current tenant. |
add-tenant | Create a tenant (super admin). |
edit-tenant | Update tenant settings. (confirms) |
get-tenant | Return the tenant record. |
list-tenants | Tenants visible to the calling user. |
History, diff & revert 18 commands
Every CRUD-ed resource keeps version history. Pair *-history with *-history-diff to inspect changes between specific versions or against the current. Since 10.0.0, revert-* restores a specific revision and saves it immediately.
| Command | Description |
|---|
flow-history | Past versions of a flow. |
flow-history-diff | Diff two flow versions: flow-history-diff <flowId> from=current to=last. |
connection-history | Past versions of a connection. |
connection-history-diff | Diff two connection versions. |
format-history | Past versions of a format. |
format-history-diff | Diff two format versions. |
schedule-history | Past versions of a schedule. |
schedule-history-diff | Diff two schedule versions. |
macro-history | Past versions of a macro. |
macro-history-diff | Diff two macro versions. |
agent-history | Past versions of an agent definition. |
agent-history-diff | Diff two agent versions. |
revert-flow | Restore a flow to a revision: revert-flow <flowId> <revision-uuid>. (confirms) |
revert-connection | Restore a connection to a revision. (confirms) |
revert-format | Restore a format to a revision. (confirms) |
revert-schedule | Restore a schedule to a revision, including its saved enabled state and scheduling configuration. (confirms) |
revert-agent | Restore an Agent's saved configuration to a revision. Does not change the software installed on the host. (confirms) |
revert-macro | Restore a macro to a revision. (confirms) |
Revert rules
- Run the matching
*-history command first: it returns each revision's uuid, modification time, author and message.
- Revert takes the artifact ID and the exact revision UUID. Names are not accepted, and
current and last are selectors for *-history-diff only.
- Artifact IDs are positive integers. Agent IDs are UUIDs.
- The revert saves immediately: no editor, no separate Save. The change comment is
Reverted to revision <uuid> via CLI, and existing history is kept.
- Only the selected artifact is restored. Connections, formats and child flows it references are not reverted, and a missing dependency can block the save.
- Tenant Administrator for artifacts in the current tenant, or Super Admin for any artifact by ID. Being able to see a shared artifact does not grant permission to revert it.
- First call returns a confirmation challenge; repeat it with
confirm=<token>. --force skips only that prompt, never permissions or validation. These commands do not run in parallel-command mode.
flow-history 123
revert-flow 123 973d824c-3d0f-4d9f-8a56-decf8f08ebce
revert-flow 123 973d824c-3d0f-4d9f-8a56-decf8f08ebce confirm=<returned-token>
Recycle Bin 10 commands
Added in 10.0.0. Deleting a flow, connection, format, listener or Agent configuration moves it to the Recycle Bin; these commands find it and bring it back. Unlike revert-*, which picks a revision of a live artifact, restore-* recovers a deleted one.
| Command | Description |
|---|
list-deleted-flows | Deleted flows with restore-eligibility metadata. |
list-deleted-connections | Deleted connections. |
list-deleted-formats | Deleted formats. |
list-deleted-listeners | Deleted listeners. |
list-deleted-agents | Deleted Agent configurations. |
restore-flow | Restore a deleted flow: restore-flow <name|id>. (confirms) |
restore-connection | Restore a deleted connection. (confirms) |
restore-format | Restore a deleted format. (confirms) |
restore-listener | Restore a deleted listener. (confirms) |
restore-agent | Restore a deleted Agent configuration. Does not reinstall anything on a host. (confirms) |
Listing
The list-deleted-* commands take no arguments, are read-only and need no confirmation. Each returns a JSON array of objects with type, id, name, tenantId (null means a global artifact), subType, deleted (Unix epoch milliseconds), deletedBy, canRestore and restoreBlockedReason. Blocked items stay visible with their reason, and canRestore is preliminary metadata eligibility: a restore still runs dependency and authorization checks and can fail. An empty Recycle Bin is [] with exit code 0. Connections and listeners are listed separately, and deleted schedules and standalone macros are not covered.
Restoring
- A positional selector matches either a name or an ID. Names match exactly and case-insensitively, not as substrings: quote names with spaces, as in
restore-flow "Daily customer import".
- Use
id=<id> or name=<name> when an artifact's name is itself numeric.
- Several matches fail without restoring anything; the error lists the matching IDs and tenant IDs so you can repeat with an explicit
id=.
- Supported missing dependencies are recovered and existing ones reused, so restoring a flow can bring back more than the flow.
- The response carries
status and the restored, reused and blocked lists, and never artifact definitions or credentials.
- Tenant Administrator within the current tenant, or Super Admin across tenants. Same confirmation and
--force behavior as revert-*, and no parallel-command mode.
- There is no
restore-schedule or standalone restore-macro: the Recycle Bin does not track those as top-level recovery types.
list-deleted-flows
restore-flow id=42
restore-flow id=42 confirm=<returned-token>
Data & SQL 7 commands
Inline SQL operations on the data behind any connection, plus JavaScript for arbitrary computation.
| Command | Description |
|---|
data-run-sql | Execute SQL on a connection. data-run-sql connectionId=<id> [object=<name>] [formatId=<id>] [sql="<statement>"] [script=true|false] [agent=<agentId>]. Works against SQL databases, files, APIs, queue connections. |
data-list-objects | List objects (tables, views, files, endpoints) exposed by a connection. |
data-list-fields | List the fields/columns of one object on a connection. |
data-get-raw | Return raw, untransformed data from a connection + format. connectionId, formatId, object required. |
get-sql-history | Past SQL executed against a given connection. |
execute-code | Execute JavaScript inline. execute-code code="<js>" [params='{"k":"v"}'] [java=true]. Calculations, data transforms, custom logic. |
list-functions | The platform's built-in transformation function catalog: signatures + descriptions. |
Agents (on-prem workers) 16 commands
Manage on-prem CLI workers that execute flows on customer infrastructure. Not the AI agent, that's documented separately at /dev/ai/.
| Command | Description |
|---|
add-agent | Create an agent from a JSON definition. |
edit-agent | Update an agent. (confirms) |
delete-agent | Delete by id. (confirms) |
get-agent | Return the agent record. extended=true includes properties, ping, flows. |
get-agent-status | Status & metrics for an agent. |
list-agents | List agents. SQL-friendly: filter by enabled, by ping age, etc. |
list-agent-releases | Available agent build versions. |
enable-agent | Enable. (confirms) |
disable-agent | Disable. (confirms) |
start-agent | Start a stopped agent. (confirms) |
stop-agent | Stop a running agent. (confirms) |
restart-agent | Restart. (confirms) |
update-agent | Roll the agent to the latest build. (confirms) |
set-agent-max-ram | Adjust max heap. (confirms) |
add-agent-action | Queue an action against an agent and return the receipt. (confirms) |
cancel-agent-action | Cancel a queued action. (confirms) |
Observability & system 24 commands
| Command | Description |
|---|
metrics | Time-series metrics (current tenant). |
metrics-aggregated | Time-series across multiple tenants. |
etl-threads | ETL execution threads across all nodes: parent & child threads. |
running-tasks | Tasks in-flight on this node. |
running-tasks-aggregated | Tasks across the cluster. (confirms) |
resource-config | Resource configuration snapshot. |
resource-summary | Resource utilization summary. |
resource-executions | Executions broken out by resource. |
resource-bottlenecks | Detected bottlenecks ranked by impact. |
resource-threads | Thread-pool utilization. |
resource-timeline | Resource usage over time. |
resource-top-flows | Flows consuming the most resources. |
get-audit-records | Audit log entries with optional filters (resourceType, userId, action, since). |
list-errors | Recent error events. |
disk-usage-summary | Total / free / used space for app.data with breakdown by tenant / directory. |
find-files | Find files under app.data by name, extension, size, modification date. (confirms) |
list-large-files | Files exceeding a size threshold. |
list-listeners | Listener connections (HTTP / Kafka / SQS / MQTT) currently registered. |
list-messages | Inbound listener messages. |
list-messages-filtered | Filter messages by message body, format, status. |
get-message | Pull the full body of a single message. |
send-mail | Send an email through the platform's mailer. |
tail-app-log | Last lines of the application log, on one node or all: tail-app-log [node=<nodeId|all>] [lines=<1-100000>]. Application nodes only, use tail-flow-log for executions. Super Admin. |
refresh-license | Refresh license properties on all live application nodes, after a renewal or plan change, without a restart. Super Admin. |
Per-command pages are rolling out
The reference above gives you discovery + a one-line description for every command. Full per-command argument reference (every flag, every named param, return shapes) is being extracted into dedicated pages over time. In the meantime, in-CLI: help <command-name> always returns the canonical usage string from the registry.