Pular para o conteúdo
Página inicial da Latchkey
Comece grátis
Menu da documentação

Execute jobs avulsos pela CLI

Execute qualquer comando em um runner novo do Latchkey a partir do seu terminal ou agente de codificação: a CLI empacota sua árvore de trabalho, transmite os logs de volta e sai com o código de saída do próprio comando.

Resumo

  1. npm install -g @latchkeydev/cli, depois latchkey run 'npm ci && npm test' executa o comando em um runner novo do Latchkey e sai com o código de saída do próprio comando.
  2. Sua árvore de trabalho é enviada com o job: as regras de .gitignore se aplicam, --exclude retém mais coisas, arquivos com formato de credencial são retidos por padrão, e .latchkeyignore sobrepõe os três.
  3. Os jobs são cobrados como minutos de runner comuns, do mesmo pool de minutos gratuitos; o gasto deles aparece como uma linha própria CLI jobs na página Cost.
  4. Requer uma chave de API que possa executar jobs. Um proprietário ou administrador cria uma em Settings, API keys and agents e escolhe CLI runner em Access. Agentes de codificação usam a mesma superfície pela ferramenta MCP run_job.

A CLI do Latchkey (@latchkeydev/cli) transforma uma máquina de CI nova em algo que você invoca como um comando local. latchkey run 'npm ci && npm test' empacota sua árvore de trabalho, executa o comando em um runner isolado do Latchkey, transmite a saída para o seu terminal e sai com o código de saída do próprio comando. O upload deixa de fora o que o seu .gitignore ignora, como node_modules, então o comando instala as dependências primeiro. Isso a torna um ciclo de verificação que você pode automatizar em scripts: execute a checagem do jeito que o CI vai executá-la, em uma máquina Linux limpa, antes de fazer o push. Ela foi feita para verificação antes do push, para reproduzir falhas que só acontecem no CI (workspace limpo, instalações do zero, Linux) e para agentes de codificação, que a conduzem como qualquer outro comando de shell.

acme-api · zsh · latchkey run

Em um terminal em ~/acme-api, o comando latchkey run 'npm test' imprime: Packing context from /Users/me/acme-api..., Packed 412 file(s), 3.1 MB compressed., Created job cli-6f0e8a3c-6a3e-4a7e-9d5f-0f1c2b3a4d5e., o link para o job no dashboard, Uploading context (3.1 MB)..., Context uploaded., Submitted; state: queued. e depois state: provisioning. O log do job volta em streaming: as duas linhas [latchkey] do agente do job, state: running e a saída do npm test, que termina com 412 testes aprovados. Ele termina com state: succeeded e Job cli-6f0e8a3c-6a3e-4a7e-9d5f-0f1c2b3a4d5e succeeded (exit 0).

FIG. 3.4-Alatchkey run 'npm test' empacota a árvore de trabalho, inicia um job em um runner novo e transmite o log de volta. O progresso do próprio CLI (esmaecido aqui) vai para o stderr, a saída do job para o stdout, e o comando termina com o código de saída do job.

Instale e autentique-se#

01
Instale a CLI

Instale globalmente com npm (Node 20.18.1 ou mais recente), ou execute-a de forma avulsa com npx @latchkeydev/cli. Instale o nome de pacote com escopo: o pacote latchkey sem escopo no npm é um projeto sem relação.

terminal
1npm install -g @latchkeydev/cli
2latchkey --help
02
Crie uma chave de API habilitada para jobs

Um proprietário ou administrador cria uma em Settings, API keys and agents e escolhe CLI runner em Access. As capacidades são fixadas na criação: uma chave existente nunca as ganha retroativamente. A chave completa (ela começa com lk_live_) é exibida uma única vez.

03
Faça login

latchkey login valida a chave sem iniciar nada cobrável e a salva para esta máquina (~/.config/latchkey/config.json). No CI ou em um loop de agente, dispense a configuração salva e defina a variável de ambiente LATCHKEY_TOKEN em vez disso.

Execute um job#

