Usando a CLI

A ferramenta de linha de comando awr é o ponto de entrada completo de gestão de um projeto AWR: tudo o que um agente pode fazer via MCP, você pode fazer no seu terminal — além da administração de projeto que o MCP não expõe.

Instalação

Os dois canais de pacotes instalam a mesma CLI em Rust e o mesmo servidor MCP; não existe um SDK separado em JavaScript ou Python:

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

Verifique com awr --version e awr-mcp --version.

Os alvos suportados são macOS 15+ (arm64 e Intel), Linux com glibc 2.39+ (a base do Ubuntu 24.04, x64 e arm64) e Windows x64. O launcher do npm requer Node 22.14+ e depende de pacotes nativos opcionais, então mantenha as dependências opcionais habilitadas; o launcher do PyPI requer Python 3.9+. No Linux, verifique a glibc com ldd --version | head -n 1. O Git é necessário apenas para operações vinculadas ao Git; o SQLite vem embutido. Para um passo a passo do primeiro projeto, veja o Quickstart.

O formato de todo comando

Os exemplos de CLI ao longo da documentação compartilham um prefixo comum:

awr --project /absolute/project --json <command>

--project aponta para a raiz do projeto; --json muda o stdout para um único objeto JSON legível por máquina (detalhes abaixo). Omita --json quando for ler a saída você mesmo — a saída humana padrão é deliberadamente limitada: status mostra no máximo uma sugestão atual e ready lista no máximo 10 itens.

Verificando onde o projeto está

status é a sua primeira parada. A sua view padrão action mostra a continuação atual, o trabalho disponível para claim, as esperas, os bloqueios reais e um resumo do histórico:

awr --project /absolute/project status --view full --branch main

--view action/full/summary — o padrão é action; full devolve a estrutura completa legada.
--branch NAME_OR_ID — lê uma branch por nome, ID interno ou main em vez da branch padrão. Selecionar uma branch para leitura nunca muda a branch padrão, as sessões, os claims ou o seu checkout do Git.

ready lista os itens de trabalho que podem ser assumidos, com diagnósticos, informações de claim e dicas de truncamento. --limit tem padrão 10 e aceita de 1 a 100; --branch também funciona aqui:

awr --project /absolute/project ready --limit 25

Lendo itens de trabalho

work show apresenta um item por completo — tarefa, critérios de aceitação, dependências, decisões, evidências e procedência. --source-sha SHA lê o item conforme uma revisão específica da fonte; --branch lê em outra branch:

awr --project /absolute/project work show W-123 --source-sha abc123

search encontra itens em todo o projeto. O texto da consulta é posicional; --type, --status, --work e --limit restringem os resultados:

awr --project /absolute/project search "payment retry" --type work --limit 20

Compilando contexto para uma tarefa

context compile monta o contexto de execução L1 — o conjunto de trabalho orçado para uma tarefa — com completude, lacunas, procedência e o hash de contexto:

awr --project /absolute/project context compile --work W-123

Tudo isso é opcional: --session e --detached controlam o vínculo de sessão; --agent, --intent e --budget orientam a compilação; --goal, --path e --tag são repetíveis; --source-sha compila contra uma versão específica da fonte; --checkpoint e --after-revision definem baselines personalizadas e são mutuamente exclusivos. --branch ID usa a baseline de contexto comum em outra branch — um significado diferente de branch context, que compila o incremento de uma branch nomeada desde o seu fork sem trocar a sua branch padrão:

awr --project /absolute/project branch context feature-x --work W-123

A saída de texto padrão é o contexto de execução limitado pelo orçamento, com os critérios de aceitação completos e as regras rígidas preservados. Se houver lacunas obrigatórias, o resultado JSON vem com ok=false e error.code=ContextIncomplete; se os fatos rígidos excederem o orçamento, você recebe BudgetExceeded — nunca fatos silenciosamente truncados.

Movendo o trabalho para a frente

Os itens de trabalho mudam de estado por meio dos subcomandos de work:

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

O mesmo formato se aplica a block, unblock, cancel e reopen, com --next-action, --summary e --blocker carregando os detalhes correspondentes. A conclusão vincula critérios de aceitação e evidências a partir de um arquivo JSON e libera o claim desta sessão em caso de sucesso:

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

Registrando eventos e evidências

event append escreve no log do projeto:

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

