CLI

ephemeral é um cliente de linha de comando para a API do mecanismo. Ele inicia e acompanha execuções, gerencia arquivos, fluxos de trabalho e conexões e aceita definições em JSON ou YAML.

Instalar

macOS e Linux:

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

Windows (PowerShell 5.1 ou mais recente):

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

O instalador baixa a versão mais recente para o seu sistema em github.com/erni-works/ephemeral-cli, confere-a com os checksums assinados da versão e a instala sem direitos de administrador: ~/.local/bin/ephemeral no macOS e no Linux, %LOCALAPPDATA%\Programs\ephemeral\bin no Windows. Defina EPHEMERAL_VERSION=v1.2.3 para instalar uma versão específica ou EPHEMERAL_INSTALL_DIR para escolher o diretório. Há builds para macOS, Linux e Windows em x86-64 e ARM64.

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

ephemeral update verifica a assinatura e o checksum da versão antes de se substituir. Uma vez por dia, os comandos interativos também verificam se há uma versão mais nova e exibem um aviso de uma linha; defina EPHEMERAL_NO_UPDATE_CHECK=1 para desativar isso. O aviso nunca é exibido em CI.

Entrar

Crie uma chave de API em Chaves de API no painel e depois salve-a. O login verifica a chave antes de armazená-la no seu diretório de configuração de usuário, legível apenas por você.

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

ephemeral status chama GET /v1/me e exibe a organização, a função e as configurações de orçamento, uma forma rápida de verificar a configuração. A saída é JSON, salvo indicação em contrário.

Execuções

# Prompt em linha, com um arquivo local enviado e montado
ephemeral run --prompt "Summarize the supplied instructions." \
  --file ./instructions.md --input '{"customer_id":"customer_123"}' --wait

# Um fluxo de trabalho salvo
ephemeral run --workflow investigate-payment --input '{"payment_id":"pay_123"}' --max-cost-micros 500000

# Uma definição completa a partir de um arquivo
ephemeral run run.yaml --wait

Se a criação da execução falhar com um erro de rede ou uma resposta 5xx, a CLI tenta até três vezes com a mesma chave de idempotência, de modo que uma requisição que chegou ao mecanismo retorna a execução original em vez de iniciar uma segunda. Se todas as tentativas falharem, o erro exibe a chave; execute o comando de novo com --idempotency-key e essa chave para evitar uma execução duplicada.

Pressionar Ctrl-C durante a espera faz a CLI parar de esperar. A execução continua; consulte-a depois com 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 exibe o stream de eventos bruto conforme chega, incluindo os IDs e os nomes dos eventos. runs cancel exibe uma linha de confirmação.

Arquivos

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

Fluxos de trabalho e conexões

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 exibe uma confirmação e nunca devolve a definição. get e list substituem os campos de credenciais por [redacted]. Salvar e ler conexões exige uma chave de administrador; connections catalog funciona com qualquer chave. oauth connect exibe a URL de autorização e a abre no seu navegador; adicione --no-browser para apenas exibi-la.

Agendamentos

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 verifica uma programação e exibe seus próximos cinco horários de início sem salvar nada. update altera apenas os campos presentes no arquivo. Criar, alterar e excluir agendamentos exige uma chave de administrador. Veja os agendamentos.

Outros comandos

Os comandos operator na saída da ajuda são para a equipe do Ephemeral e exigem credenciais privadas do serviço. Quando um comando falha, a CLI exibe o status HTTP, em geral com a mensagem de erro da API, e termina com o código 1.