terminal
1latchkey run 'npm ci && npm test'
2latchkey run --size large --timeout 3600 'npm ci && npm run build && npm test'
3latchkey run --env NODE_ENV=test 'npm ci && npm test'

Toda execução faz as mesmas cinco coisas: empacota o diretório atual em um arquivo de contexto, faz o upload, executa o comando em um runner novo, transmite os logs de volta ao vivo e sai com o código de saída do próprio comando. Um job cancelado sai com 130, um job que o Latchkey expirou antes mesmo de começar sai com 124, e um comando interrompido pelo --timeout termina com falha por timeout_exceeded e sai com 1, então scripts e agentes podem ramificar conforme o desfecho sem interpretar uma linha sequer de log.

latchkey run 'cd app && npm ci && npm test'

Passe uma verificação de várias etapas como um único argumento entre aspas, mudando de diretório dentro dele quando precisar. O runner executa essa linha em bash com -e e -o pipefail, então ela para no primeiro comando que falhar. Um bash -c ou sh -c no início, digitado como palavras separadas, executaria só a primeira palavra do script, então o CLI o recusa com código de saída 2, antes de qualquer coisa ser empacotada ou enviada, e imprime a linha a executar no lugar: ela mantém o seu shell dentro do único argumento e só o remove quando era bash com -e e -o pipefail. Um bash -c dentro do único argumento entre aspas, ou latchkey run bash ci.sh, roda como foi escrito.

acme-api · zsh · latchkey run

latchkey run 'npm run e2e' transmite o log do job até a pessoa apertar Ctrl-C. O CLI então imprime job still running: latchkey cancel cli-8c41a0f2-7d3e-4b9a-a5c6-1e2f3d4b5c6a | latchkey logs cli-8c41a0f2-7d3e-4b9a-a5c6-1e2f3d4b5c6a --follow, o shell informa o código de saída 130 e o job continua rodando no runner. Em seguida, latchkey cancel com o id do job imprime Cancellation requested; the runner honors it within about 10 seconds (current state: running).

FIG. 3.4-CO Ctrl-C para o acompanhamento do log, não o job: o CLI mostra como cancelá-lo ou voltar a acompanhá-lo, e o latchkey cancel o encerra no runner em cerca de 10 segundos.
acme-api · zsh · latchkey run --timeout

Num terminal em ~/acme-api, latchkey run --timeout 120 'npm run e2e' imprime Packing context from /Users/me/acme-api..., Packed 412 file(s), 3.1 MB compressed., Created job cli-5d9e2c71-4b8a-4f06-9e3d-a1c7b2f4e860., o link para o job no dashboard, Uploading context (3.1 MB)..., Context uploaded. e Submitted; state: queued. O log do job volta em fluxo: a linha [latchkey] do agente do job, state: running, o script e2e iniciando o Playwright com Running 86 tests using 4 workers e uma fileira de pontos, um por teste aprovado. Dois minutos depois do início do comando, o log imprime [latchkey] job timed out after 120s. Em seguida, a CLI imprime state: failed e Job cli-5d9e2c71-4b8a-4f06-9e3d-a1c7b2f4e860 failed. The job reported: timeout_exceeded, e sai com o código 1.

FIG. 3.4-DUm comando que passa do --timeout é interrompido no runner e o job termina com falha pelo motivo que relatou, timeout_exceeded, então a execução sai com 1. O código 124 é só para um job que o Latchkey expirou antes mesmo de começar.

Divida uma suíte entre runners#

Uma suíte longa termina mais cedo como um job por shard. Defina o orçamento de um lote novo, inicie um job desanexado por shard com a própria flag de divisão do executor de testes, passada pelo próprio script test do pacote, e depois acompanhe cada job até o seu veredito. Passar pelo script roda os passos de pretest do pacote (uma checagem de tipos dos testes, por exemplo) em todo shard, como o CI os roda, enquanto chamar o executor de testes diretamente os pula. O bloco para de iniciar shards assim que um é recusado e termina com um código de saída diferente de zero quando um shard não começou ou falhou:

