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.

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 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. 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.

Instale e autentique-se#

$ npm install -g @latchkeydev/cli
$ latchkey --help

Execute um job#

$ latchkey run 'npm test'
$ latchkey run --size large --timeout 3600 'npm ci && npm run build && npm test'
$ latchkey run --env NODE_ENV=test '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 e um job expirado pela plataforma sai com 124, então scripts e agentes podem ramificar conforme o desfecho sem interpretar uma linha sequer de log.

Os comandos#

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 2 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. 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 é 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. Três regras decidem o que entra, e a última a expressar uma opinião vence:

• Todo .gitignore dentro da árvore empacotada se aplica, 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).
• 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. Um .gitignore nunca pode reincluí-los.
• Um arquivo .latchkeyignore (mesma sintaxe) prevalece sobre ambos: 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.

Limites#

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.

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 Análise de custos esse gasto aparece como uma linha própria CLI Jobs, porque esses jobs não pertencem a nenhum repositório ou workflow.

A autocorreção também funciona aqui#

Todo job da CLI roda sob a mesma maquinaria de autocorreção 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 a autocorreção nunca abre um pull request; as correções acontecem no runner ou não acontecem. 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 a autocorreção diagnosticou mas não conseguiu corrigir (suas execuções de workflow, e jobs da CLI também) e entrega cada nova falha ao seu agente de codificação (Claude Code por padrão, --agent para qualquer outro), exatamente uma vez. O agente lê o contexto completo 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ê.

Funciona com#

• Conecte seu agente de IA: a ferramenta MCP run_job é a mesma superfície de jobs sem um terminal. Ela parte de um workspace vazio; a CLI é o caminho para enviar sua árvore de trabalho.
• Visão geral dos runners: jobs da CLI rodam nos mesmos quatro tamanhos de runner e na mesma imagem do runner, nova para cada job e destruída ao final.
• Uso de runners e minutos gratuitos: como funcionam a medição por minuto e o nível gratuito.
• Análise de custos: onde o gasto com jobs da CLI aparece no dashboard.

Perguntas comuns#