Quickstart

The Etlworks CLI is built into the platform, no install, no credential management. Open it, write a statement, hit Ctrl+Enter. Same engine drives POST /v1/cli for automation.

Open the CLI

Sign in to Etlworks. Open CLI from the main navigation panel. The console runs entirely inside the platform under your user identity, no separate auth, no API key to manage.

The interface

• Command Editor: top pane. Write and edit one or many statements (separate with ;).
• Command Palette: searchable list of every available command.
• History: full execution history with timestamps. Re-run, copy, audit.
• Output Panel: JSON output, SQL-transformed tables, errors, logs, captured values.

Keyboard shortcuts

Your first script

Confirm identity, list flows tagged production, and dump one flow's configuration to a file:

whoami;
list-flows where tags = "production";
get-flow 12345 >> backup/flow-12345.json;

Hit Ctrl + Enter. Each statement runs in order; output panel shows three blocks: user info, the filtered flow list, and a confirmation that the file was written under the tenant's data folder.

Statements & comments

The CLI is a statement-based execution engine. A script is one or more statements; each ends with ; when there's more than one. Comments use // for single-line and /* … */ for multi-line.

// Single statement, no semicolon needed
list-connections

// Multiple statements — semicolons required between them
list-connections; list-flows;

/*
  Multi-line comment.
  Useful for documenting longer scripts.
*/
list-tenants;

Parameters & quoting

Every command follows the same shape:

command-name positional1 'positional2 with spaces'
             param1=value param2='value with spaces'
             --modifier1 --modifier2
             select … from … where … order by … limit …
             | capture var=stdout.field
             & >> relative/path/name.json;

Positional args come first, named key=value args follow in any order. Wrap any value containing spaces, special characters, or JSON in quotes: single or double, both work, and inner quotes can be escaped:

print '{ "id": 10, "name": "Sample" }';
print '{ "message": "He said \"hello\"" }';
print "{ 'path': 'c:\\\\data\\\\file.txt' }";

Modifiers

Modifiers go after the command name and before any SQL or capture clause:

list-flows --silent select id where flowType like '%cdc%' | capture cdc=stdout;

Capture variables

Pipe a command's JSON output into a variable, then reference it later as {name}. Capture works on whole results, single fields, or arrays.

// Single field
get-connection 120 | capture connId=stdout.id;

// Multiple fields in one capture
get-connection 120 | capture id=stdout.id name=stdout.connection.name;

// Capture an entire array — then iterate
list-tenants | capture tenants=stdout;
for-each (t in tenants) {
  print 't.name';
};

// Use captured values inside JSON
print '{"id":"{id}","name":"{name}"}';

Control structures

if and for-each are built into the language.

// if — full boolean expressions, comparisons, JSON-path access
if ({connId} == 100) {
  print 'Matched';
};

// for-each over arrays
for-each (tenant in tenants) {
  print 'tenant.email';
};

// Nested loops + per-iteration commands
for-each --stop-on-error (agent in agents) {
  update-agent {agent.id} --force;
};

Loops continue on per-iteration errors by default (consistent with the script-wide default). Add --stop-on-error on the loop itself to halt on the first failure.

Parallel execution

Append & to run a command asynchronously: the script keeps going without waiting:

// Fire and forget
run-flow 100 &;

// With timeout
run-flow 200 timeout=15000 &;

// Combined with redirect
get-flow 100 & >> f100.json

Default cap is 10 parallel commands per request (server-side cli.max.parallel).

Redirecting output

Append >> filename at the end of any statement to save its stdout to a file under the tenant's application data directory. Subfolders are auto-created. Absolute paths are not allowed.

// Save all flows
list-flows >> flows.json

// Subfolder
list-connections >> exports/conn-list.json

// Filename from a captured variable
list-flows --silent where name like "%script%" | capture flows=stdout;
for-each (f in flows) {
  get-flow {f.id} >> backup/{f.name}.json;
};

// Combined with inline SQL
list-flows select id,name where flowType like '%cdc%' >> cdc.json

Inline SQL on JSON output

Most commands return JSON. The CLI ships a compact SQL engine that operates directly on that JSON: SELECT, FROM (array flattening), WHERE, ORDER BY, LIMIT, plus scalar & time-helper functions.

list-connections scope=all
  select id, name, connectionType, date(created) as created
  where connectionType like '%mysql%'
  order by created desc
  limit 10;

flow-executions-aggregated offset=5
  select flowId, auditId, started, ended, status
  from executions
  where status != 'success'
    and started > ts("now - 10d")
  order by ended desc
  limit 10;

Time helpers like ts("now - 1d"), addDays(ts, n), parseDate(text, pattern), plus string/aggregate utilities are documented in the SQL reference. The full SQL grammar comes from the Built-in SQL in CLI support article, we mirror the highlights, that page has the exhaustive function list.

Exit codes & output

Each statement returns a CliResponse:

The REST endpoint returns an array of these: one per statement.

Confirmation for destructive operations

Roughly 50 commands require explicit confirmation: every delete-*, every edit-*, flows-suspend, flows-resume, run-flow, agent lifecycle commands. Pass --force to confirm inline; without it, interactive runs prompt and scripted runs return exitCode=1 with a "confirmation required" message.

// In a script:
delete-flow 12345 --force;

// Bulk:
list-flows where name like '%test cdc%' | capture flows=stdout;
for-each (f in flows) {
  delete-flow {f.id} deleteSchedules=true --force;
};

Roles & permissions

Commands run as the calling user. Each command requires at least a particular role; the CLI inherits your role and tenant scope: same boundary as the UI and REST API.

Driving from REST

Same engine, same commands, programmatic. POST /v1/cli takes a CliRequest with the script as a single string and an optional variable map. Returns an array of CliResponse objects: one per statement.

curl -s -X POST "$ETLWORKS_URL/v1/cli" \
  -H "Authorization: Bearer $ETLWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "list-flows --silent where tags = \"production\" | capture flows=stdout; for-each (f in flows) { get-flow {f.id} >> backup/{f.name}.json; };",
    "vars": {}
  }'
# → [
#   { "command": "list-flows ...", "stdout": "...", "stderr": "", "exitCode": 0 },
#   { "command": "get-flow 12345 >> backup/...", "stdout": "...", "stderr": "", "exitCode": 0 },
#   ...
# ]

The vars map is the REST equivalent of CLI {var} interpolation: the script references {flowName}, the request supplies "vars": {"flowName": "Stripe to Snowflake"}. Auth is the same Bearer token used by the REST API: an API key (long-lived) or a JWT (mint via POST /v1/token-auth).