split-suite.sh
batch="suite-$(date +%Y%m%d%H%M%S)"
failed=0
ids=()
latchkey budget set "$batch" 4 || failed=1
for shard in 1 2 3 4; do
  [ "$failed" -eq 0 ] || break
  id=$(latchkey run --batch "$batch" --size large --detach "npm ci && npm test -- --shard=$shard/4") || true
  if [ -n "$id" ]; then ids+=("$id"); else echo "shard $shard not started"; failed=1; fi
done
for id in "${ids[@]}"; do
  code=0
  latchkey logs "$id" --follow > "$id.log" || code=$?
  echo "$id exited $code"
  [ "$code" -eq 0 ] || failed=1
done
[ "$failed" -eq 0 ]

Cada shard paga a própria instalação e é cobrado em seus próprios minutos inteiros, e cada shard conta para o limite de jobs em execução ao mesmo tempo do workspace, que todos os agentes e execuções de workflow do workspace compartilham. Divida só uma suíte longa o bastante para compensar as instalações extras, e mantenha uma rajada bem abaixo do limite. Um arquivo de workflow divide do mesmo jeito com um matrix.

Os comandos#

ComandoO que ele faz
latchkey loginValida uma chave de API e a salva para esta máquina
latchkey runEmpacota o diretório atual, executa um comando em um runner novo, transmite os logs e sai com o código do comando
latchkey listLista os jobs recentes, do mais novo para o mais antigo, incluindo os que ainda estão em execução
latchkey logsImprime os logs de um job, ou os acompanha até a conclusão com --follow
latchkey statusMostra o estado de um job, o tamanho do runner, os tempos e o código de saída
latchkey cancelSolicita o cancelamento; um job em execução para em cerca de 10 segundos
latchkey budgetDefine o primeiro orçamento de um lote em dólares americanos e o primeiro limite de jobs rodando ao mesmo tempo, os reduz ou os mostra com o gasto; uma chave de API nunca aumenta nenhum dos dois
latchkey batchMostra o orçamento, o gasto, os jobs por estado e os jobs de um lote
latchkey waitEspera jobs ou um lote terminarem e resume o resultado de cada um
latchkey watchConsulta as falhas de CI que o autorreparo registrou mas não corrigiu e entrega a primeira falha nova de cada job (de cada execução, no Latchkey on GH) ao seu agente de codificação
latchkey cacheRestaura ou salva uma entrada de cache de dentro de um job, para que um diretório de dependências sobreviva até o próximo
latchkey artifactEnvia ou baixa um artefato de dentro de um job de uma execução do Latchkey CI, passando arquivos entre os jobs dessa execução
latchkey oidcObtém um token de identidade de curta duração dentro de um job de uma execução do Latchkey CI, para que o job entre na sua nuvem sem nenhuma chave guardada
latchkey secretsDefine um segredo que os passos de um arquivo de workflow leem, para o workspace inteiro ou para um repositório
latchkey migratePlaneja a migração de um repositório do GitHub Actions para o Latchkey CI e abre o pull request para ela (abrir o pull request exige uma chave criada com Allow opening migration pull requests)
latchkey stepsLista os passos do Latchkey que um arquivo de workflow pode nomear, cada um na versão mais recente, com suas entradas e as regras delas
latchkey validateVerifica um arquivo de workflow alterado sem iniciar uma execução: a primeira recusa, ou os jobs dele e o máximo que uma execução deles pode custar
latchkey preflightRoda um arquivo de workflow, como o Latchkey o compila, na sua árvore de trabalho antes de você fazer o commit ou o push (exige um repositório conectado ao Latchkey CI)
latchkey workflowsInicia uma execução manual de um arquivo de workflow que aceita execuções manuais, em um branch ou tag e com as entradas dele (exige uma chave criada com Allow starting Latchkey CI workflows)

