Overview

The CLI API provides programmatic access to the full Etlworks CLI engine. Anything that can be executed in the in-browser CLI console can also be executed remotely over HTTPS. This includes:

inspecting and filtering Etlworks metadata
running flows and orchestrating multi-step workflows
querying data associated with connections, formats, and endpoints
executing multi-line scripts with variables, conditions, and loops
applying SQL-like operators to JSON output
running commands in parallel inside a single request

The API is a single entry point that allows external systems to automate complex Etlworks tasks without creating custom flows or scripts. It is suitable for CI/CD pipelines, scheduling systems, DevOps automation, infrastructure provisioning, and integration with third-party platforms.

Important Note:

The CLI API is stateless. Each call executes a full script and returns all results. It does not persist state across calls. Variables, scopes, and loop context are available only within the current request.

Authentication

All CLI API calls require a valid JWT access token.

Step 1. Obtain a token

Call the authentication endpoint using any Etlworks user. The returned token is valid for a short period of time.

Step 2. Call the CLI API

Include the token in the header:

Authorization:Bearer access-token

API Endpoints

Both endpoints are located under:

/rest/v1/cli

Execute CLI Script

PATH:

POST /rest/v1/cli

DESCRIPTION:

Executes one or multiple CLI commands as a single script.

HEADERS:

Authorization:Bearer access-token 
Content-Type:application/json

REQUEST BODY MODEL: CliRequest

{
   "command": "full CLI script here"
   "vars": {
       "variableName": "value" 
   }
}

Fields

Field	Type	Description
command	string	Full CLI script to execute
vars	map<string, string>	Optional top-level variables injected into the CLI execution context

Variables

The optional vars field allows passing top-level variables into the CLI execution context.

Each entry in the vars map defines a variable that can be referenced anywhere in the CLI script using the {variableName} syntax. Variables are resolved at runtime and are available throughout the entire script, including commands, conditions, loops, and expressions.

Variables exist only for the duration of the request and are not persisted across calls.

For a detailed explanation of CLI variables, including scope rules and examples, read this article.

Example Request without variables

{
     "command": "connections list | capture c=stdout; for-each (x in c.items) print \"{x.name}\""
}

Example Request with variables

{

  "command": "run-flow {flowId} sync={sync}"
  "vars": {
    "flowId": "12345",
    "sync": "true"
  }
}

In this example:

{flowId} and {sync} are substituted before executing the run-flow command

Example Response

The response is a list of CliResponse entries, one per executed command.

[
   {
     "command": "connections list",
     "stdout": "[{\"name\":\"MySQL\",\"type\":\"database\"}]",
     "stderr": "",
     "exitCode": 0
   },
   {
     "command": "print \"MySQL\"",
     "stdout": "MySQL",
     "stderr": "",
     "exitCode": 0
   }
]

Response Model

Each item is a CliResponse:

Field	Type	Description
command	string	The CLI command that was executed
stdout	string	Standard output of the command
stderr	string	Standard error of the command
exitCode	integer	Zero if success, nonzero if error

Errors do not terminate the request unless the script explicitly uses --stop-on-error.

List Available Commands