CLI

ephemeral est un client en ligne de commande pour l'API du moteur. Il lance et suit des exécutions, gère les fichiers, les workflows et les connexions, et accepte des définitions en JSON ou en YAML.

Installer

macOS et Linux :

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

Windows (PowerShell 5.1 ou plus récent) :

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

Le programme d'installation télécharge la dernière version pour votre système depuis github.com/erni-works/ephemeral-cli, la vérifie avec les sommes de contrôle signées de la version et l'installe sans droits d'administrateur : ~/.local/bin/ephemeral sur macOS et Linux, %LOCALAPPDATA%\Programs\ephemeral\bin sur Windows. Définissez EPHEMERAL_VERSION=v1.2.3 pour installer une version précise ou EPHEMERAL_INSTALL_DIR pour choisir le répertoire. Des builds existent pour macOS, Linux et Windows sur x86-64 et ARM64.

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

ephemeral update vérifie la signature et la somme de contrôle de la version avant de se remplacer lui-même. Une fois par jour, les commandes interactives vérifient aussi si une version plus récente existe et affichent un avis d'une ligne ; définissez EPHEMERAL_NO_UPDATE_CHECK=1 pour le désactiver. L'avis n'est jamais affiché en CI.

Se connecter

Créez une clé API sous Clés API dans le tableau de bord, puis enregistrez-la. login vérifie la clé avant de la stocker dans votre répertoire de configuration utilisateur, lisible par vous seul.

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

ephemeral status appelle GET /v1/me et affiche l'organisation, le rôle et les paramètres de budget, ce qui permet de vérifier rapidement la configuration. La sortie est en JSON, sauf indication contraire.

Exécutions

# Prompt en ligne, avec un fichier local importé et monté
ephemeral run --prompt "Summarize the supplied instructions." \
  --file ./instructions.md --input '{"customer_id":"customer_123"}' --wait

# Un workflow enregistré
ephemeral run --workflow investigate-payment --input '{"payment_id":"pay_123"}' --max-cost-micros 500000

# Une définition complète depuis un fichier
ephemeral run run.yaml --wait

Si la création de l'exécution échoue avec une erreur réseau ou une réponse 5xx, la CLI réessaie jusqu'à trois tentatives avec la même clé d'idempotence : une requête qui a bien atteint le moteur renvoie donc l'exécution d'origine au lieu d'en lancer une seconde. Si toutes les tentatives échouent, l'erreur affiche la clé ; relancez la commande avec --idempotency-key et cette clé pour éviter un doublon.

Appuyer sur Ctrl-C pendant l'attente arrête l'attente de la CLI. L'exécution continue ; consultez-la plus tard avec 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 affiche le flux d'événements brut au fur et à mesure de son arrivée, avec les ID et les noms d'événements. runs cancel affiche une ligne de confirmation.

Fichiers

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 et connexions

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 affiche une confirmation et ne renvoie jamais la définition. get et list remplacent les champs d'identifiants par [redacted]. Enregistrer et lire des connexions exige une clé admin ; connections catalog fonctionne avec n'importe quelle clé. oauth connect affiche l'URL d'autorisation et l'ouvre dans votre navigateur ; ajoutez --no-browser pour seulement l'afficher.

Planifications

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 vérifie un calendrier et affiche ses cinq prochains horaires de lancement sans rien enregistrer. update ne modifie que les champs présents dans le fichier. Créer, modifier et supprimer des planifications exige une clé admin. Voir planifications.

Autres commandes

Les commandes operator de l'aide sont destinées à l'équipe Ephemeral et exigent des identifiants de service privés. Lorsqu'une commande échoue, la CLI affiche le statut HTTP, généralement avec le message d'erreur de l'API, et se termine avec le code 1.