As flags de run que você vai realmente usar: --size escolhe o runner (small é o padrão; medium, large e xlarge correspondem aos tamanhos de runner que seus workflows usam), --env KEY=VALUE passa segredos e configurações sem enviá-los como arquivos, --timeout aceita de 30 segundos a 3 horas (os jobs têm 30 minutos por padrão), --detach envia o job e sai para você acompanhá-lo depois, e --no-context executa o comando em um workspace vazio, sem nada enviado. --batch <name> coloca o job em um lote com nome de 1 a 64 caracteres, sem / nem %, que não seja apenas . ou .. (ou defina LATCHKEY_BATCH uma vez para todos os jobs de um shell), para que os jobs e o gasto de um mesmo trabalho sejam lidos juntos. Todo comando remoto aceita --output json para saída legível por máquina, e o pacote traz sua própria referência aprofundada (SKILL.md) que um agente de codificação pode ler para conhecer o contrato completo.

O que cada versão adicionou, alterou e corrigiu está no Changelog da CLI do Latchkey.

acme-api · zsh · latchkey run --detach

latchkey run --detach 'npm ci && npm test' empacota e envia a árvore de trabalho com as mesmas linhas de progresso de uma execução normal, imprime o id do job cli-2b9d4e71-0c5a-4f3e-8a6d-7e1f9c3b5a20 e retorna na hora. latchkey status com esse id imprime as linhas do job: State running, Runner size small, Rate e Cost so far pela taxa de lista do tamanho small, antes dos minutos gratuitos, Timeout 1800s, Cancel requested no, Exit code e Failure reason ainda sem valor, e os horários Created, Submitted e Started. latchkey logs com esse id e --follow imprime o log do job desde o início até os resultados dos testes e, depois, state: succeeded e Job cli-2b9d4e71-0c5a-4f3e-8a6d-7e1f9c3b5a20 succeeded (exit 0).

FIG. 3.4-EO --detach devolve o id do job na hora em vez de transmitir o log. O latchkey status lê o job, e o latchkey logs --follow acompanha o log desde o início e termina com o código de saída do job.
acme-api · zsh · latchkey list

Em ~/acme-api, latchkey list --limit 5 imprime os cinco jobs mais recentes do workspace em uma tabela com as colunas JOB, STATUS, SIZE, BATCH, KEY, DURATION, COST, COMMAND e QUEUED. O mais recente, cli-4e7a9c21-8b3d-4f6e-a1c5-9d2b7e0f3a64, está running em medium no lote refactor-auth, iniciado com a chave claude-code, com o comando mostrado como npm run, a duração como um hífen e o custo até agora como meio centavo. Os dois seguintes executaram npm test em small no mesmo lote: success em 1m52s por meio centavo e failure (1) em 2m07s por três quartos de centavo. Os dois últimos foram executados com a chave laptop e sem lote: npm run em large, success em 6m31s por 7 centavos, e npm ci em small, success em 48s por um quarto de centavo. Cada linha termina com o horário em que o job entrou na fila, de 2026-10-15T10:42:18.604Z até 2026-10-15T09:47:12.773Z.

FIG. 3.4-FUm id de job que sumiu do terminal está a um latchkey list de distância. Jobs em execução também aparecem, sem duração até terminarem; um job com falha traz o código de saída ao lado do status, e a coluna de comando mostra só o programa e o primeiro subcomando, então um token na linha de comando nunca é impresso.
acme-api · zsh · latchkey run --quiet

Em ~/acme-api, cat ci/deps.sh imprime um script de cinco linhas: set -e, npm install -g @latchkeydev/cli, latchkey cache restore --key npm-cache --version v1, npm ci --cache .npm-cache e latchkey cache save --key npm-cache --version v1 .npm-cache. latchkey run --quiet 'bash ci/deps.sh' imprime o id do novo job, cli-0d4f7b2e-6c1a-4e95-a8b3-f2e7c9d1a046, e o link para ele no dashboard, e depois o log do job: a linha [latchkey] do agente do job, added 9 packages in 2s, cache miss: npm-cache (version v1), added 1291 packages in 41s e cache saved: npm-cache (61834215 bytes). O mesmo comando de novo inicia cli-8f3a6e19-b2d7-4c40-9e5f-1a7c0b4d2e83, cujo log traz added 9 packages in 2s, cache restored: npm-cache (61834215 bytes), added 1291 packages in 9s e cache entry already exists: npm-cache was not overwritten. As duas execuções terminam com código 0.

