Skip to main content
Use this when you work in a terminal, in a script or in CI. yukta-cli is one small static binary with no runtime to install. It calls the REST API and prints the answer. The same tour for the browser is Use the web UI. Prerequisites: the client. The Linux archives and packages of a release include it next to the server, and the install script installs both. A laptop that only talks to a remote server needs the client alone: download yukta-cli-<os>-<arch> for your platform from the release page (Linux amd64 and arm64, macOS amd64 and arm64, Windows amd64), check it against SHA256SUMS, make it executable and put it on your PATH. Check it with yukta-cli --version. This page covers the tasks. Every command and flag is in CLI reference, and yukta-cli <command> --help shows the flags of one.

Connect to a server

whoami shows the name, role and sessions of your key and what it may do. The URL defaults to http://localhost:9858. A flag (--url, --token) overrides its environment variable, and the client reads no configuration file.
  • Keep the key out of shell history. --token-file <path> reads it from a file. It cannot be combined with --token.
  • Plain http to a remote host. The client refuses to send a token over plain http to a host that is not loopback. Use HTTPS, or set --insecure-token (or YUKTA_INSECURE_TOKEN=true) on a network you trust.
  • Flaky networks. --retries N repeats reads, and starts (with a generated idempotency key), on network errors, 429 and 502 to 504. --retry-wait sets the first pause, which doubles each time.
  • Machine output. -o json prints the server’s data as JSON. The default is table.

Load a workflow

session apply takes a JSON file, or inline JSON when no such file exists, and creates or replaces the session. It needs an ADMIN key. To check a definition without saving it, use yukta-cli session validate <json-or-file>.

Start a run and follow it

The trigger input is a JSON object, from --payload or from a file with --payload-file. Use --idempotency-key <key> when a start may be retried: a repeat with the same key, session and workflow returns the first execution id. Then follow it:
status shows the status, times and each node. logs streams stored lines and then live ones. result prints one JSON event per line as results reach the terminals, ending with EXECUTION_END. To follow one run to its end:
--quiet shows only problems and the end. Start the watch before the run, because the feed does not replay past events. A Ctrl-C ends a live command cleanly with exit code 0. More in Observe runs.

Steer a run

These need the OPERATOR role.
--tree includes the runs a run started as sub-workflows, which pausing the parent alone leaves running. workflow stop stops every active run of a workflow: DRAIN (the default) lets work in flight finish, CANCEL and KILL do not. yukta-cli workflow tree <execution-id> shows a run and every run it started. On one node of a live run:
retry restarts from a node that failed, as a new run. See Control a run. After a restart aborted a run, continue it with yukta-cli workflow executions recover <execution-id>. See Persist sessions.

Answer a request for input

See Ask for input.

Look around the server

These show the plugin types, the execution limits and how many runs execute and wait, the connected workers, and the newest control commands. Supervisors have their own commands: yukta-cli supervisors --help, and see Assign a supervisor.

Use it in CI

Give a CI job a key that can start and watch runs (OPERATOR) and limit it to one session, so a leaked key reaches little. Then:
--until-done exits 0 whatever the outcome, so the last line is the one that fails the job: read the status of the run. It uses the exit codes below. On failure the command prints error: <message> to standard error, and for an HTTP error the status code and the response body. --timeout (default 30s, 0 turns it off) limits each non-streaming request. Streaming commands have no time limit; set YUKTA_STREAM_IDLE (a duration, 0 turns the idle check off) and YUKTA_STREAM_RECONNECTS (a count) when a proxy buffers streams.

Verify it worked

Both answer with your key’s details and a list of plugin types. A 401 means the key is missing or wrong, and a 403 means its role does not allow the call (see Secure the server). error: ... connection refused means the URL is wrong or the server is down.

Variations that matter

  • Two servers. Keep one environment per server (a small script that exports the two variables), or pass --url and --token-file on each command.
  • No command exists. Draining the server (/api/admin/drain), templates and metrics have no command. Use the REST API. Client parity lists every task across the four clients.
  • Output you can parse. Some commands print JSON in both formats because their data is nested (session summaries, session workflow get, session workflow graph, session workflow executions).