CLI · Ephemeral ドキュメント

ephemeral は、エンジン API のコマンドラインクライアントです。実行の開始と追跡、ファイル、ワークフロー、接続の管理ができ、定義は JSON または YAML で指定できます。

インストール

macOS と Linux:

ターミナル

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

Windows (PowerShell 5.1 以降):

テキスト

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

インストーラーは、お使いのシステム向けの最新リリースを github.com/erni-works/ephemeral-cli からダウンロードし、リリースの署名付きチェックサムと照合したうえで、管理者権限なしでインストールします。インストール先は、macOS と Linux では ~/.local/bin/ephemeral、Windows では %LOCALAPPDATA%\Programs\ephemeral\bin です。特定のリリースをインストールするには EPHEMERAL_VERSION=v1.2.3 を、ディレクトリを指定するには EPHEMERAL_INSTALL_DIR を設定します。ビルドは、macOS、Linux、Windows の x86-64 と ARM64 向けに用意されています。

ターミナル

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

ephemeral update は、自身を置き換える前に、リリースの署名とチェックサムを検証します。対話的なコマンドは、1 日に 1 回、新しいバージョンがないかも確認し、1 行の通知を出力します。無効にするには EPHEMERAL_NO_UPDATE_CHECK=1 を設定します。CI では通知は表示されません。

ダッシュボードのAPI キーで API キーを作成し、保存します。login はキーを検証してから、あなただけが読み取れるユーザー設定ディレクトリに保存します。

ターミナル

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

変数	用途
`EPHEMERAL_URL`	`/v1` を除いたエンジンのベース URL。保存済みの URL より優先されます。デフォルトは `https://app.ephemer.al`。
`EPHEMERAL_API_KEY`	Bearer トークンとして送信される API キー。保存済みのキーより優先されます。保存済みのキーは、保存時に指定した URL にのみ送信されます。
`EPHEMERAL_ORGANIZATION`	任意。トークンがユーザーセッションの場合に、組織を選ぶために `X-Ephemeral-Organization` として送信されます。

ephemeral status は GET /v1/me を呼び出し、組織、ロール、予算の設定を出力します。設定を手早く確認できる方法です。特に記載がない限り、出力は JSON です。

実行

ターミナル

# インラインのプロンプトで、ローカルのファイルをアップロードしてマウントする
ephemeral run --prompt "Summarize the supplied instructions." \
  --file ./instructions.md --input '{"customer_id":"customer_123"}' --wait

# 保存済みのワークフロー
ephemeral run --workflow investigate-payment --input '{"payment_id":"pay_123"}' --max-cost-micros 500000

# ファイルに書いた完全な定義
ephemeral run run.yaml --wait

オプション	効果
`FILE`	JSON または YAML の実行定義。フラグは対応するフィールドを置き換え、`--file` は定義の files に追加します。
`--prompt TEXT`	インラインのプロンプト。`--workflow` とは併用できません。
`--workflow NAME`	保存済みのワークフローを開始します。
`--input JSON`	実行の入力。有効な JSON である必要があります。
`--file PATH`	ローカルのファイルをアップロードし、ベース名でマウントします。複数のファイルには繰り返し指定します。
`--max-cost-micros N`	実行の予算。
`--idempotency-key KEY`	実行を作成するときの `Idempotency-Key`。200 文字まで。省略するとランダムなキーが使われます。
`--wait`	1 秒ごとにポーリングし、最終的な実行を出力します。実行が成功しなかった場合は、ゼロ以外の終了コードで終了します。

実行の作成がネットワークエラーまたは 5xx レスポンスで失敗した場合、CLI は同じ冪等キーで最大 3 回まで試行します。そのため、エンジンに届いていたリクエストは、2 つ目の実行を開始せず、元の実行を返します。すべての試行が失敗した場合は、エラーにキーが表示されます。重複した実行を避けるには、そのキーを --idempotency-key に指定して、コマンドをもう一度実行してください。

待機中に Ctrl-C を押すと、CLI は待機をやめます。実行は続行されます。後から 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 は、イベント ID と名前を含む生のイベントストリームを、受信しながら出力します。runs cancel は、確認の 1 行を出力します。

ファイル

ターミナル

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

ワークフローと接続

ターミナル

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

connection.yaml

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

save は確認のメッセージを出力し、定義をそのまま表示することはありません。get と list は、認証情報のフィールドを [redacted] に置き換えます。接続の保存と読み取りには、管理者キーが必要です。connections catalog は、どのキーでも使えます。oauth connect は、認可 URL を出力してブラウザーで開きます。出力だけにするには、--no-browser を追加します。

コミットする定義ファイルには、認証情報を含めないでください。認証情報は接続に一度保存し、名前で参照してください。

スケジュール

ターミナル

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…

schedule.yaml

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 は、何も保存せずに、タイムテーブルを検証して次の 5 回の開始時刻を出力します。update は、ファイルに書かれたフィールドだけを変更します。スケジュールの作成、変更、削除には、管理者キーが必要です。スケジュールをご覧ください。

その他のコマンド

コマンド	動作
`ephemeral models`	モデルカタログを出力します。
`ephemeral api METHOD /v1/PATH [FILE]`	EPHEMERAL_URL の API に、任意のリクエストを送信します。JSON または YAML のボディを付けることもできます。
`ephemeral keys list\|create NAME [admin\|member]\|revoke ID`	セルフホストのインストールで API キーを管理します。ホスト型サービスでは利用できません。
`ephemeral help`	コマンドの一覧をすべて出力します。

ヘルプの出力にある operator コマンドは、Ephemeral のスタッフ向けで、非公開のサービス認証情報が必要です。コマンドが失敗すると、CLI は HTTP ステータスを (通常は API のエラーメッセージとともに) 出力し、終了コード 1 で終了します。

インストール

ログイン

実行

ファイル

ワークフローと接続

スケジュール

その他のコマンド