FIG. 3.4-GO latchkey cache roda dentro de um job, então o job instala o CLI primeiro. A primeira execução não encontra o cache e salva o cache do npm; a seguinte o restaura antes do npm ci, e o save dela deixa a entrada como está, porque uma chave que já tem uma entrada nunca é sobrescrita. Um cache miss sai com 0, como um erro do proxy de cache, então um cache vazio ou indisponível nunca faz um job falhar, e --quiet reduz as linhas do próprio CLI ao id do job e ao link dele.

latchkey artifact também roda dentro de um job, mas só em um job de uma execução de um arquivo de workflow: upload --name <name> <path...> empacota os caminhos em um único artefato, e download --name <name> busca um que um job de que este job precisa enviou. Um envio deixa de fora arquivos e diretórios cujo nome começa com um ponto, como .git e .env, a menos que receba --include-hidden-files, e um envio que nomeia um deles sem essa flag falha, assim como um envio que não encontra nenhum arquivo regular nos seus caminhos. Ao contrário de latchkey cache, um envio ou download que falha sai com 1, então o passo falha. Um job de um preflight não pode enviar nem baixar artefatos: o armazenamento recusa toda chamada que ele faz, e o comando sai com 199, que o preflight lê no primeiro passo do job que falhou para relatar o job como não executado, e não como falho. A página de arquivos de workflow tem as regras: nomes, limites e por quanto tempo um artefato fica guardado.

acme-api · zsh · latchkey secrets set

Em ~/acme-api, latchkey secrets set NPM_TOKEN pede Secret value (input hidden): e não mostra nada enquanto o valor é digitado; depois imprime Set NPM_TOKEN for the workspace (version 1). Em seguida, echo "$DATABASE_URL" é encadeado com pipe em latchkey secrets set DATABASE_URL --repository acme/api, que lê o valor do pipe e imprime Set DATABASE_URL for acme/api (version 2). Os dois comandos terminam com código 0.

FIG. 3.4-HO latchkey secrets set guarda um segredo que os passos de um arquivo de workflow leem como ${{ secrets.NAME }}, para o workspace inteiro ou, com --repository, para um repositório. O valor vem de um prompt oculto ou de um pipe, nunca da linha de comando, e nunca é impresso; definir um nome de novo guarda uma nova versão. Ele precisa de uma chave criada com Allow setting workspace secrets; um job do CLI recebe os segredos dele por --env.

O que é enviado com o job#

latchkey run empacota o diretório de onde você o executa, nunca o repositório que o contém, então executar de um subdiretório envia apenas aquele subdiretório, e --context <dir> aponta o empacotamento para outro lugar. O comando roda na raiz da árvore enviada, então o diretório que --context nomeia vira a raiz do workspace no runner. --context e --exclude são lidos apenas antes do comando, então as flags do próprio comando passam adiante. Quatro regras decidem o que entra, e a última a expressar uma opinião vence:

  • Todo .gitignore dentro da árvore empacotada se aplica aos arquivos não rastreados, então instalações de dependências e saídas de build ignoradas ficam em casa e o job instala do zero, do jeito que o CI faz. Só contam os arquivos de ignore dentro da árvore: execute de um subdiretório e o .gitignore da raiz do repositório deixa de se aplicar (um .latchkeyignore na raiz do empacotamento é a correção).
  • --exclude <pattern> retém caminhos direto da linha de comando, em sintaxe de gitignore, um padrão por flag. Ele não aceita negação: um ! no início é um erro de uso, porque --exclude só pode reter mais, nunca readmitir algo.
  • Arquivos com formato de credencial (arquivos .env, chaves privadas, arquivos de credenciais de nuvem) são retidos por uma lista de bloqueio integrada, e toda exclusão é impressa. Nenhum padrão de --exclude pode enviar um arquivo que a lista de bloqueio de credenciais retém, e todo arquivo que a lista de bloqueio retém é reportado. Um .gitignore também nunca pode reincluí-los.
  • Um arquivo .latchkeyignore (mesma sintaxe) prevalece sobre os três: use-o para excluir mais, ou para reincluir deliberadamente algo que a lista de bloqueio reteve, o que imprime um aviso destacado nomeando o arquivo. É a única fonte de regras que pode fazer isso, porque é o arquivo do próprio dono do repositório.
  • Um job que precisa de dois pacotes de um mesmo repositório empacota o diretório que contém os dois e muda de diretório dentro do seu único comando (cd shared && npm ci && cd ../web && npm ci && npm test). Empacotar o diretório de um só pacote deixa os vizinhos em casa.
  • Todo comando começa pela instalação, já que um job roda em um runner limpo. Onde nenhuma regra de ignore nomeia node_modules, ele é enviado e custa tempo de upload por nada: retenha-o com uma linha node_modules no .latchkeyignore, sem barra no final.
  • Um arquivo commitado com git add -f que corresponde a um padrão do .gitignore é enviado, porque o empacotamento inclui o que o git rastreia. Um arquivo de configuração commitado que um teste lê e que corresponde a um padrão de credencial continua ficando em casa (*.config.tfvars corresponde a *.tfvars): se ele não guarda nenhum segredo, traga-o de volta com uma linha ! no .latchkeyignore.
