Overview
The Etlworks CLI provides a unified, scriptable interface for managing every part of the Etlworks platform. It allows users to inspect, modify, and automate objects such as connections, formats, flows, schedules, tenants, users, agents, listeners, messages, data assets, SQL queries, audit logs, system metrics, and runtime controls.
This reference lists all available CLI commands, grouped by functional area.
For each command you will find:
-
Command name
-
Usage
-
Description
-
Required role (at and up) or all roles
-
Whether confirmation is required
-
Whether parallel execution is allowed
The reference is intended for ETL developers, data engineers, DevOps teams, support engineers, and administrators who use the CLI for automation, operational control, troubleshooting, and large multi-step tasks that are difficult to perform through the UI alone.
Passing Parameters to CLI Commands
CLI commands support positional and named parameters.
-
Positional parameters are passed in order, without names.
-
Named parameters use the format name=value.
If a parameter contains spaces, special characters, or structured data such as JSON, it must be enclosed in single quotes, for example:
print '{ "id": 10, "name": "Sample" }'
Named parameters follow the same rule:
connection='{ "status": "active" }'
Both single and double quotes can be escaped inside a quoted value. This allows you to preserve quotes inside JSON or text:
print '{ "message": "He said \"hello\"" }'
print "{ 'path': 'c:\\\\data\\\\file.txt' }"
If quoting is correct, the CLI will treat the entire payload as a single parameter, regardless of whitespace or internal punctuation.
Commands
Managing Flows
add-flow
Usage:
add-flow '<flowJson>'
Description: Creates a new flow from the provided JSON definition (same structure as REST).
Role: Editor
Confirmation: no
Allow parallel: yes
delete-flow
Usage:
delete-flow <flowId> [deleteConnections=true|false] [deleteSchedules=true|false]
Description: Deletes a flow by ID. Supports deleteConnections and deleteSchedules flags. Requires confirmation.
Role: Editor
Confirmation: yes
Allow parallel: yes
edit-flow
Usage:
edit-flow <flowId> '<flowJson>'
Description: Updates an existing flow using the provided JSON definition. Requires confirmation.
Role: Editor
Confirmation: yes
Allow parallel: yes
get-flow
Usage:
get-flow <id|name>
Description: Retrieve a flow definition by ID, including metadata, mappings, transformations, and nested flows
Role: Editor
Confirmation: no
Allow parallel: yes
list-flows
Usage:
list-flows [scope=all]
Description: List flows. Use scope=all to list all flows, regardless of tenant if permitted. Default scope returns flows accessible to the current tenant.
Role: Operator
Confirmation: no
Allow parallel: yes
run-flow
Usage:
run-flow <flowId> [sync=false|true] [waitIfRunning=true|false] [force=true|false] [allowParallel=false|true] [debug=true|false] [logStep=100] [emailOnSuccess=true|false] [emailOnFailure=true|false] [emailOnLastFailure=true|false] [emailMetrics=true|false] [emails=<list>] [expectedTime=<minutes>] [stopTime=<minutes>] [returnErrorCode=true|false] [disableExecutionNotifications=false|true] [repeatExpectedTimeNotifications=false|true] [checkAgentFlow=true|false] [anyFlowParameter=value ...]
Description: Runs a flow by ID. Supports all parameters available in the REST runFlow API.
Role: Operator
Confirmation: yes
Allow parallel: yes
run-flow-by-name
Usage:
run-flow-by-name <flowName> [tenant=<tenantName>] [sync=false|true] [debug=true|false] [allowParallel=false|true] [logStep=100] [returnErrorCode=true|false] [emailOnSuccess=true|false] [emailOnFailure=true|false] [emailOnLastFailure=true|false] [emailMetrics=true|false] [emails=<list>] [expectedTime=<minutes>] [stopTime=<minutes>] [disableExecutionNotifications=false|true] [repeatExpectedTimeNotifications=false|true] [anyFlowParameter=value ...]
Description: Runs a flow by name (and optional tenant).
Role: Operator
Confirmation: yes
Allow parallel: yes
stop-flow
Usage:
stop-flow <id>
Description: Attempts to stop a running flow with the given ID. Use –force to skip confirmation.
Role: Operator
Confirmation: yes
Allow parallel: yes
tail-flow-log
Usage:
tail-flow-log flowId=<id>|flowName=<name> auditId=<id|last|last-error|last-success|last-warning> [lines=100]Description: Shows the last N lines of a flow execution log. auditId selects a specific execution or the most recent one matching the given outcome.
Role: Operator
Confirmation: no
Allow parallel: yes
flow-history
Usage:
flow-history <flowId>
Description: Returns the change history for the given flow.
Role: Editor
Confirmation: no
Allow parallel: yes
flow-history-diff
Usage:
flow-history-diff <flowId>
from=<uuid|current> to=<uuid|last>
Description: Returns a diff between two versions of the flow history.
Role: Editor
Confirmation: no
Allow parallel: yes
flow-usage
Usage:
flow-usage <flowId>
Description: Returns where the flow is referenced in other flows, schedules, and agents.
Role: Editor
Confirmation: no
Allow parallel: yes
inspect-flow
Usage:
inspect-flow <flowId>
Description: Inspects a flow for potential performance and structural issues.
Role: Editor
Confirmation: no
Allow parallel: yes
flow-documentation
Usage:
flow-documentation <flow-id>
Description: Generate documentation for the specified flow.
Role: Editor
Confirmation: no
Allow parallel: yes
list-running-flows
Usage:
list-running-flows
Description: Displays all flows that are currently running.
Role: Operator
Confirmation: no
Allow parallel: yes
running-tasks
Usage:
running-tasks [tenantId=<id>]
Description: Return the list of running flow tasks for the current tenant, or for a specific tenant if tenantId is provided.
Role: Operator
Confirmation: no
Allow parallel: yes
running-tasks-aggregated
Usage:
running-tasks-aggregated tenants=<id1,id2,...|all>
Description: Return aggregated running flow tasks across multiple tenants. When tenants=all is supplied, the command returns results for all active tenants.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
flow-executions
Usage:
flow-executions [date=<YYYY-MM-DD>]
[offset=<0-30>] [tenantId=<id>] [includeMetrics=true|false]
Description: Return the list of flow executions for a specific day (date or offset) for a tenant.
Role: Administrator
Confirmation: no
Allow parallel: yes
flow-executions-aggregated
Usage:
flow-executions-aggregated tenants=<id1,id2,...|all>
[date=<YYYY-MM-DD>] [offset=<0-30>] [includeMetrics=true|false]
Description: Return aggregated flow executions across multiple tenants.
Role: Super Admin
Confirmation: no
Allow parallel: yes
flows-suspend
Usage:
flows-suspend [--persistent]
Description: Suspends new flow executions. Scheduler and manual executions are blocked. Running flows continue.
Role: Super Admin
Confirmation: yes
Allow parallel: no
flows-suspend-force
Usage:
flows-suspend-force [--persistent]
Description: Suspends new flow executions and attempts to stop running flows. Use –force to skip confirmation.
Role: Super Admin
Confirmation: yes
Allow parallel: no
flows-resume
Usage:
flows-resume
Description: Resumes flow execution. Scheduler and manual runs are enabled.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
etl-threads
Usage:
etl-threads
Description: Return ETL execution threads across all nodes, including parent and child threads, flowId, executionId, and CPU/RAM usage.
Role: Super Admin
Confirmation: no
Allow parallel: yes
copy-flow
Usage:
copy-flow <flowId|name> [to-tenant=<id|name|current> (default current)] [from-tenant=<id|name|current> (default current)] [collision=Add|Keep|Replace (default Add)] [importSchedules=true|false (default false)] [excludeCredentials=true|false (default false)]
Description: Copies a flow with ALL its connections and formats between tenants using export/import (dump). Credentials are copied by default so the copy is runnable. Use this (NOT per-artifact recreation)
Role: Editor
Confirmation: no
Allow parallel: yes
get-flow-status
Usage:
get-flow-status <id> [status]
Description: Returns the flow execution status. Optional [status] filters by last matching run.
Role: Operator
Confirmation: no
Allow parallel: yes
export-flows
Usage:
export-flows
Description:
Role: Editor
Confirmation: no
Allow parallel: yes
import-flows
Usage:
import-flows
Description:
Role: Editor
Confirmation: yes
Allow parallel: yes
Managing Connections
add-connection
Usage:
add-connection '<connection-json>'
Description: Create a new connection from a JSON payload.
Role: Editor
Confirmation: no
Allow parallel: yes
list-connections
Usage:
list-connections [scope=all]
Description: List connections. Use scope=all to list connections across all tenants, if permitted. Default scope returns connections accessible to the current tenant.
Role: Editor
Confirmation: no
Allow parallel: yes
get-connection
Usage:
get-connection <id|name>
Description: Get connection by id.
Role: Editor
Confirmation: no
Allow parallel: yes
edit-connection
Usage:
edit-connection <id> '<connection-json>'
Description: Update an existing connection using a JSON payload.
Role: Editor
Confirmation: yes
Allow parallel: yes
delete-connection
Usage:
delete-connection <id>
Description: Delete a connection by id.
Role: Editor
Confirmation: yes
Allow parallel: yes
test-connection
Usage:
test-connection <id> [agent=<agent-id>]
[action=<agent-action-id>]
Description: Test a connection by id. You can optionally provide agent and agent action ids.
Role: Editor
Confirmation: no
Allow parallel: yes
build-default-connection
Usage:
build-default-connection <connection-type>
Description: Build a new connection object using descriptor defaults for the given connection type.
Role: Editor
Confirmation: no
Allow parallel: yes
connection-history
Usage:
connection-history <connection-id>
Description: Get change history for a connection.
Role: Editor
Confirmation: no
Allow parallel: yes
connection-history-diff
Usage:
connection-history-diff <connection-id>
<from-uuid|current> <to-uuid|last>
Description: Get diff between two history versions of a connection. Use 'current' as from or 'last' as to when needed.
Role: Editor
Confirmation: no
Allow parallel: yes
find-connection-usage
Usage:
find-connection-usage <connection-id>
Description: List flows that use the specified connection.
Role: Editor
Confirmation: no
Allow parallel: yes
export-connections
Usage:
export-connections
Description:
Role: Editor
Confirmation: no
Allow parallel: yes
import-connections
Usage:
import-connections
Description:
Role: Editor
Confirmation: yes
Allow parallel: yes
list-listeners
Usage:
list-listeners [scope=all]
Description: List listeners. Use scope=all to list list-listeners across all tenants, if permitted. Default scope returns listeners accessible to the current tenant.
Role: Any authenticated user
Confirmation: no
Allow parallel: yes
Managing Formats
add-format
Usage:
add-format '<format-json>'
Description: Create a new format from a JSON payload.
Role: Editor
Confirmation: no
Allow parallel: yes
list-formats
Usage:
list-formats [scope=all]
Description: List connections. Use scope=all to list formats across all tenants, if permitted. Default scope returns formats accessible to the current tenant.
Role: Editor
Confirmation: no
Allow parallel: yes
get-format
Usage:
get-format <id>
Description: Get format by id.
Role: Editor
Confirmation: no
Allow parallel: yes
edit-format
Usage:
edit-format <id> '<format-json>'
Description: Update an existing format using a JSON payload.
Role: Editor
Confirmation: yes
Allow parallel: yes
delete-format
Usage:
delete-format <id>
Description: Delete a format by id.
Role: Editor
Confirmation: yes
Allow parallel: yes
build-default-format
Usage:
build-default-format <format-type>
Description: Build a new format using descriptor defaults for the given format type.
Role: Editor
Confirmation: no
Allow parallel: yes
format-history
Usage:
format-history <id>
Description: Get change history for a format.
Role: Editor
Confirmation: no
Allow parallel: yes
format-history-diff
Usage:
format-history-diff <id>
<from-uuid|current> <to-uuid|last>
Description: Get diff between two history versions of a format.
Role: Editor
Confirmation: no
Allow parallel: yes
find-format-usage
Usage:
find-format-usage <format-id>
Description: List flows that use the specified format.
Role: Editor
Confirmation: no
Allow parallel: yes
export-formats
Usage:
export-formats
Description:
Role: Editor
Confirmation: no
Allow parallel: yes
import-formats
Usage:
import-formats
Description:
Role: Editor
Confirmation: yes
Allow parallel: yes
Managing Schedules
add-schedule
Usage:
add-schedule '<schedule-json>'
Description: Create a new schedule from a JSON payload.
Role: Administrator
Confirmation: yes
Allow parallel: yes
list-schedules
Usage:
list-schedules [scope=all]
Description: List schedules. Use scope=all to list schedules across all tenants, if permitted. Default scope returns schedules accessible to the current tenant.
Role: Administrator
Confirmation: no
Allow parallel: yes
get-schedule
Usage:
get-schedule <id>
Description: Get schedule by id.
Role: Administrator
Confirmation: no
Allow parallel: yes
edit-schedule
Usage:
edit-schedule <id> '<schedule-json>'
Description: Update an existing schedule using a JSON payload.
Role: Administrator
Confirmation: yes
Allow parallel: yes
delete-schedule
Usage:
delete-schedule <id>
Description: Delete a schedule by id.
Role: Administrator
Confirmation: yes
Allow parallel: yes
enable-schedule
Usage:
enable-schedule <schedule-id>
Description: Enable a schedule by id.
Role: Administrator
Confirmation: yes
Allow parallel: yes
disable-schedule
Usage:
disable-schedule <schedule-id>
Description: Disable a schedule by id.
Role: Administrator
Confirmation: yes
Allow parallel: yes
is-schedule-enabled
Usage:
is-schedule-enabled <schedule-id>
Description: Check if a schedule is enabled.
Role: Administrator
Confirmation: no
Allow parallel: yes
find-flow-schedules
Usage:
find-flow-schedules <flow-id>
Description: List schedules associated with a specific flow.
Role: Administrator
Confirmation: no
Allow parallel: yes
schedule-history
Usage:
schedule-history <schedule-id>
Description: Get change history for a schedule.
Role: Administrator
Confirmation: no
Allow parallel: yes
schedule-history-diff
Usage:
schedule-history-diff <schedule-id>
<from-uuid|current> <to-uuid|last>
Description: Get diff between two history versions of a schedule. Use ‘current' as from or ‘last' as to when needed.
Role: Administrator
Confirmation: no
Allow parallel: yes
Managing Macros
add-macro
Usage:
add-macro '<json>'
Description: Add a new macro.
Role: Editor
Confirmation: no
Allow parallel: yes
list-macros
Usage:
list-macros
Description: List all macros for the current tenant.
Role: Editor
Confirmation: no
Allow parallel: yes
get-macro
Usage:
get-macro <id>
Description: Get a macro by its ID.
Role: Editor
Confirmation: no
Allow parallel: yes
edit-macro
Usage:
edit-macro <id> '<json>'
Description: Edit an existing macro.
Role: Editor
Confirmation: yes
Allow parallel: yes
delete-macro
Usage:
delete-macro <id>
Description: Delete a macro by ID.
Role: Administrator
Confirmation: yes
Allow parallel: yes
macro-history
Usage:
macro-history <id>
Description: Get history records for a macro.
Role: Editor
Confirmation: no
Allow parallel: yes
macro-history-diff
Usage:
macro-history-diff <id>
<from-uuid|current> <to-uuid|last>
Description: Get diff between two macro history versions.
Role: Editor
Confirmation: no
Allow parallel: yes
Managing Agents
add-agent
Usage:
add-agent '<agentJson>'
Description: Creates a new agent from the provided JSON definition.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-agents
Usage:
list-agents [scope=all] [extended=false|true]
Description: Lists Integration Agents installed for the current tenant. Use scope=all to list agents across all tenants (requires Tenant Admin). Use extended=true to include full agent details.
Role: Administrator
Confirmation: no
Allow parallel: yes
get-agent
Usage:
get-agent <agentId> [extended=false|true]
Description: Returns details for a specific Integration Agent by id. Use extended=true to include full configuration, including properties, ping payload, and flows.
Role: Administrator
Confirmation: no
Allow parallel: yes
edit-agent
Usage:
edit-agent <agentId> '<agentJson>'
Description: Updates an existing agent using the provided JSON definition. Requires confirmation.
Role: Administrator
Confirmation: yes
Allow parallel: yes
delete-agent
Usage:
delete-agent <agentId>
Description: Deletes an agent by ID. Requires confirmation.
Role: Administrator
Confirmation: yes
Allow parallel: yes
add-agent-action
Usage:
add-agent-action <agentId>
'<agentActionJson>'
Description: Adds an action to the specified agent and returns the action receipt.
Role: Administrator
Confirmation: yes
Allow parallel: yes
start-agent
Usage:
start-agent <agentId> [verify=true|false]
Description
Sends a request to the updater service to start the agent. If verify=true (default), the command checks that the agent is currently stopped and that the updater service is available. Returns an action receipt with the action ID.
Role: Administrator
Confirmation: yes
Allow parallel: yes
stop-agent
Usage:
stop-agent <agentId> [verify=true|false]
Description
Sends a stop request to the agent. If verify=true (default), the command checks that the agent is currently running. Returns an action receipt with the action ID.
Role: Administrator
Confirmation: yes
Allow parallel: yes
restart-agent
Usage:
restart-agent <agentId> [verify=true|false]
Description
Sends a restart request to the updater service for the specified agent. The agent is stopped and then started by the updater. If verify=true (default), the command checks that the updater service is available. Returns an action receipt with the action ID.
Role: Administrator
Confirmation: yes
Allow parallel: yes
update-agent
Usage:
update-agent <agentId> [version=<version>] [verify=true|false]
Description
Requests the updater service to update the agent to a specific version.
-
If version is not provided, the agent is updated to the latest compatible version.
-
If version is provided, it must exist in the list of available agent releases or the command fails.
-
If the agent is already on the same or a newer version than requested, the command returns status "No update required" without sending an update action.
-
If verify=true (default), the command checks that the updater service is available.
Returns an action receipt with the action ID when an update is queued, or a JSON status when no update is required.
Role: Administrator
Confirmation: yes
Allow parallel: yes
enable-agent
Usage:
enable-agent <agentId>
Description
Enables the agent in the server configuration. The agent picks up the updated configuration on the next ping. Returns a JSON response that indicates whether the enabled flag was changed.
Role: Administrator
Confirmation: yes
Allow parallel: yes
disable-agent
Usage:
disable-agent <agentId>
Description
Disables the agent in the server configuration. The agent picks up the updated configuration on the next ping. Returns a JSON response that indicates whether the enabled flag was changed.
Role: Administrator
Confirmation: yes
Allow parallel: yes
set-agent-max-ram
Usage:
set-agent-max-ram <agentId> <maxRamMb> [verify=true|false]
Description
Requests the updater service to change the agent JVM maximum heap size (Xmx) to the specified value in megabytes.
If verify=true (default), the command checks that the updater service is available.
The new setting is applied by the updater and takes effect when the agent is restarted by the updater or via a restart/start action.
Returns an action receipt with the action ID.
Role: Administrator
Confirmation: yes
Allow parallel: yes
run-agent-flow
Usage:
run-agent-flow <agentId> <flowId> [description=text] [verify=true|false]
Description: Starts a flow on the specified agent. Requires agent to be running if verify=true.
Role: Administrator
Confirmation: yes
Allow parallel: yes
stop-agent-flow
Usage:
stop-agent-flow <agentId> <flowId> [verify=true|false]
Description: Stops a flow on the specified agent. Requires agent to be running if verify=true.
Role: Administrator
Confirmation: yes
Allow parallel: yes
cancel-agent-action
Usage:
cancel-agent-action <agentId>
<actionId>
Description: Cancels the specified agent action (actionId) for the specified agent (agentId) if it is still queued.
Role: Administrator
Confirmation: yes
Allow parallel: yes
get-agent-status
Usage:
get-agent-status <agentId>
Description: Returns status and metrics for the given agent.
Role: Administrator
Confirmation: no
Allow parallel: yes
agent-history
Usage:
agent-history <agentId>
Description: Returns the change history for the given agent.
Role: Administrator
Confirmation: no
Allow parallel: yes
agent-history-diff
Usage:
agent-history-diff <agentId>
from=<uuid|current> to=<uuid|last>
Description: Returns a diff between two versions of the agent history.
Role: Administrator
Confirmation: no
Allow parallel: yes
Managing dbt Flows
The dbt command family executes saved dbt flows and reads their retained results and artifacts. Only the exact dbt execute form requires interactive confirmation (or --force); typed dbt actions and read-only result and artifact commands do not. The namespace is classified as mutating for unattended-agent authorization.
dbt execute
Usage:
dbt execute <flow> [runtimeParameter=value ...]Description: Runs a saved dbt flow with optional runtime parameters, like run-flow.
Role: Operator
Confirmation: yes (or --force)
Allow parallel: yes
dbt <command>
Usage:
dbt <build|run|test|seed|snapshot|compile|debug|list|source-freshness|docs-generate|run-operation|retry> <flow>
[select=...] [exclude=...] [vars=...] [macro=...] [args=...] [schema=...]
[threads=N] [fullRefresh=true|false] [failFast=true|false] [timeoutMs=N] [state=...]
[jobId=N] [pollIntervalMs=N] [overrideCommand=true|false]
[sync=true|false] [waitIfRunning=true|false] [allowParallel=true|false] [returnErrorCode=true|false]Description: Runs a saved dbt flow with a typed dbt action, applying the structured dbt overrides to this execution only. The saved flow is not changed. jobId, pollIntervalMs, and overrideCommand apply to dbt Platform flows.
Role: Operator
Confirmation: no
Allow parallel: yes
dbt results
Usage:
dbt results <flow> [execution=last]Description: Retrieves the normalized dbt results of a retained execution.
Role: Operator
Confirmation: no
Allow parallel: yes
dbt artifacts
Usage:
dbt artifacts <flow> [execution=last]Description: Lists the retained raw dbt artifacts of an execution.
Role: Operator
Confirmation: no
Allow parallel: yes
dbt download-artifact
Usage:
dbt download-artifact <flow> <artifact> [execution=last] [invocation=...]Description: Downloads one raw dbt artifact. Use invocation to pick one dbt invocation of a parent execution that contains several.
Role: Operator
Confirmation: no
Allow parallel: yes
dbt
Usage:
dbt execute <flow> [runtimeParameter=value ...] | dbt <command> <flow> [select=...] [exclude=...] [vars=...] [macro=...] [args=...] | dbt results <flow> [execution=last] | dbt artifacts <flow> [execution=last] | dbt download-artifact <flow> <artifact> [execution=last] [invocation=...]
Description: Executes saved dbt flows and reads their retained results and artifacts.
Role: Operator
Confirmation: no
Allow parallel: yes
Managing Webhooks
add-webhook
Usage:
add-webhook '<webhook-json>'
Description: Create a new webhook from a JSON payload.
Role: Administrator
Confirmation: yes
Allow parallel: yes
list-webhooks
Usage:
list-webhooks [scope=all]
Description: List webhooks. Use scope=all to list webhooks across all tenants, if permitted.
Role: Administrator
Confirmation: no
Allow parallel: yes
get-webhook
Usage:
get-webhook <id>
Description: Get webhook by id.
Role: Administrator
Confirmation: no
Allow parallel: yes
edit-webhook
Usage:
edit-webhook <id> '<webhook-json>'
Description: Update an existing webhook using a JSON payload.
Role: Administrator
Confirmation: yes
Allow parallel: yes
delete-webhook
Usage:
delete-webhook <id>
Description: Delete a webhook by id.
Role: Administrator
Confirmation: yes
Allow parallel: yes
get-webhook-events
Usage:
get-webhook-events <webhook-id>
Description: Get latest events for a webhook.
Role: Administrator
Confirmation: no
Allow parallel: yes
get-webhook-event
Usage:
get-webhook-event <webhook-id>
<event-id>
Description: Get a specific webhook event by ID.
Role: Administrator
Confirmation: no
Allow parallel: yes
Managing Tenants
add-tenant
Usage:
add-tenant '<tenantJson>'
Description: Creates a new tenant from the provided JSON definition.
Role: Super Admin
Confirmation: no
Allow parallel: yes
list-tenants
Usage:
list-tenants
Description: List all tenants
Role: Super Admin
Confirmation: no
Allow parallel: yes
get-tenant
Usage:
get-tenant <id>
Description: Retrieve a tenant by ID
Role: Super Admin
Confirmation: no
Allow parallel: yes
edit-tenant
Usage:
edit-tenant <tenantId>
'<tenantJson>'
Description: Updates an existing tenant using the provided JSON definition. Requires confirmation.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
Managing Users
add-user
Usage:
add-user '<userJson>' [noInvite=<true|false>]
Description: Creates a new user from the provided JSON definition.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-users
Usage:
list-users
Description: List all users visible to this administrator
Role: Administrator
Confirmation: no
Allow parallel: yes
get-user
Usage:
get-user <id>
Description: Retrieve a user by ID
Role: Administrator
Confirmation: no
Allow parallel: yes
edit-user
Usage:
edit-user <userId> '<userJson>'
Description: Updates an existing user using the provided JSON definition. Requires confirmation.
Role: Administrator
Confirmation: yes
Allow parallel: yes
Messages
list-messages
Usage:
list-messages
Description: List up to 1000 recent messages for the current tenant.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-messages-filtered
Usage:
list-messages-filtered [sender=<name>] [size=<n>]
[sizeType=<Byte|KB|MB>] [comparator=< <|=|> >] [
fromDate=<epoch>] [toDate=<epoch>] [status=<s>] [
format=<fmt>] [message=<substring>] [scheduleName=<name>]
Description: List messages using a filter (sender, size, dates, status, format, etc.).
Role: Administrator
Confirmation: no
Allow parallel: yes
get-message
Usage:
get-message <messageId>
Description: Get and pretty-print the message body for the specified message ID.
Role: Administrator
Confirmation: no
Allow parallel: yes
Managing Tags
list-tags
Usage:
list-tags [global=true|false] [include=types] [exclude=types]
Description: List all tags for the current tenant or globally. Supports optional filters
Role: Editor
Confirmation: no
Allow parallel: yes
update-tags
Usage:
update-tags '<json>'
Description: Renames or deletes tags for the current account or tenant. JSON argument required.
Role: Administrator
Confirmation: yes
Allow parallel: yes
Example:
update-tags '{"trim":true, "caseSensitive":true,
"rename":[{"oldTag":"bigquery","newTag":"google bq"}],
"delete":[{"tag":"bulk_merge"}, {"tag":"bulk_ merge"}]}'
update-all-tags
Usage:
update-all-tags '<json>'
Description: Renames or deletes tags across tenants. Super admin only. JSON argument required.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
update-tenant-tags
Usage:
update-tenant-tags <tenantId> '<json>'
Description: Renames or deletes tags for the given tenant. tenantId and JSON argument required.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
Data Access
data-get-raw
Usage:
data-get-raw connectionId=<id> object=<name> formatId=<id>
[agent=<agentId>] [action=<agentActionId>]
Description: Retrieve raw, unprocessed data from a connection object in its native format.
Role: Editor
Confirmation: no
Allow parallel: yes
data-run-sql
Usage:
data-run-sql connectionId=<id> [object=<name>] [formatId=<id>] [sql="<statement>"] [script=true|false] [agent=<agentId>] [action=<agentActionId>]
Description: Execute SQL or retrieve data from a connection object. Supports SQL databases, files, APIs, and other data sources. SQL must be eclised in double quotes.
Role: Editor
Confirmation: no
Allow parallel: yes
get-sql-history
Usage:
get-sql-history <connectionId>
Description: Get executed SQL history for the specified connection.
Role: Editor
Confirmation: no
Allow parallel: yes
data-list-fields
Usage:
data-list-fields connectionId=<id> object=<name> [formatId=<id>]
Description: List columns/fields for a table, view, or file in a connection. Returns column names, types, and metadata.
Role: Editor
Confirmation: no
Allow parallel: yes
data-list-objects
Usage:
data-list-objects connectionId=<id> [formatId=<id>]
Description: List database objects (tables, views, files) for a connection. Returns object names and types.
Role: Editor
Confirmation: no
Allow parallel: yes
Object History and Diffs
Reverting to a saved revision (10.0.0+)
The revert-* commands replace the current saved definition of an artifact with a specific historical revision and save immediately — no editor and no separate Save action. Use the matching *-history command to find the revision:
flow-history 123
revert-flow 123 <revision-uuid>
revert-flow 123 <revision-uuid> confirm=<returned-token>
The first revert invocation returns the standard confirmation challenge without saving; repeat the command with the returned token. For deliberate unattended execution, --force skips only the confirmation prompt, never permissions or validation:
revert-flow 123 <revision-uuid> --force
Rules that apply to all revert-* commands:
- History entries provide the revision uuid, modification time, author, and message. Revert requires the artifact ID and the exact revision UUID — names, current, and last are not accepted as revert selectors (current and last work in the *-history-diff commands only).
- Artifact IDs are positive integers, except Agent IDs, which are UUIDs.
- The artifact's current ID and tenant ownership are preserved. Existing history is retained, and the normal save path handles validation, auditing, history, and applicable runtime updates. The recorded change comment is "Reverted to revision <uuid> via CLI".
- Dependencies are not reverted or recreated — missing or invalid dependencies can prevent saving. Deleted artifacts cannot be reverted; use the restore-* commands below.
- Reverting a schedule applies its saved enabled state and scheduling configuration immediately. Reverting an Agent changes its saved configuration, not the software installed on the host.
- None of these operations undo data already written by flow executions.
- Requires a tenant Administrator (artifacts owned by the current tenant) or a Super Admin (any artifact, by ID, globally). Visibility of a shared or global artifact does not grant permission to revert it. These commands do not run in CLI parallel-command mode.
revert-flow
Usage:
revert-flow <flowId> <revision-uuid>
Description: Replace the current flow definition with the specified historical revision and save it immediately.
Role: Administrator
Confirmation: yes
Allow parallel: no
revert-connection
Usage:
revert-connection <connection-id> <revision-uuid>
Description: Replace the current connection definition with the specified historical revision and save it immediately.
Role: Administrator
Confirmation: yes
Allow parallel: no
revert-format
Usage:
revert-format <id> <revision-uuid>
Description: Replace the current format definition with the specified historical revision and save it immediately.
Role: Administrator
Confirmation: yes
Allow parallel: no
revert-schedule
Usage:
revert-schedule <schedule-id> <revision-uuid>
Description: Replace the current schedule with the specified historical revision, including its saved enabled state and scheduling configuration, and save it immediately.
Role: Administrator
Confirmation: yes
Allow parallel: no
revert-agent
Usage:
revert-agent <agentId> <revision-uuid>
Description: Replace the Agent’s saved configuration with the specified historical revision and save it immediately. Does not change the software installed on the Agent host.
Role: Administrator
Confirmation: yes
Allow parallel: no
revert-macro
Usage:
revert-macro <id> <revision-uuid>
Description: Replace the current macro definition with the specified historical revision and save it immediately.
Role: Administrator
Confirmation: yes
Allow parallel: no
Recycle Bin: Deleted Artifacts (10.0.0+)
These commands find and recover deleted artifacts through the Recycle Bin. Choose the right command family:
| Goal | Command family |
|---|---|
| Inspect revisions of a saved artifact | *-history |
| Replace a live artifact with a specific historical revision | revert-* |
| Find deleted artifacts | list-deleted-* |
| Recover a deleted artifact and supported missing dependencies | restore-* |
Listing deleted artifacts
The list-deleted-* commands take no arguments, are read-only, and require no confirmation. Each returns a JSON array with type, id, name, tenantId (null identifies a global artifact), subType, deleted (Unix epoch milliseconds), deletedBy, canRestore, and restoreBlockedReason.
- Artifacts that cannot currently be restored remain visible with their restoreBlockedReason.
- canRestore indicates preliminary metadata eligibility from the Recycle Bin listing. Restoration still checks dependencies and authorization, so true does not guarantee success.
- An empty authorized Recycle Bin is a successful empty JSON array with exit code 0; listing failures return a nonzero exit code.
- Connections and listeners have separate commands. Deleted schedules and standalone macros are not covered by these lists.
- No full definitions or credentials are returned.
- Tenant Administrators see only their current tenant. Super Admins see global artifacts and all tenants, even when the session is switched into a tenant. The session tenant is unchanged.
list-deleted-flows
Usage:
list-deleted-flows
Description: List deleted flows in the Recycle Bin with restore eligibility metadata.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-deleted-connections
Usage:
list-deleted-connections
Description: List deleted connections in the Recycle Bin with restore eligibility metadata.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-deleted-formats
Usage:
list-deleted-formats
Description: List deleted formats in the Recycle Bin with restore eligibility metadata.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-deleted-listeners
Usage:
list-deleted-listeners
Description: List deleted listeners in the Recycle Bin with restore eligibility metadata.
Role: Administrator
Confirmation: no
Allow parallel: yes
list-deleted-agents
Usage:
list-deleted-agents
Description: List deleted Agent configurations in the Recycle Bin with restore eligibility metadata.
Role: Administrator
Confirmation: no
Allow parallel: yes
Restoring deleted artifacts
The restore-* commands recover a deleted artifact by name or ID and save it immediately through the existing Recycle Bin transaction. Supported missing dependencies are recovered and existing dependencies are reused, so a flow restore can recover more than the flow itself.
A complete recovery:
list-deleted-flows
restore-flow id=42
restore-flow id=42 confirm=<returned-token>
For unattended execution:
restore-flow id=42 --force
Name resolution:
- Names match exactly and case-insensitively — not as substrings. Quote names containing spaces: restore-flow "Daily customer import".
- A positional selector matches either a name or an ID. Use the explicit selectors to resolve numeric-name ambiguity: restore-flow id=42 or restore-flow name="123".
- Multiple matches cause an error without restoring anything; the response lists the matching IDs and tenant IDs. Repeat with an explicit id=.
Behavior and permissions:
- The response includes status and the restored, reused, and blocked lists. It does not expose artifact definitions or credentials.
- Missing history, insufficient metadata, blocked dependencies, or authorization failures prevent recovery and return a nonzero exit code.
- There is no restore command for schedules or standalone macros — the Recycle Bin does not support them as top-level recovery types.
- Restoring an Agent recovers its saved configuration, not an installation on a machine.
- Requires a tenant Administrator (current tenant only) or a Super Admin (global artifacts and all tenants, with restoration scoped to the matched artifact's owner; the session tenant is unchanged). Visibility does not grant restore permission.
- These commands do not run in CLI parallel-command mode. --force skips only the confirmation prompt, never permissions or validation.
restore-flow
Usage:
restore-flow <name|id>
restore-flow id=<id>
restore-flow name=<name>
Description: Restore a deleted flow (and supported missing dependencies) from the Recycle Bin and save it immediately. Example: restore-flow "Daily customer import".
Role: Administrator
Confirmation: yes
Allow parallel: no
restore-connection
Usage:
restore-connection <name|id>
Description: Restore a deleted connection from the Recycle Bin and save it immediately. Example: restore-connection "Source database".
Role: Administrator
Confirmation: yes
Allow parallel: no
restore-format
Usage:
restore-format <name|id>
Description: Restore a deleted format from the Recycle Bin and save it immediately. Example: restore-format "Customer JSON".
Role: Administrator
Confirmation: yes
Allow parallel: no
restore-listener
Usage:
restore-listener <name|id>
Description: Restore a deleted listener from the Recycle Bin and save it immediately. Example: restore-listener "Order webhook".
Role: Administrator
Confirmation: yes
Allow parallel: no
restore-agent
Usage:
restore-agent <name|id>
Description: Restore a deleted Agent configuration from the Recycle Bin and save it immediately. Does not reinstall anything on a host. Example: restore-agent "Branch Agent".
Role: Administrator
Confirmation: yes
Allow parallel: no
Managing Git Repositories (10.1.0+)
Commands for working with Git Repository connections: refs, the Etlworks workspace, sync and one-step management. Every command takes the Git Repository connection's name or ID first. Commands that change the repository or the workspace need Edit on the connection. Concurrency: one Git command per workspace at a time; a second waits up to 60 seconds.
git-refs
Usage:
git-refs <connection> [json=true]
Description: Lists the repository's branches, tags and default branch.
Role: Viewer
Confirmation: no
git-status
Usage:
git-status <connection> [json=true]
Description: Shows the Etlworks workspace: the current branch, changed files, and commits to push or pull.
Role: Editor
Confirmation: no
git-diff
Usage:
git-diff <connection> [path=<file or folder>] [stat=true]
Description: Shows uncommitted changes in the workspace.
Role: Editor
Confirmation: no
git-log
Usage:
git-log <connection> [ref=<branch|tag|commit>] [path=<file or folder>] [count=20] [json=true]
Description: Shows the commit history (count up to 500).
Role: Editor
Confirmation: no
git-pull
Usage:
git-pull <connection> [branch=<name>]
Description: Brings the remote's commits into the Etlworks workspace (fast-forward only; nothing is merged). branch= switches to that branch first.
Role: Editor
Confirmation: no
git-commit
Usage:
git-commit <connection> message="text" [paths=<a,b>]
Description: Commits all workspace changes, or only paths=. Nothing is pushed.
Role: Editor
Confirmation: no
git-push
Usage:
git-push <connection>
Description: Pushes committed workspace work to the remote. Never forces: if the remote has new commits, run git-pull first.
Role: Editor
Confirmation: yes
git-branch
Usage:
git-branch <connection> name=<branch> [from=<branch|tag|commit>]
Description: Creates and pushes a branch. Never replaces an existing branch.
Role: Editor
Confirmation: yes
git-tag
Usage:
git-tag <connection> name=<tag> [ref=<branch|tag|commit>]
Description: Creates and pushes a tag — for example a release tag.
Role: Editor
Confirmation: yes
git-reset
Usage:
git-reset <connection> [branch=<name>] --force
Description: Discards uncommitted changes and unpushed commits in the Etlworks workspace: the branch goes back to the remote's. Nothing on the remote changes.
Role: Editor
Confirmation: yes
git-sync-out
Usage:
git-sync-out <connection> [branch=<name>] [path=<folder in the repository>] [project=<name>] [flows=<id|name,...>|all] [connections=nosecrets|reference|encrypted] [schedules=true|false] [clean=true|false] [message="text"]
Description: Exports flows, with everything they use, as a project to a branch, commits and pushes. The branch ends up matching Etlworks: a change made only in Git (not deployed here) is reverted, though it stays in the Git history. Run git-sync-in first, or sync out to a branch and review the pull request.
Role: Editor
Confirmation: yes
git-sync-in
Usage:
git-sync-in <connection> [ref=<branch|tag|commit>] [path=<folder in the repository>] [env=<name>] [prune=true] [takeover=true] [collision=Replace|Keep|KeepAllReplaceFlowsAndMacros] [replace=<types>] [keep=<types>] [fail=<types>] [dry-run=true] [plan-hash=<hash>] [message="text"] [json=true] [verbose=true]
Description: Deploys a project from a branch, tag or commit: plan and apply in one command. dry-run=true only shows the plan. prune=true and takeover=true need the Administrator role.
Role: Editor
Confirmation: yes (not for dry-run)
git-manage
Usage:
git-manage <connection> flows=<id|name,...>|all [path=<folder in the repository>] [project=<name>] [branch=<name>] [all-types=true] [connections=nosecrets|reference|encrypted] [schedules=true|false] [takeover=true] [message="text"]
Description: Puts flows under Git in one step: exports them with everything they use to the folder on the branch, pushes, and records them as managed in Git. The CLI equivalent of Manage in Git.
Role: Editor
Confirmation: yes
Projects: Flows as Code (10.1.0+)
Commands for exporting, validating, planning and deploying projects — from a folder, an upload, or Git — plus drift, per-object compare and revert, and per-environment values. Concurrency: one deploy per tenant and project at a time; a second waits up to 60 seconds. In the usages below, a project source is <folder>, <bundle>, upload:<id>, or git:<connection>[@<branch|tag|commit>].
project-export
Usage:
project-export <folder>|out=download [project=<name>] [flows=<id|name,...>|all] [connections=nosecrets|reference|encrypted] [schedules=true|false] [clean=true]
Description: Exports a project to a folder under the app data, or out=download for a zip.
Role: Editor
Confirmation: no
project-validate
Usage:
project-validate <source> [path=<folder in the repository>] [env=<name>] [collision=...] [replace=<types>] [keep=<types>] [fail=<types>]
Description: Checks a project's files, references, environment overrides and credentials without comparing or changing anything.
Role: Viewer
Confirmation: no
project-plan
Usage:
project-plan <source> [path=<folder in the repository>] [env=<name>] [prune=true] [takeover=true] [collision=...] [replace=<types>] [keep=<types>] [fail=<types>] [json=true] [verbose=true]
Description: Shows what a deploy would do, object by object, with diffs and a plan hash. Changes nothing.
Role: Editor
Confirmation: no
project-apply
Usage:
project-apply <source> [path=<folder in the repository>] [env=<name>] [prune=true] [takeover=true] [collision=...] [replace=<types>] [keep=<types>] [fail=<types>] [plan-hash=<hash>] [message="text"] [json=true] [verbose=true]
Description: Deploys a project in one transaction. With plan-hash=, refuses if anything changed since the plan was reviewed. Unchanged objects aren't written.
Role: Editor
Confirmation: yes
project-drift
Usage:
project-drift [project=<name>] [changed=true] [json=true]
Description: Lists managed objects and whether each changed here since its deploy. The same data as Monitor → Git drift.
Role: Viewer
Confirmation: no
project-compare
Usage:
project-compare <flow|connection|format|macro|schedule> <name|id> [json=true]
Description: Shows how one managed object differs from its deployed version. Credentials and canvas layout aren't compared.
Role: Viewer
Confirmation: no
project-revert
Usage:
project-revert <flow|connection|format|macro|schedule> <name|id> [message="text"]
Description: Re-applies the deployed version of one object. Objects it references stay as they are.
Role: Editor
Confirmation: no
project-env-init
Usage:
project-env-init <folder> env=<name> [force=true]
Description: Writes an environment file template listing the project's objects; entries left empty change nothing.
Role: Editor
Confirmation: no
project-env-set
Usage:
project-env-set <project> connection|format|flow|schedule <name> <field> value=<value> [secret=true]
Description: Stores an environment value in Etlworks (not in Git). Stored values win over the environment file; secret=true stores it encrypted and shows it as ******.
Role: Tenant Admin
Confirmation: yes
project-env-get
Usage:
project-env-get <project>
Description: Lists the overrides stored in this environment for a project (secrets hidden).
Role: Editor
Confirmation: no
project-env-unset
Usage:
project-env-unset <project> connection|format|flow|schedule <name> <field>
Description: Removes an override stored in this environment for a project.
Role: Tenant Admin
Confirmation: yes
project-encrypt-value
Usage:
project-encrypt-value connection|format|schedule <name> <field> value=<secret> [connectionType=<type>]
Description: Prints an encrypted value (enc:v1:…) to paste into an environment file instead of plain text. Not available to tenant users on shared servers.
Role: Editor
Confirmation: no
System Metrics and Monitoring
Diagnostics commands (10.0.8+)
Heap-dump capture and analysis, and CDC buffer diagnostics. See Capture and analyze heap dumps and Monitor CDC buffer pressure and latency.
core-dump
Usage:
core-dump
Description: Capture an HPROF heap dump on the engine and return its server-side path. Can pause the JVM and consume disk space. Does not capture every cluster node.
Role: Super Admin
Confirmation: yes
Allow parallel: no
analyze-heap-dump
Usage:
analyze-heap-dump <engine-hprof-path|job-id> [--top=20] [--histogram-only] [--wait=20]
Description: Start an isolated analysis of a captured HPROF dump, or poll an existing job by ID. --top accepts 1-100; --histogram-only skips retained-size and root-path analysis; --wait (0-20 seconds) applies when polling. Only regular .hprof files in the engine errors folder are accepted.
Role: Super Admin
Confirmation: yes
Allow parallel: no
heap-analysis-status
Usage:
heap-analysis-status <job-id> [--wait=20]
Description: Poll an asynchronous heap-analysis job and return its status/results. Does not start an analysis.
Role: Super Admin
Confirmation: no
Allow parallel: yes
cdc-buffers
Usage:
cdc-buffers
Description: Read CDC queue occupancy, estimated bytes, producer backpressure, and destination flush timings on the responding ETL engine node. Read-only; not a cluster or Agent aggregate. Unavailable byte measurements are null. Requires an engine with CDC buffer diagnostics support.
Role: Super Admin
Confirmation: no
Allow parallel: yes
metrics
Usage:
metrics [tenantId=<id>]
Description: Return system metrics for the current tenant, or for a specific tenant if tenantId is provided.
Role: Administrator
Confirmation: no
Allow parallel: yes
metrics-aggregated
Usage:
metrics-aggregated tenants=<id1,id2,...|all>
Description: Return aggregated metrics across multiple tenants. When tenants=all is supplied, the command returns results for all active tenants.
Role: Super Admin
Confirmation: no
Allow parallel: yes
health
Usage: health
Description: Returns system health.
Role: none
Confirmation: no
Allow parallel: yes
ai-usage-report
Usage:
ai-usage-report <from-date> [to-date] [by=user|session|model|day] OR ai-usage-report export=<session-id> [format=csv|json|md]
Description: Break down AI token usage for a date or date range to investigate a usage spike (who and what drove it). Super Admin only.
Role: Super Admin
Confirmation: no
Allow parallel: yes
disk-usage-summary
Usage:
disk-usage-summary
Description: Show disk usage summary for app.data — total/free/used space plus breakdown by tenant/directory.
Role: Super Admin
Confirmation: no
Allow parallel: yes
find-files
Usage:
find-files [name=*.log] [ext=.csv] [path=logs] [size=>10MB] [modified=>2026-01-01] [top=50] [sort=size|name|modified] [delete=true]
Description: Find files under app.data with filters for name, extension, size, and modification date. Supports comparison operators (>, <, >=, <=). Use delete=true to remove matching files (files under debezium_data are never deleted). Scoped by tenant for non-super-admins.
Role: Super Admin
Confirmation: yes
Allow parallel: yes
list-large-files
Usage:
list-large-files [top=20] [min_size=1MB] [path=logs] [ext=.log]
Description: List largest files under app.data. Scoped by tenant for non-super-admins. Useful for diagnosing disk space issues.
Role: Super Admin
Confirmation: no
Allow parallel: yes
list-errors
Usage:
list-errors [top=20] [hours=24] [flowId=123|flowName=<name>] [warnings=true]
Description: List recent flow execution errors and warnings. Shows error messages, flow names, timestamps, and audit IDs for log retrieval with tail-flow-log.
Role: Super Admin
Confirmation: no
Allow parallel: yes
thread-dump
Usage:
thread-dump [--name=<thread-name-substring>] [--thread-id=<id>] [--limit=20] [--after-thread-id=<id>]
Description: Super Admin only. Read-only live platform-thread dump using ThreadMXBean inside the responding ETL engine JVM. Returns node, capture time, complete available Java stacks, states, native-read status, locks and lock owners. Use --name=3014:666173 for an execution (includes matching worker/timer names), or --thread-id for one thread.
Role: Super Admin
Confirmation: no
Allow parallel: no
get-audit-records
Usage:
get-audit-records [fromDate=...] [toDate=...] [fromTime=...] [toTime=...] [method=...] [parameters=...] [exception=...] [user=...] [status=success|error] [duration=<ms>] [clientIp=...]
Description: Retrieve audit records using optional named parameters as filters.
Role: Administrator
Confirmation: no
Allow parallel: yes
flow-findings
Usage:
flow-findings [tenants=<id1,id2,...|all>] [status=<critical|major|medium|minor|info>] [flowId=<id>] [flowName=<text>] [tenantName=<text>] [top=<N>]
Description: Return persisted flow inspection reports that contain findings, including enriched flow and tenant data. Arguments: optional tenants=<id1,id2,...|all>, optional status=<critical|major|medium|minor|info>, optional flowId=<id>, optional flowName=<text>, optional tenantName=<text>, optional top=<N>. Super admin defaults to the main account unless tenants=all or tenant IDs are supplied.
Role: Viewer
Confirmation: no
Allow parallel: yes
resource-summary
Usage:
resource-summary
Description: Return the current Resource Usage summary for super admins. Use this command first during incident triage to discover the current cluster or node state, including per-node CPU, RAM, heap, thread counts, running flows, and supporting service status. The response includes a query block and summary block so automated agents can reason about scope.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-config
Usage:
resource-config
Description: Return the effective Resource Usage feature flags, capture cadence, and retention settings. This command is intended for administrators and automated agents to verify whether historical capture is enabled before attempting diagnostics.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-timeline
Usage:
resource-timeline [from=<ISO-8601>] [to=<ISO-8601>] [nodeId=<node>] [metric=<cpu|memory|cpu+memory|heap|threads|disk|data-disk>] [resolution=<auto|1m|15m|1h|fine|medium|coarse>]
Description: Return historical Resource Usage timeline points for a time window. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional nodeId=<node>, optional metric=<cpu|memory|cpu+memory|heap|threads|disk|data-disk>, optional resolution=<auto|1m|15m|1h|fine|medium|coarse>. If from and to are omitted, the command defaults to the last 2 hours.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-top-flows
Usage:
resource-top-flows [from=<ISO-8601>] [to=<ISO-8601>] [tenants=<id1,id2,...>] [metric=<cpu|memory|allocation>] [top=<N>]
Description: Return the most significant flows for the selected resource-usage window. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional tenants=<id1,id2,...>, optional metric=<cpu|memory|allocation>, optional top=<N>. This command is intended to answer the question: which flows were most associated with pressure during the selected time range. If from and to are omitted, the command defaults to the last 2 hours.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-executions
Usage:
resource-executions [from=<ISO-8601>] [to=<ISO-8601>] [flowId=<id>] [tenants=<id1,id2,...>] [top=<N>]
Description: Return related executions that overlap the selected Resource Usage window. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional flowId=<id>, optional tenants=<id1,id2,...>, optional top=<N>. Each result includes overlap duration, correlation tag, and execution identity fields so an automated agent can link resource evidence back to execution history.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-threads
Usage:
resource-threads [from=<ISO-8601>] [to=<ISO-8601>] [flowId=<id>] [tenants=<id1,id2,...>] [nodeId=<node>] [rootsOnly=<true|false>] [top=<N>]
Description: Return sampled ETL thread evidence for the selected Resource Usage window. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional flowId=<id>, optional tenants=<id1,id2,...>, optional nodeId=<node>, optional rootsOnly=<true|false>, optional top=<N>. Use rootsOnly=true for concise incident diagnosis because root rows already include aggregated CPU and memory for child threads.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-bottlenecks
Usage:
resource-bottlenecks [from=<ISO-8601>] [to=<ISO-8601>] [tenants=<id1,id2,...>] [top=<N>]
Description: Return an opinionated bottleneck analysis for the selected window. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional tenants=<id1,id2,...>, optional top=<N>. The command returns the hottest CPU windows, hottest memory windows, lowest disk windows, top contributing flows for CPU and memory, and related executions. Use this command when a human or AI agent needs a fast triage summary rather than raw data.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-incidents
Usage:
resource-incidents [from=<ISO-8601>] [to=<ISO-8601>] [nodeId=<node>] [status=<open|resolved|interrupted>] [resource=<cpu|ram|disk|cpu_ram|cpu_disk|ram_disk|cpu_ram_disk>] [top=<N>]
Description: Return Resource Usage incident windows for a time range, including enriched flow evidence captured during each incident. Arguments: from=<ISO-8601 instant>, to=<ISO-8601 instant>, optional nodeId=<node>, optional status=<open|resolved|interrupted>, optional resource=<cpu|ram|disk|cpu_ram|cpu_disk|ram_disk|cpu_ram_disk>, optional top=<N>. If from and to are omitted, the command defaults to the last 6 hours.
Role: Super Admin
Confirmation: no
Allow parallel: yes
resource-incident-impact
Usage:
resource-incident-impact incidentId=<id> [tenants=<id1,id2,...>]
Description: Run on-demand execution impact analysis for one Resource Usage incident. Arguments: incidentId=<id> or positional <id>, optional tenants=<id1,id2,...>. The result includes baseline and incident windows, impact indicators, summary, and top impacted flows.
Role: Super Admin
Confirmation: no
Allow parallel: yes
Administrative Runtime Controls
tail-app-log
Usage:
tail-app-log [node=<nodeId|all>] [lines=<1-100000>]Description: Returns the last lines from the most recently modified catalina*.log file on one or all application nodes, without host-level shell access. The log directory and default line count are configured under Settings → Logging. Application-node logs only — use tail-flow-log for flow executions. Super Admin only.
Role: Administrator (Super Admin)
Confirmation: no
Allow parallel: no
refresh-license
Usage:
refresh-licenseDescription: Requests an immediate license-property refresh on all live application nodes — for example after a plan change or renewal — without restarting. Super Admin only.
Role: Administrator (Super Admin)
Confirmation: no
Allow parallel: no
list-app-releases
Usage:
list-app-releases [limit]
Description
Returns a list of available Etlworks application releases. Results are sorted from newest to oldest. Limit is an optional positional parameter which defines maximum number of releases to return. Default is 10.
Role: all
Confirmation: no
Allow parallel: yes
list-agent-releases
Usage:
list-agent-releases [limit]
Description
Returns a list of available Integration Agent releases, sorted from newest to oldest. Includes version, commit, compatibility information, and release notes. Limit is an optional positional parameter which defines maximum number of releases to return. Default is 10.
Role: all
Confirmation: no
Allow parallel: yes
version
Usage:
version [extended]
Description
Shows the current Etlworks application version and ETL engine version. Use extended to include release notes, license information, and system environment details.
Role: all
Confirmation: no
Allow parallel: yes
update
Usage:
update
Description
Checks whether the currently installed Etlworks version is up to date. If a newer version is available, the command returns detailed upgrade instructions based on the deployment type (single-node or multi-node).
This command does not perform the upgrade; it only provides guidance.
The output includes:
-
currentVersion – the version currently installed
-
latestVersion – the newest version available
-
needsUpdate – whether an upgrade is required
-
multiNode – whether the deployment consists of more than one node
-
instructions – upgrade steps appropriate for Linux or Windows, including multi-node steps
-
documentation – link to the official support article for upgrading
Role: Super Admin
Confirmation: no
Allow parallel: yes
redis-persist-for-backup
Usage:
redis-persist-for-backup
Description: Persists current Redis state to disk for backup or migration using BGSAVE and verifies completion.
Role: Super Admin
Confirmation: yes
Allow parallel: no
Search
search
Usage:
search '<keywords>'
Description: Search objects in the current tenant using keywords.
Role: all
Confirmation: no
Allow parallel: yes
flow-search
Usage:
flow-search <flowId> '<search string>'
Description: Search a flow hierarchy (including nested flows) for a given string. Returns a JSON response with matching flow IDs and match count per flow.
Role: all
Confirmation: no
Allow parallel: yes
Utility Commands
Usage:
print <template>
Description: Outputs the template after all variables have been substituted.
Role: all
Confirmation: no
Allow parallel: yes
help
Usage:
help [full=false|true] [asJson=true|false]
Description: Show help for all available commands.
Role: all
Confirmation: no
Allow parallel: yes
execute-code
Usage:
execute-code code="<javascript>" [params='{"key":"value"}'] [java=true]
Description: Executes JavaScript code. Use for calculations, data transforms, and logic.
Role: Any authenticated user
Confirmation: no
Allow parallel: yes
send-mail
Usage:
send-mail to="recipient@example.com" subject="Subject line" body="Email body (HTML supported)"
Description: Send an email using the system mail service (same SMTP/API configuration as system notifications).
Role: Operator
Confirmation: no
Allow parallel: yes
list-functions
Usage:
list-functions
Description: List all built-in Etlworks function templates available for use in code transformations.
Role: Editor
Confirmation: no
Allow parallel: yes
whoami
Usage:
whoami
Description: Shows the current user's identity, role, and permissions.
Role: Any authenticated user
Confirmation: no
Allow parallel: yes
get-license-info
Usage:
get-license-info
Description: Returns license and environment information. Super Admin only.
Role: Super Admin
Confirmation: no
Allow parallel: yes