Referencia del CLI

Comandos, flags, variables de entorno y códigos de salida del CLI tallygraph.

Corre cualquier comando con npx --yes tallygraph, o instálalo global con npm i -g tallygraph. tallygraph help imprime la lista completa.

Uso

Comando	Qué hace
`collect --token T`	Descubre agentes locales, encola su uso y lo sube.
`collect --watch`	Lo mismo, repetido cada --interval segundos (900 por defecto).
`collect --dry-run`	Solo valida. Sin red y sin escribir en el spool.
`read [fuente]`	Imprime eventos como líneas JSON. Nunca manda nada.
`collect --file events.jsonl`	Sube eventos que generaste tú (usa - para stdin).
`service install \| status \| uninstall`	Administra el servicio en segundo plano.
`tap [-- cliente]`	Proxy local que anota el uso de la API en vivo.
`agent --team T -- claude [args]`	Corre un cliente contra tu gateway con una llave emitida; las credenciales de proveedor de la shell no se pasan.
`security enroll \| collect \| status \| disable`	Reportes opcionales de seguridad de sesiones. Ver Seguridad de sesiones.

Un collect exitoso también publica un reporte de runtimes: un id de instalación aleatorio guardado en TALLYGRAPH_STATE_DIR/install-id, más las versiones del CLI, de Node y de los CLIs de los agentes del batch. Alimenta los findings sobre runtimes viejos. Si falla avisa y sigue saliendo con 0.

Consultar tus datos

Estos comandos usan un token de lectura, que también se crea en Conectores. Responden en el idioma de la terminal (de LC_ALL o LANG) cuando hay traducción.

Comando	Qué hace
`spend [--days N] [--json]`	Gasto del workspace por servicio.
`findings [--json]`	Hallazgos abiertos con ahorro estimado.
`guard activity [--days N] [--json]`	Bloqueos de Guard, salud y contadores de privacidad (pide token de lectura de owner).
`mcp`	Servidor MCP de solo lectura por stdio con get_spend, get_findings y get_guard_activity.

Auditorías sin conexión

Estos nunca suben nada.

Comando	Qué hace
`scan [--staged \| --all]`	Busca secretos en archivos staged o versionados. Sirve como hook de pre-commit.
`exposure`	Secretos que tus agentes mandaron a proveedores en los últimos 30 días.
`trifecta`	Sesiones que juntaron datos privados, contenido no confiable y una vía de salida.
`navwaste`	Cómo se reparten las sesiones de Claude entre navegar, editar y ejecutar.

Variables de entorno

Variable	Para qué
`TALLYGRAPH_WRITE_TOKEN`	Token de escritura para collect y tap, en vez de --token.
`TALLYGRAPH_READ_TOKEN`	Token de lectura para spend, findings y mcp.
`TALLYGRAPH_ENDPOINT`	URL propia de ingesta o de la app. Por defecto www.tallygraph.dev.
`TALLYGRAPH_STATE_DIR`	Ubicación del spool. Por defecto ~/.tallygraph.

Códigos de salida de collect

Código	Significado
0	Todo entregado.
1	Error inesperado.
2	La API rechazó el request. Las filas siguen en el spool.
3	No se pudo abrir el spool o está lleno.
4	Token inválido, revocado o vencido. Las filas siguen en el spool.
5	Se agotaron los reintentos. Las filas siguen; vuelve a correr para continuar.

Mandar tus propios eventos

Cualquier cosa que escriba líneas JSON puede reportar uso. Cada línea es un evento; los external_id repetidos se ignoran, así que puedes reenviar sin miedo.

events.jsonl

{"external_id":"run-42-call-1","service_slug":"anthropic","model":"claude-sonnet-5-5","input_tokens":1200,"output_tokens":340,"occurred_at":"2026-11-02T18:00:00Z"}

terminal

tallygraph collect --file events.jsonl --dry-run   # revisa primero
tallygraph collect --file events.jsonl --token tg_xxxxxxxx