.latchkeyignore
!test/fixtures/**/*.txt
!terraform/*.config.tfvars
O que o latchkey run empacota~/acme-api
.gitignore
.latchkeyignore
Desmarque uma linha para comentá-la.
Lista de bloqueio de credenciais: 39 padrões
.env.env.**.env.envrc.dev.vars*.pem*.key*.p12*.pfx*.p8*.ppk*.jks*.keystoreid_rsaid_rsa.*id_dsaid_ecdsaid_ed25519id_ed25519.*.ssh/.aws/.gnupg/.kube/kubeconfig.npmrc.netrc.pypirc.pgpass.git-credentials.vault-token.terraformrc.htpasswd**/.docker/config.json*.tfstate*.tfstate.**.tfvarsservice-account*.jsonserviceAccount*.jsongcp-credentials*.json
Nunca bloqueados (ficam com as suas próprias regras):
.env.example.env.sample.env.template.env.*.example*.example.env*.sample.env*.example.tfvars*.sample.tfvars*.tfvars.example*.tfvars.sample
  • .env112 Bfica de fora
  • .env.example98 Bempacotado
  • .git/fica de fora
  • .gitignore37 Bempacotado
  • .latchkeyignore34 Bempacotado
  • .npmrc52 Bfica de fora
  • README.md1.8 KBempacotado
  • data/fica de fora
  • seed.sql1.4 GBfica de fora
  • dist/fica de fora
  • server.js612 KBfica de fora
  • node_modules/fica de fora
  • 18.240 arquivos em 2.315 pastas212 MB
  • npm-debug.log9.6 KBfica de fora
  • package-lock.json186 KBempacotado
  • package.json1.2 KBempacotado
  • src/empacotado
  • routes.ts4.1 KBempacotado
  • server.ts2.3 KBempacotado
  • test/empacotado
  • api.test.ts5.4 KBempacotado
  • fixtures/empacotado
  • tls.key1.7 KBfica de fora
.npmrc
Retido pelo padrão .npmrc da lista de bloqueio integrada, diga o .gitignore o que disser. O latchkey run o nomeia, e só uma linha ! no .latchkeyignore pode trazê-lo de volta.
Arquivos
9
Sem compressão
201 KB
de 1 GiB
Entradas
12
de 250.000
O que o latchkey run imprime
Excluded 3 path(s) matching the credential deny-list. Add a "!" line to .latchkeyignore to include one deliberately:
.env
.npmrc
test/fixtures/tls.key
Um projeto de exemplo; os tamanhos são ilustrativos. O arquivo compactado pode ter no máximo 200 MiB, e as pastas podem se aninhar em no máximo 64 níveis. Um contexto acima de qualquer limite falha antes de qualquer envio.

Limites#

