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

Source: https://latchkey.dev/pt/documentation/latchkey-cli

## Summary

- `npm install -g @latchkeydev/cli`, depois `latchkey run 'npm test'` executa o comando em um runner novo do Latchkey e sai com o código de saída do próprio comando.
- Sua árvore de trabalho é enviada com o job: as regras de `.gitignore` se aplicam, arquivos com formato de credencial são retidos por padrão, e `.latchkeyignore` sobrepõe ambos.
- 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 de Análise de custos.
- Requer uma chave de API criada com **Allow running CLI jobs (includes reading)**. Agentes de codificação alcançam 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 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

1. **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.
2. **Crie uma chave de API habilitada para jobs** Em **Settings, API Keys** (proprietários e administradores), gere uma chave com **Allow running CLI jobs (includes reading)** marcado. 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.
3. **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
$ 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.

> **O código de saída é o veredito**
> `latchkey run 'npm test'` sair com 0 significa que a suíte passou em um runner Linux limpo; diferente de zero significa que não passou. Encadear a saída em outro comando com pipe substitui esse veredito pelo status do comando seguinte, então redirecione para um arquivo quando precisar dos logs e do código ao mesmo tempo.

## Os comandos

| Comando | O que ele faz |
| --- | --- |
| `latchkey login` | Valida uma chave de API e a salva para esta máquina |
| `latchkey run` | Empacota o diretório atual, executa um comando em um runner novo, transmite os logs e sai com o código do comando |
| `latchkey list` | Lista os jobs recentes, do mais novo para o mais antigo, incluindo os que ainda estão em execução |
| `latchkey logs` | Imprime os logs de um job, ou os acompanha até a conclusão com `--follow` |
| `latchkey status` | Mostra o estado de um job, o tamanho do runner, os tempos e o código de saída |
| `latchkey cancel` | Solicita o cancelamento; um job em execução para em cerca de 10 segundos |
| `latchkey watch` | Consulta as falhas de CI que a autocorreção não conseguiu corrigir e entrega cada uma ao seu agente de codificação |

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](/documentation/runners-overview) 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.

> **Seu histórico git fica em casa**
> O diretório `.git` nunca é enviado e não pode ser reincluído, então o job vê seus arquivos, não seu histórico ou seus remotes. Precisa de um SHA de commit ou de um nome de branch dentro do job? Passe-o com `--env`. Segredos de verdade também pertencem a `--env`, nunca à árvore enviada.

## Limites

| Limite | Valor |
| --- | --- |
| Linha de comando | 16,384 caracteres |
| Variáveis de ambiente | 64 por job |
| Timeout do job | 30 segundos a 2 horas, padrão de 30 minutos |
| Upload de contexto | 200 MB comprimido, 1 GiB descomprimido, 250,000 entradas |
| Criação de jobs | 120 jobs por hora por workspace |
| Registros de jobs | Status e logs permanecem legíveis por cerca de 24 horas após o término de um job; `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`.

## 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](/documentation/runner-usage-and-free-minutes). 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](/documentation/cost-analysis) 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](/documentation/self-healing) 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](/documentation/connect-your-ai-agent), 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](/documentation/connect-your-ai-agent): 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](/documentation/runners-overview): jobs da CLI rodam nos mesmos quatro tamanhos de runner e na mesma [imagem do runner](/documentation/runner-image-software), nova para cada job e destruída ao final.
- [Uso de runners e minutos gratuitos](/documentation/runner-usage-and-free-minutes): como funcionam a medição por minuto e o nível gratuito.
- [Análise de custos](/documentation/cost-analysis): onde o gasto com jobs da CLI aparece no dashboard.

## Perguntas comuns

### O 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; se o comando precisar de um SHA de commit ou de um nome de branch, passe-o por `--env`.

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

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

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt