Uso de la CLI

La herramienta de línea de comandos awr es el punto de entrada de gestión completo para un proyecto AWR: todo lo que un agente puede hacer a través de MCP, tú puedes hacerlo desde tu terminal, además de la administración del proyecto que MCP no expone.

Instalación

Ambos canales de paquetes instalan la misma CLI en Rust y el mismo servidor MCP; no existe un SDK separado de JavaScript o 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

Verifica con awr --version y awr-mcp --version.

Los objetivos soportados son macOS 15+ (arm64 e Intel), Linux con glibc 2.39+ (la línea base de Ubuntu 24.04, x64 y arm64) y Windows x64. El lanzador de npm requiere Node 22.14+ y depende de paquetes nativos opcionales, así que mantén las dependencias opcionales activadas; el lanzador de PyPI requiere Python 3.9+. En Linux, comprueba glibc con ldd --version | head -n 1. Git solo se necesita para las operaciones vinculadas a Git; SQLite va incluido. Para un recorrido del primer proyecto, consulta Inicio rápido.

La forma de cada comando

Los ejemplos de la CLI en toda la documentación comparten un prefijo común:

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

--project apunta a la raíz del proyecto; --json cambia stdout a un único objeto JSON legible por máquina (detalles abajo). Quita --json cuando leas la salida tú mismo: la salida humana predeterminada está deliberadamente acotada: status muestra como máximo una sugerencia actual y ready lista como máximo 10 elementos.

Comprobar dónde está el proyecto

status es tu primera parada. Su vista action predeterminada muestra la continuación actual, el trabajo reservable, las esperas, los bloqueos reales y un resumen del historial:

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

--view action/full/summary — el valor predeterminado es action; full da la estructura completa heredada.
--branch NAME_OR_ID — lee una rama por nombre, ID interno o main en lugar de la rama predeterminada. Seleccionar una rama para una lectura nunca cambia la rama predeterminada, las sesiones, las reservas ni tu checkout de Git.

ready lista los elementos de trabajo que se pueden tomar, con diagnósticos, información de reserva y avisos de truncamiento. --limit tiene como valor predeterminado 10 y acepta de 1 a 100; --branch también funciona aquí:

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

Leer elementos de trabajo

work show da un elemento completo: tarea, criterios de aceptación, dependencias, decisiones, evidencia y procedencia. --source-sha SHA lo lee tal como estaba en una revisión de fuente específica; --branch lo lee en otra rama:

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

search encuentra elementos en todo el proyecto. El texto de consulta es posicional; --type, --status, --work y --limit acotan los resultados:

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

Compilar contexto para una tarea

context compile reúne el contexto de ejecución L1 — el conjunto de trabajo presupuestado para una tarea — con completitud, lagunas, procedencia y el hash de contexto:

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

Todas estas opciones son opcionales: --session y --detached controlan la vinculación de sesión; --agent, --intent y --budget orientan la compilación; --goal, --path y --tag son repetibles; --source-sha compila contra una versión de fuente específica; --checkpoint y --after-revision establecen líneas base personalizadas y son mutuamente excluyentes. --branch ID usa la línea base de contexto ordinaria en otra rama: un significado distinto al de branch context, que compila el incremento de una rama con nombre desde que se bifurcó, sin cambiar tu rama predeterminada:

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

La salida de texto predeterminada es el contexto de ejecución limitado por presupuesto con los criterios de aceptación completos y las reglas duras preservadas. Si existen lagunas requeridas, el resultado JSON tiene ok=false con error.code=ContextIncomplete; si los hechos duros exceden el presupuesto obtienes BudgetExceeded: nunca hechos truncados silenciosamente.

Hacer avanzar el trabajo

Los elementos de trabajo cambian de estado a través de los subcomandos de work:

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

La misma forma se aplica a block, unblock, cancel y reopen, con --next-action, --summary y --blocker llevando los detalles correspondientes. La finalización vincula criterios de aceptación y evidencia desde un archivo JSON y libera la reserva de esta sesión en caso de éxito:

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

Registrar eventos y evidencia

event append escribe en el registro del proyecto:

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