LimiteValor
Linha de comando16.384 caracteres
Variáveis de ambiente64 por job
Timeout do job30 segundos a 3 horas, padrão de 30 minutos
Orçamento do jobNenhum por padrão; com --budget ou budget_usd, o job é interrompido assim que custar esse valor ao preço de tabela do seu tamanho, contado em minutos inteiros
Orçamento do loteNenhum por padrão; definido ou reduzido com latchkey budget set ou com a ferramenta set_batch_budget, nunca aumentado por uma chave de API. Quando os jobs de um lote custam o seu orçamento a preços de tabela, um novo job nele é recusado e os seus jobs na fila ficam retidos; os jobs em execução terminam, então um lote pode terminar um pouco acima do orçamento
Limite de gastosO limite do workspace para o mês do calendário, definido por um owner ou admin. Ao atingi-lo, latchkey run é recusado (exit 1) e um job em execução é interrompido (exit 130); um orçamento de job ou de lote nunca pode ser definido acima dele.
Upload de contexto200 MiB comprimido, 1 GiB descomprimido, 250.000 entradas
Contexto mantido por workspace20 GiB de contexto enviado no total ao mesmo tempo, por padrão; um upload é liberado quando seu arquivo é excluído e sua URL de upload já expirou, ou quando o próprio upload expira
Criação de jobsDeveloper 120, Launch 240, Scale 600 por workspace por hora cheia; Enterprise conforme contrato. Um workspace pode ter o seu próprio número, e a recusa informa o número em vigor. Uma criação recusada entra na contagem da hora.
Leituras por chave de API900 por minuto cheio, somando as leituras da Jobs API e as ferramentas de leitura do MCP; uma leitura recusada entra na contagem. Acima disso, uma leitura é recusada até o minuto virar, com os segundos de espera (retry_after_s, e um cabeçalho Retry-After no 429 da Jobs API). Uma espera por runs (latchkey wait --commit ou --pr, ou a ferramenta MCP wait_run) não é contada.
Registros de jobsO status permanece legível após o término de um job, os logs por 30 dias e o cancelamento por cerca de 24 horas; latchkey list ainda mostra jobs mais antigos

Um contexto acima do teto falha no empacotamento localmente, antes de qualquer coisa ser enviada ou cobrada, com os maiores caminhos nomeados, de modo que a correção costuma ser uma linha de .latchkeyignore.

Um job não é recusado no limite de jobs em execução ao mesmo tempo do seu workspace: o Latchkey o mantém na fila, e ele começa quando um job em execução termina. Enquanto jobs que você iniciou estiverem retidos no limite do workspace ou perto dele, não inicie nada novo e combine verificações em menos jobs.

acme-api · zsh · latchkey budget set

Em ~/acme-api, latchkey budget set refactor-auth 10 imprime que o orçamento do lote refactor-auth passou a ser de $10,00 e que o gasto até agora é de $2,415 a preços de tabela. latchkey budget set refactor-auth 5 reduz o orçamento para $5,00, com o mesmo gasto. latchkey budget set refactor-auth 20 pede um aumento, e o CLI imprime a recusa: o lote refactor-auth já tem um orçamento de $5,00, e uma chave de API só pode reduzir o orçamento de um lote, então o Latchkey o deixou como estava; comece o trabalho com um novo nome de lote ou peça a um owner do workspace que aumente este. Esse comando termina com código 1.

FIG. 3.4-IUma chave de API define o primeiro orçamento de um lote e pode reduzi-lo, mas nunca aumentá-lo; um owner ou admin do workspace pode, na página Billing. Spent so far é o que os jobs do lote custaram a preços de tabela, e quando chega ao orçamento, um novo job no lote é recusado e os jobs dele na fila ficam retidos.

Cobrança#

Jobs da CLI são minutos de runner comuns: a mesma tarifa por minuto de um job de workflow no mesmo tamanho, arredondada para cima por job, descontada primeiro do mesmo pool mensal de minutos gratuitos. O medidor corre de quando seu comando inicia até o fim do job; tempo de fila e de provisionamento nunca é cobrado. Na página Cost esse gasto aparece como uma linha própria CLI jobs, porque esses jobs não pertencem a nenhum repositório ou workflow. Quando um job termina, latchkey status e latchkey list mostram quanto ele custou pelo preço de tabela, antes dos minutos gratuitos.

