CLI

ephemeral es un cliente de línea de comandos para la API del motor. Inicia y sigue ejecuciones, gestiona archivos, flujos de trabajo y conexiones, y acepta definiciones en JSON o YAML.

Instalar

macOS y Linux:

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

Windows (PowerShell 5.1 o posterior):

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

El instalador descarga la última versión para tu sistema desde github.com/erni-works/ephemeral-cli, la comprueba con las sumas de verificación firmadas de la versión y la instala sin derechos de administrador: ~/.local/bin/ephemeral en macOS y Linux, %LOCALAPPDATA%\Programs\ephemeral\bin en Windows. Establece EPHEMERAL_VERSION=v1.2.3 para instalar una versión concreta o EPHEMERAL_INSTALL_DIR para elegir el directorio. Hay compilaciones para macOS, Linux y Windows en x86-64 y ARM64.

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

ephemeral update verifica la firma y la suma de verificación de la versión antes de reemplazarse a sí mismo. Una vez al día, los comandos interactivos también buscan una versión más reciente e imprimen un aviso de una línea; establece EPHEMERAL_NO_UPDATE_CHECK=1 para desactivarlo. El aviso nunca se muestra en CI.

Iniciar sesión

Crea una clave de API en Claves de API en el panel y guárdala. login comprueba la clave antes de almacenarla en tu directorio de configuración de usuario, legible solo por ti.

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

ephemeral status llama a GET /v1/me e imprime la organización, el rol y los ajustes de presupuesto, una forma rápida de comprobar la configuración. La salida es JSON salvo que se indique lo contrario.

Ejecuciones

# 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

Si la creación de la ejecución falla por un error de red o una respuesta 5xx, la CLI reintenta hasta tres veces con la misma clave de idempotencia, de modo que una solicitud que sí llegó al motor devuelve la ejecución original en lugar de iniciar una segunda. Si todos los intentos fallan, el error imprime la clave; vuelve a ejecutar el comando con --idempotency-key y esa clave para evitar una ejecución duplicada.

Pulsar Ctrl-C mientras espera hace que la CLI deje de esperar. La ejecución continúa; compruébala más tarde con 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 imprime el flujo de eventos sin procesar a medida que llega, con los IDs y nombres de los eventos. runs cancel imprime una línea de confirmación.

Archivos

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

Flujos de trabajo y conexiones

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 imprime una confirmación y nunca devuelve la definición. get y list sustituyen los campos de credenciales por [redacted]. Guardar y leer conexiones requiere una clave de administrador; connections catalog funciona con cualquier clave. oauth connect imprime la URL de autorización y la abre en tu navegador; añade --no-browser para solo imprimirla.

Programaciones

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 comprueba una programación e imprime sus próximas cinco horas de inicio sin guardar nada. update cambia solo los campos del archivo. Crear, modificar y eliminar programaciones requiere una clave de administrador. Consulta programaciones.

Otros comandos

Los comandos operator de la salida de ayuda son para el personal de Ephemeral y requieren credenciales de servicio privadas. Cuando un comando falla, la CLI imprime el estado HTTP, normalmente con el mensaje de error de la API, y termina con el código 1.