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을 설정하세요. 빌드는 x86-64와 ARM64의 macOS, Linux, Windows용으로 제공됩니다.

터미널

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

ephemeral update는 자신을 교체하기 전에 릴리스의 서명과 체크섬을 검증합니다. 대화형 명령은 하루에 한 번 새 버전이 있는지도 확인하고 한 줄짜리 안내를 출력합니다. 이를 끄려면 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입니다.

실행

터미널

# 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

옵션	효과
`FILE`	JSON 또는 YAML 실행 정의. 플래그는 해당 필드를 대체하며, `--file`은 정의의 파일 목록에 추가됩니다.
`--prompt TEXT`	인라인 프롬프트. `--workflow`와 함께 쓸 수 없습니다.
`--workflow NAME`	저장된 워크플로를 시작합니다.
`--input JSON`	실행 입력. 올바른 JSON이어야 합니다.
`--file PATH`	로컬 파일을 업로드하고 파일 이름(base name)으로 마운트합니다. 여러 파일은 반복해서 지정합니다.
`--max-cost-micros N`	실행의 예산.
`--idempotency-key KEY`	실행을 만들 때 쓰는 `Idempotency-Key`, 최대 200자. 생략하면 무작위 키를 사용합니다.
`--wait`	1초마다 폴링하다가 최종 실행을 출력합니다. 실행이 성공하지 않으면 0이 아닌 코드로 종료합니다.

실행 생성이 네트워크 오류나 5xx 응답으로 실패하면 CLI는 같은 멱등성 키로 최대 세 번까지 재시도합니다. 따라서 엔진에 이미 도달한 요청은 두 번째 실행을 시작하지 않고 원래 실행을 반환합니다. 모든 시도가 실패하면 오류에 키가 출력됩니다. 중복 실행을 피하려면 그 키를 --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은 확인 메시지 한 줄을 출력합니다.

파일

터미널

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]로 바꿉니다. 연결을 저장하고 읽으려면 admin 키가 필요하며, connections catalog는 어떤 키로도 사용할 수 있습니다. oauth connect는 인가 URL을 출력하고 브라우저에서 엽니다. 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는 시간표를 검사하고, 아무것도 저장하지 않은 채 다음 다섯 번의 시작 시각을 출력합니다. update는 파일에 있는 필드만 변경합니다. 스케줄을 만들고, 변경하고, 삭제하려면 admin 키가 필요합니다. 스케줄을 참고하세요.

기타 명령

명령	기능
`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는 보통 API의 오류 메시지와 함께 HTTP 상태를 출력하고 상태 코드 1로 종료합니다.

설치

로그인

실행

파일

워크플로와 연결

스케줄

기타 명령