O autorreparo também funciona aqui#

Todo job da CLI roda sob a mesma maquinaria de autorreparo dos seus jobs de workflow. Falhas de ambiente (um registry instável, um pacote de sistema faltando, um disco cheio) são diagnosticadas no lugar enquanto o job roda e corrigidas quando uma correção se aplica: uma nova tentativa corrigida que passa sai com 0, e quando nada se aplica o código de saída original do comando permanece. Defeitos reais no seu código passam adiante inalterados, para que o código de saída diga a verdade. Uma diferença em relação aos jobs de workflow: um job da CLI não tem repositório, então o autorreparo nunca abre um pull request; as correções acontecem no runner ou não acontecem. Para diagnosticar uma falha, o autorreparo pode ler arquivos da árvore de trabalho que você enviou: no máximo quatro consultas por diagnóstico e os primeiros 8 KiB de um arquivo. O que ele lê vai para o nosso provedor de modelo de IA e fica no registro do reparo por 90 dias, depois que o próprio envio é excluído. Um arquivo que você retém com --exclude nunca chega ao runner. O diagnóstico roda dentro da janela cobrada, então uma execução que falha é cobrada visivelmente mais do que uma que passa (tipicamente cerca de um minuto extra); conte com esse custo ao iterar sobre uma falha.

A outra direção: watch#

latchkey run é você pedindo ao Latchkey para checar algo. latchkey watch é o Latchkey avisando que algo quebrou: ele consulta as falhas que o autorreparo registrou mas não corrigiu (suas execuções de workflow, e jobs da CLI também) e entrega a primeira falha nova de cada job (de cada execução, no Latchkey on GH) ao seu agente de codificação (Claude Code por padrão, --agent para qualquer outro). O agente lê o registro da falha pelo servidor MCP, então conecte-o lá primeiro. Use --once para uma listagem única e --no-spawn para imprimir sem iniciar nada. Qualquer chave pode executar watch; ele apenas lê.

acme-api · zsh · latchkey watch

Em ~/acme-api, latchkey watch imprime Watching for new failures every 15s (2 existing failures ignored). New ones go to: claude. Quando chega uma nova falha sem correção, ele imprime failure 7c2e9a14-3b5d-4f81-9a6e-0d4c8b2f1e37, depois uma linha com o repositório acme/api, o workflow ci, a categoria test_failure, o arquivo com falha src/auth/refresh.ts e a causa raiz token expiry compared in seconds against a millisecond clock, em seguida o link da execução no GitHub e, por fim, Handing 7c2e9a14-3b5d-4f81-9a6e-0d4c8b2f1e37 to claude…

FIG. 3.4-JFalhas já conhecidas são ignoradas; cada nova aparece com o que o autorreparo registrou, e a primeira nova de cada job (de cada execução, no Latchkey on GH) vai para o seu agente uma vez. A saída é a do próprio CLI, separadores incluídos.

Funciona com#

Perguntas comuns#

Q.01O job vê meu histórico git?

Não. O diretório .git é sempre excluído e não pode ser reincluído. O job vê seus arquivos como eles estão no disco, em um repositório de um único commit que o runner cria quando consegue, então comandos git funcionam; o HEAD dele não é o seu commit, então, se o comando precisar de um SHA de commit ou de um nome de branch, passe-o por --env.

Q.02Um job pode alcançar meus serviços ou bancos de dados locais?

Não. O runner é uma máquina nova e isolada, sem rota de volta para o seu laptop. Ele vê a árvore enviada e as variáveis de ambiente que você passa, nada mais. Comandos interativos travam pelo mesmo motivo: não há terminal do outro lado, então qualquer coisa que peça entrada espera até o timeout encerrar o job.

Q.03O que acontece quando eu pressiono Ctrl-C?

Ele interrompe o acompanhamento, não o job: o job continua rodando (e sendo cobrado) no runner. O aviso de interrupção imprime os dois próximos passos, latchkey cancel <id> para parar o job e latchkey logs <id> --follow para reconectar.