Banderas opcionales: --work, --session, --branch, --importance (predeterminado normal) y --payload FILE (un archivo de valor JSON, {} cuando se omite). La salida predeterminada muestra el ID, el tipo, un resumen corto y la versión: no repite el payload; usa event show --full para expandir un evento explícitamente. No puedes falsificar eventos de dominio reservados como work.completed; esos solo provienen de los comandos de cambio de estado.

evidence add registra evidencia desde un archivo JSON de entrada:

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

Los campos de entrada incluyen work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope y verified_at. Una escritura correcta devuelve el registro guardado y un event_id, pero registrar no es ejecutar: validation_basis=caller_supplied_bindings significa que AWR almacenó las vinculaciones que enviaste, no que ejecutó tu comando ni que la aceptación de negocio se superó. evidence show da la vista de lectura resumida de un registro; no es un recibo de escritura.

Reglas de rutas y tamaños: las rutas relativas en la entrada de evidencia y en los payloads de eventos se resuelven contra la raíz de --project; las rutas relativas en una entrada de finalización se resuelven contra el directorio actual del proceso, así que usa rutas absolutas en la automatización. La entrada de evidencia y los archivos de payload de eventos tienen un tope de 1 MiB, y las entradas de finalización de 64 KiB.

Revisiones y concurrencia optimista

Las escrituras aceptan --expected-revision R, donde R es la project_revision más reciente que observaste. Si el proyecto ha avanzado, la escritura falla con RevisionConflict en lugar de sobrescribir silenciosamente el trabajo de otra persona: vuelve a leer con status y reintenta contra la nueva revisión. Tres números de versión aparecen en la salida y no son intercambiables: revision es la versión de un objeto, source_revision es la versión de la fuente y project_revision es la versión del estado del proyecto.

Si una escritura se interrumpe o se aplica parcialmente, comprueba la propuesta, los eventos, la sesión y la revisión actual antes de decidir qué hacer a continuación: no reintentes a ciegas tras un fallo de proceso. Dos errores de workspace merecen mención: WorkspaceConflict (de awr workspace) significa que ambas partes editaron el mismo archivo rastreado y nada se fusiona automáticamente; WorkspaceContended significa que un publish o drop fue interrumpido tres commits seguidos, y el remedio es simplemente ejecutar el mismo comando de nuevo.

Salida JSON, errores y códigos de salida

Con --json, un comando correcto imprime exactamente un objeto JSON en stdout. Los errores son JSON tipado en stderr:

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

Analiza los dos flujos por separado: nunca los combines con 2>&1 y analices el texto combinado. code y details son la base legible por máquina para las decisiones; message es para humanos. --json puede ir antes o después de un subcomando conocido; ponlo antes del comando para obtener errores JSON en comandos de nivel superior desconocidos. Códigos de salida:

0 — éxito (también --help y --version).
1 — un error de dominio (error tipado en stderr), posiblemente con un cuerpo parcial e inspeccionable en stdout; también Unsupported para comandos de nivel superior no implementados.
2 — argumentos ausentes o inválidos o subcomandos anidados desconocidos; InvalidInput en modo --json.

Dónde termina la CLI y empieza MCP

La CLI y el servidor MCP exponen el mismo estado de dominio: para las herramientas compartidas de trabajo y contexto, ambos devuelven los mismos identificadores, versiones, criterios de aceptación, dependencias, diagnósticos y lagunas bajo el mismo proyecto, selección de rama, fuente indexada y parámetros. La diferencia es la postura:

La CLI es el punto de entrada completo de gestión del proyecto, y sus lecturas pueden actualizar proyecciones de base de datos reconstruibles (source_refresh).
Las herramientas de lectura MCP son estrictamente de solo lectura (read_only=true). Si la fuente ha cambiado, una lectura MCP rechaza la instantánea obsoleta con SourceStale en lugar de actualizarla; ejecuta awr source reindex y lee de nuevo.
MCP stdio expone un catálogo fijo de herramientas para clientes de agentes (el servicio HTTP compartido añade herramientas de directorio de proyectos); la administración más allá de ese catálogo queda en la CLI.

En la práctica, diriges la configuración, la administración, la reindexación y la investigación ad hoc desde la terminal, mientras tu cliente de agente llama a las herramientas MCP durante una sesión. Consulta Herramientas MCP para el lado del agente y Solución de problemas cuando algo vaya mal.