CLI

ephemeral is a command-line client for the engine API. It starts and follows runs, manages files, workflows and connections, and accepts definitions in JSON or YAML.

Install

macOS and Linux:

curl -fsSL https://ephemer.al/install.sh | sh

Windows (PowerShell 5.1 or later):

irm https://ephemer.al/install.ps1 | iex

The installer downloads the latest release for your system from github.com/erni-works/ephemeral-cli, checks it against the release's signed checksums and installs it without administrator rights: ~/.local/bin/ephemeral on macOS and Linux, %LOCALAPPDATA%\Programs\ephemeral\bin on Windows. Set EPHEMERAL_VERSION=v1.2.3 to install a particular release or EPHEMERAL_INSTALL_DIR to choose the directory. Builds exist for macOS, Linux and Windows on x86-64 and ARM64.

ephemeral version
ephemeral update            # install the latest release
ephemeral update --check    # only report whether one is available

ephemeral update verifies the release's signature and checksum before replacing itself. Once a day, interactive commands also check for a newer version and print a one-line notice; set EPHEMERAL_NO_UPDATE_CHECK=1 to turn this off. The notice is never shown in CI.

Sign in

Create an API key under Keys in the dashboard, then save it. login checks the key before storing it in your user configuration directory, readable only by you.

ephemeral login                                  # paste the key; it is not shown
ephemeral login --url https://ephemeral.example.com  # a self-hosted installation
ephemeral status

ephemeral status calls GET /v1/me and prints the organization, role and budget settings, which is a quick way to check the configuration. Output is JSON unless noted.

Runs

# Inline prompt, with a local file uploaded and mounted
ephemeral run --prompt "Summarize the supplied instructions." \
  --file ./instructions.md --input '{"customer_id":"customer_123"}' --wait

# A saved workflow
ephemeral run --workflow investigate-payment --input '{"payment_id":"pay_123"}' --max-cost-micros 500000

# A complete definition from a file
ephemeral run run.yaml --wait

If creating the run fails with a network error or a 5xx response, the CLI retries up to three attempts with the same idempotency key, so a request that did reach the engine returns the original run instead of starting a second one. If every attempt fails, the error prints the key; run the command again with --idempotency-key and that key to avoid a duplicate run.

Pressing Ctrl-C while waiting stops the CLI from waiting. The run continues; check it later with ephemeral runs get ID.

ephemeral runs list --limit 20 --status succeeded
ephemeral runs get run_4abb0f420c6623a12d2889610eb67284
ephemeral runs events run_4abb0f420c6623a12d2889610eb67284
ephemeral runs cancel run_4abb0f420c6623a12d2889610eb67284
ephemeral runs definition run_4abb0f420c6623a12d2889610eb67284

runs events prints the raw event stream as it arrives, including event IDs and names. runs cancel prints a confirmation line.

Files

ephemeral files upload instructions.md --name guides/instructions.md
ephemeral files list
ephemeral files download file_9c41d2a07be35f1e8a6c0d4b9e2f7a13 > instructions.md
ephemeral files rename file_9c41d2a07be35f1e8a6c0d4b9e2f7a13 playbook.md
ephemeral files delete file_9c41d2a07be35f1e8a6c0d4b9e2f7a13

Workflows and connections

ephemeral workflows save investigate-payment workflow.yaml
ephemeral workflows list
ephemeral workflows get investigate-payment
ephemeral workflows delete investigate-payment

ephemeral connections catalog
ephemeral connections save payments-api connection.yaml
ephemeral connections list
ephemeral connections get payments-api
ephemeral connections delete payments-api
ephemeral oauth connect payments-api

type: http
url: https://api.example.com/v2
auth:
  type: bearer
  token: sk_live_…
allowed_methods: [GET]

save prints a confirmation and never echoes the definition back. get and list replace credential fields with [redacted]. Saving and reading connections needs an admin key; connections catalog works with any key. oauth connect prints the authorization URL and opens it in your browser; add --no-browser to only print it.

Schedules

ephemeral schedules preview "0 9 * * 1-5" Asia/Tokyo
ephemeral schedules create schedule.yaml
ephemeral schedules list --workflow welcome-new-customers
ephemeral schedules run sch_4f9c…
ephemeral schedules pause sch_4f9c…
ephemeral schedules resume sch_4f9c…
ephemeral schedules update sch_4f9c… changes.yaml
ephemeral schedules delete sch_4f9c…

workflow: welcome-new-customers
name: Weekday welcome emails
cron: "0 9 * * 1-5"
timezone: Asia/Tokyo
input:
  signed_up: yesterday
max_cost_micros: 200000

preview checks a timetable and prints its next five start times without saving anything. update changes only the fields in the file. Creating, changing and deleting schedules needs an admin key. See schedules.

Other commands

The operator commands in the help output are for Ephemeral staff and need private service credentials. When a command fails, the CLI prints the HTTP status, usually with the API's error message, and exits with status 1.