Flags opcionais: --work, --session, --branch, --importance (padrão normal) e --payload FILE (um arquivo de valor JSON, {} quando omitido). A saída padrão mostra o ID, o tipo, o resumo curto e a versão — ela não ecoa o payload; use event show --full para expandir um evento explicitamente. Você não pode forjar eventos de domínio reservados como work.completed; eles vêm apenas dos comandos de mudança de estado.

evidence add registra evidência a partir de um arquivo JSON de entrada:

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

Os campos de entrada incluem work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope e verified_at. Uma escrita bem-sucedida retorna o registro salvo e um event_id, mas registrar não é executar: validation_basis=caller_supplied_bindings significa que o AWR armazenou os vínculos que você enviou — não que ele rodou o seu comando nem que a aceitação de negócio passou. evidence show fornece a view de leitura resumida de um registro; não é um recibo de escrita.

Regras de caminho e tamanho: caminhos relativos na entrada de evidência e nos payloads de eventos são resolvidos em relação à raiz do --project; caminhos relativos em uma entrada de conclusão são resolvidos em relação ao diretório atual do processo, então use caminhos absolutos em automação. Arquivos de evidência e de payload de eventos têm limite de 1 MiB; entradas de conclusão, de 64 KiB.

Revisões e concorrência otimista

As escritas aceitam --expected-revision R, onde R é o project_revision mais recente que você observou. Se o projeto avançou, a escrita falha com RevisionConflict em vez de sobrescrever silenciosamente o trabalho de outra pessoa — releia com status e tente de novo contra a nova revisão. Três números de versão aparecem na saída e não são intercambiáveis: revision é a versão de um objeto, source_revision é a versão da fonte e project_revision é a versão do estado do projeto.

Se uma escrita for interrompida ou aplicada parcialmente, verifique a proposta, os eventos, a sessão e a revisão atual antes de decidir o que fazer — não tente de novo às cegas após uma falha de processo. Dois erros de workspace merecem menção: WorkspaceConflict (de awr workspace) significa que os dois lados editaram o mesmo arquivo rastreado e nada é mesclado automaticamente; WorkspaceContended significa que um publish ou drop foi preemptado três commits seguidos, e o remédio é simplesmente rodar o mesmo comando de novo.

Saída JSON, erros e códigos de saída

Com --json, um comando bem-sucedido imprime exatamente um objeto JSON no stdout. Erros são JSON tipado no stderr:

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

Analise os dois fluxos separadamente — nunca os mescle com 2>&1 e parseie o texto combinado. code e details são a base legível por máquina para decisões; message é para humanos. --json pode vir antes ou depois de um subcomando conhecido; coloque-o antes do comando para obter erros em JSON para comandos de topo desconhecidos. Códigos de saída:

0 — sucesso (também --help e --version).
1 — um erro de domínio (erro tipado no stderr), possivelmente com um corpo parcial e inspecionável no stdout; também Unsupported para comandos de topo não implementados.
2 — argumentos ausentes ou inválidos, ou subcomandos aninhados desconhecidos; InvalidInput no modo --json.

Onde a CLI termina e o MCP começa

A CLI e o servidor MCP expõem o mesmo estado de domínio: para as ferramentas compartilhadas de trabalho e contexto, ambos retornam os mesmos identificadores, versões, critérios de aceitação, dependências, diagnósticos e lacunas sob o mesmo projeto, seleção de branch, fonte indexada e parâmetros. A diferença é a postura:

A CLI é o ponto de entrada completo de gestão do projeto, e suas leituras podem atualizar projeções de banco de dados reconstruíveis (source_refresh).
As ferramentas de leitura do MCP são estritamente somente leitura (read_only=true). Se a fonte mudou, uma leitura MCP recusa o snapshot desatualizado com SourceStale em vez de atualizá-lo; rode awr source reindex e leia de novo.
O MCP stdio expõe um catálogo fixo de ferramentas para clientes de agentes (o serviço HTTP compartilhado adiciona ferramentas de diretório de projetos); a administração além desse catálogo fica na CLI.

Na prática, você conduz a configuração, a administração, a reindexação e a investigação ad hoc pelo terminal, enquanto o seu cliente de agente chama ferramentas MCP durante uma sessão. Veja Ferramentas MCP para o lado do agente e Solução de problemas quando algo der errado.