CLI

Controla toda la observabilidad de Failproof AI desde la terminal o un script: sin idas y vueltas al dashboard. El CLI agenteye consulta tus datos (sesiones, registros de eventos, evaluaciones) y administra tu organización (claves de API, usuarios, configuraciones, alertas, incidentes, consultas guardadas), así que úsalo cuando quieras automatizar una verificación, integrar Observabilidad en CI, o permitir que un agente de código inspeccione producción. Todos los comandos admiten el flag --json, por lo que funciona igual de bien para ti en un prompt o para un agente de código (Claude Code, Cursor) que ejecuta el comando y parsea el resultado. Con un solo binario puedes:

Leer tus datos: sessions, events, evals, errors (filtra por tiempo, agente, entorno, puntuación).
Administrar tu organización: keys, users, settings, alerts, incidents.
Ejecutar análisis: SQL guardado y un ejecutor de consultas ad-hoc (query).
Consultar al asistente de IA: el mismo analista de solo lectura con el que chateas en el dashboard (agent).

Nota: Este es el CLI agenteye, una herramienta distinta del daemon recolector (agenteye-collector). El CLI se comunica con tu dashboard; el recolector envía eventos al servidor.

Inicio rápido

De cero a tu primer resultado en cuatro líneas. Apunta el CLI a tu dashboard, inicia sesión, confirma quién eres y luego extrae el último día de ejecuciones:

pipx install agenteye
agenteye --base-url https://agenteye.example.com login --email you@example.com   # código de 6 dígitos enviado por email
agenteye whoami                                                                  # confirma usuario + org activa
agenteye --json sessions --since 24h                                             # una fila por ejecución de agente, últimas 24h

Ese último comando imprime un objeto JSON con las sesiones más recientes (más nuevas primero, limitado a 50 por defecto). Pásalo por jq para filtrarlo, o quita --json para obtener una tabla enmarcada y con colores. Cada fila contiene el estado de la ejecución y, si un evaluador la puntuó, sus métricas (abreviadas aquí):

{
  "sessions": [
    {
      "session_id": "run-8f2a",
      "agent_id": "checkout-bot",
      "environment": "prod",
      "status": "error",
      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
      "event_count": 37,
      "started_at": "2026-07-16T09:14:02Z",
      "last_event_at": "2026-07-16T09:14:48Z"
    }
  ],
  "next_cursor": null
}

El resto de esta página explica cada parte: instalación en aislamiento, inicio de sesión, configuración, las convenciones globales que comparten todos los comandos, y la referencia completa de comandos.

Instalación

El CLI es un paquete público de PyPI llamado agenteye. Instálalo en un entorno aislado para que siempre tenga sus propias dependencias:

pipx install agenteye
# o
uv tool install agenteye

Requiere Python 3.10+. El comando instalado es agenteye:

agenteye --version
agenteye --help

Nota: El SDK de Python de Observabilidad de Failproof AI también usa el nombre de distribución agenteye. Instalar el CLI con pipx o uv tool (en lugar de pip install en un virtualenv compartido) evita conflictos entre ambos. Un simple pip install agenteye solo es seguro si el SDK no está instalado en el mismo entorno.

Autenticación

El CLI se autentica en el dashboard con un código de un solo uso enviado por email:

agenteye login --email you@example.com
# Se te envía un código de 6 dígitos por email; pégalo en el prompt.

El token de sesión se almacena en ~/.agenteye/cli.json (legible solo por ti, modo 0600) y es válido por 24 horas por defecto. Cuando expire, ejecuta agenteye login de nuevo.

agenteye whoami     # muestra el usuario actual, la org activa y los permisos
agenteye logout     # revoca la sesión y elimina el token almacenado

whoami nunca falla por una sesión ausente o expirada; en su lugar reporta logged_in: false, por lo que un script o agente puede verificar el estado de autenticación de forma segura (igual puede salir con código distinto de cero si no hay URL base configurada o el dashboard no está disponible). Requisitos: tu email debe tener permiso para iniciar sesión en el dashboard (consulta a tu administrador de Observabilidad de Failproof AI), y el dashboard debe ser accesible en su URL base (ver Configuración). Si solicitas un código y no llega, probablemente tu email todavía no tiene acceso habilitado al dashboard.

Elegir tu organización (multi-tenant)

Si tu cuenta pertenece a más de una organización, elige la activa al iniciar sesión; se guarda y se usa en todos los comandos posteriores:

agenteye login --org acme           # autentícate y establece el tenant activo en un solo paso
agenteye orgs list                  # las orgs a las que tienes acceso (la activa aparece marcada)
agenteye orgs switch globex         # cambia el valor predeterminado guardado
agenteye --org globex sessions      # anula la org solo para un comando

Si perteneces a exactamente una org, se selecciona automáticamente y puedes ignorar --org por completo. Si perteneces a varias y no eliges una, el CLI las lista y te pide que vuelvas a ejecutar con --org <slug>. La org activa se envía al dashboard en cada solicitud, y tus permisos se resuelven por org; agenteye whoami muestra la org activa, tus permisos en ella y todas tus membresías.

Configuración

Parámetro	Flag	Variable de entorno	Por defecto
URL base del dashboard	`--base-url`	`AGENTEYE_DASHBOARD_URL`	requerida (sin valor predeterminado)
Org/tenant activo	`--org`	`AGENTEYE_ORG`	elegida al iniciar sesión; guardada en `~/.agenteye/cli.json`
Token de sesión	`--token`	`AGENTEYE_CLI_TOKEN`	desde `~/.agenteye/cli.json`
Salida JSON	`--json`	`AGENTEYE_CLI_JSON`	desactivado
Omitir verificación TLS	`--insecure` / `--secure`	`AGENTEYE_INSECURE`	desactivado (guardado al iniciar sesión)
Tiempo de espera de solicitud (segundos)	`--timeout`	(ninguna)	30
Deshabilitar telemetría de uso	(ninguna)	`AGENTEYE_ANALYTICS_DISABLED` (o `DO_NOT_TRACK`)	la telemetría está actualmente deshabilitada; no se envía nada

El orden de resolución es flag → variable de entorno → archivo de configuración. No hay valor por defecto; debes apuntar el CLI a tu dashboard, ya sea por comando (--base-url https://agenteye.example.com) o una vez mediante la variable de entorno (también se guarda tras tu primer login):

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com

El directorio de configuración respeta AGENTEYE_HOME (la misma convención que usan el SDK y el recolector); si está definido, cli.json se ubica en $AGENTEYE_HOME/cli.json.

TLS autofirmado o interno

Si tu dashboard se sirve sobre HTTPS con un certificado autofirmado o interno (por ejemplo, el nombre de host de un balanceador de carga), la verificación TLS lo rechazará con un error CERTIFICATE_VERIFY_FAILED. Usa --insecure para omitir la verificación de certificados:

agenteye --base-url https://agenteye.internal --insecure login

--insecure se guarda en cli.json al iniciar sesión, por lo que los comandos posteriores omiten la verificación automáticamente; no necesitas repetir el flag. Usa --secure para una llamada verificada puntual, o para volver a habilitar la verificación en tu próximo inicio de sesión. El CLI muestra una advertencia en stderr antes de cualquier comando que contacte el dashboard con la verificación deshabilitada. Omitir la verificación elimina la protección contra ataques de intermediario (man-in-the-middle); asegúrate de confiar en la ruta de red a tu dashboard (VPN, subred privada, etc.) antes de depender de esta opción.

Telemetría y privacidad

Nota: El CLI incluido no envía telemetría de uso hoy en día. Hay un interruptor maestro activado, por lo que no se transmite nada independientemente de tu entorno. La sección a continuación describe la capacidad de exclusión voluntaria para el caso de que la telemetría alguna vez se habilite.

Incluso cuando esté habilitada, la telemetría sería únicamente análisis de uso anónimos, nunca datos de tu agente, sesión o eventos:

Ningún dato de agente, sesión o evento sale jamás de tu infraestructura. Solo se reportaría el uso del CLI: el nombre del comando y subcomando (p. ej., keys create), los nombres de los flags que usaste (nunca sus valores), estado de éxito/salida, y duración, más un evento por acción para mutaciones (p. ej., api_key_created, query_run) que solo lleva nombres/enums estáticos y conteos aproximados. Tu URL de dashboard, token de sesión, email, slug de org, IDs de recursos, SQL, secretos de claves y filtros de consulta nunca se enviarían. Los operadores se identificarían únicamente por un ID interno opaco, nunca por email.
Excluirte con antelación establece AGENTEYE_ANALYTICS_DISABLED=1 en el entorno del CLI (el CLI también respeta la convención multiplataforma DO_NOT_TRACK=1). Esto tiene efecto en el momento en que la telemetría se active, por lo que un entorno con conciencia de privacidad puede permanecer excluido permanentemente.
Si la telemetría estuviera habilitada, el CLI enviaría directamente a PostHog (https://us.i.posthog.com); una máquina con ese host bloqueado simplemente no enviaría nada y el CLI no se vería afectado.

Opciones globales y convenciones

Lee esto una vez; aplica a todos los comandos.

Las opciones globales van ANTES del comando. agenteye --json sessions es correcto; agenteye sessions --json es un error de uso. Las globales son --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet y --no-color.
--json imprime JSON puro en stdout, y nada más. Las líneas de estado para humanos, advertencias y errores van a stderr, por lo que una captura de stdout con --json se mantiene limpia para pasar a jq incluso cuando se muestra una línea de estado. Sin --json obtienes una vista enmarcada y con colores para lectura humana.
Explora con --help. Cada comando y subcomando tiene --help (y el alias -h): agenteye -h, agenteye sessions -h, agenteye keys create -h. La ayuda de nivel superior también lista los códigos de salida y las opciones globales. No hay un volcado de superficie legible por máquina a nivel global; usa --help por comando, más los específicos de dominio agenteye query schema y agenteye settings schema para esos dos registros.
Las confirmaciones se omiten automáticamente en scripts y agentes. Los comandos de creación/actualización/eliminación muestran el mensaje “¿estás seguro?” en una terminal interactiva, pero omiten ese prompt automáticamente con --json o cuando stdin no es un TTY (un TTY es una sesión de terminal interactiva; una tubería o un runner de CI no lo es), por lo que los scripts y agentes nunca quedan bloqueados. Usa --yes/-y para omitirlo explícitamente. Como el prompt no se mostrará para un agente, este debería confirmar las acciones destructivas con el humano primero.
Paginación: los resultados están ordenados de más nuevo a más antiguo y paginados por cursor (cada página devuelve un token que usas para obtener la siguiente). --limit N (alias -n) limita las filas y por defecto es 50; --all pagina automáticamente (en bloques de 200 filas) hasta --limit, por lo que un --all sin más aún se detiene en 50. Para un barrido completo, pasa un límite explícito alto: --all --limit 1000. --page-size N controla el bloque por solicitud (máximo 200); --cursor <id> reanuda desde el next_cursor de una página anterior.
Filtros de tiempo: --since acepta una ventana relativa: 15m, 1h, 6h, 24h, 7d, o all (los presets del dashboard). Para un rango más largo o personalizado (digamos los últimos 30 días), usa --from/--to: timestamps UTC explícitos en ISO-8601 con T y zona horaria (p. ej., 2026-06-01T00:00:00Z) que sobreescriben --since. Un valor separado por espacios o sin zona horaria es un error de uso.
--fields a,b,c (en events, sessions, evals, errors) restringe la salida a esas claves, tanto en la tabla como en --json. Los nombres desconocidos se rechazan con la lista válida, una forma rápida de descubrir los nombres de campos.
--file payload.json (o --file - para leer stdin) proporciona un cuerpo de solicitud JSON completo donde un recurso tiene una forma compleja (en alerts create/update, settings set y users create/update). El SQL de consultas guardadas usa --sql @file.sql en su lugar.
Los filtros de múltiples valores son separados por comas → se comparan como un conjunto (unión dentro de un filtro, AND entre filtros): --event-type tool_use,tool_result. Las opciones de Click no son variádicas, así que --add a b no funciona. Usa --add a,b, repite el flag (--add a --add b), o entrecomíllalo (--add "a b").

Referencia de comandos

Los 5 comandos que más usarás

La mayor parte del trabajo diario se realiza con un puñado de comandos de lectura. Empieza aquí y recurre a la superficie completa cuando lo necesites:

Comando	Qué hace	Pruébalo
`sessions`	Una fila por ejecución de agente: tiempo, entorno, agente, estado, última puntuación.	`agenteye --json sessions --since 24h --status error`
`events`	El rastro sin procesar de cada paso dentro de una ejecución (añade `--full` para los payloads).	`agenteye --json events --session-id run-001 --all`
`evals`	Resultados de evaluación y puntuaciones; `--aggregate` los agrupa.	`agenteye --json evals --aggregate --since 7d --env prod`
`errors`	Solo los eventos con error; `--aggregate` para conteos por tipo.	`agenteye --json errors --since 24h --aggregate`
`list`	Descubre los valores de filtro válidos (agentes, entornos, modelos, …).	`agenteye list agents`

Todo lo que puede hacer el CLI

La superficie completa aparece a continuación. El CLI tiene 18 comandos de nivel superior. Todos los comandos de lectura aceptan --json y las opciones globales anteriores; ejecuta agenteye <command> -h (o <command> <subcommand> -h) para la lista exhaustiva de flags y la forma JSON de cualquiera.

agenteye login --email you@example.com [--org acme]   # código de un solo uso por email; guarda la sesión
agenteye logout                                       # limpia la sesión guardada en esta máquina
agenteye whoami                                       # usuario actual, org activa, permisos
agenteye version                                      # muestra la versión del CLI (igual que --version)
agenteye help                                         # ayuda de nivel superior (igual que --help)

orgs inspecciona y cambia el tenant activo:

agenteye orgs list        # tus orgs + tu rol en cada una (la activa aparece marcada)
agenteye orgs switch acme # cambia la org activa guardada (omite el slug para elegir de una lista en TTY)
agenteye orgs current     # tarjeta de identidad de la org activa
agenteye orgs perms       # tus permisos en la org activa, agrupados por recurso

Observar (solo lectura): `events` · `sessions` · `evals` · `errors` · `list`

Ninguno de estos requiere confirmación. Filtros compartidos: --session-id, --agent-id, --env (no --environment), y el rango de tiempo (--since / --from / --to).

# events (alias: el rastro sin procesar por paso), más nuevos primero
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'

# sessions: una fila por ejecución de agente (tiempo/entorno/agente/sesión/estado; sin filtrado por puntuación)
agenteye --json sessions --since 24h --status error
agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000

# evals: resultados de evaluación + puntuaciones; --score filtra por métrica, --aggregate agrupa
agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
agenteye --json evals --aggregate --since 7d --env prod        # mezcla de estados + estadísticas de puntuación por clave

# errors: eventos con error; --aggregate para conteos/sesiones/agentes/última aparición
agenteye --json errors --since 24h --aggregate
agenteye --json errors --since 24h --error-type timeout --all --limit 1000

# list: descubre los valores de filtro válidos antes de filtrar
agenteye list envs        # también: agents event_types score_filters models hooks tools error_types

--score KEY:MIN..MAX (en evals, no en sessions) es repetible y se combina con AND; cualquiera de los límites es opcional (..0.5 significa ≤ 0.5, 0.9.. significa ≥ 0.9). Hasta 20 filtros de puntuación por solicitud. evals --scores-full es un flag de visualización solo para la tabla humana; muestra todos los pares de puntuación en lugar de los primeros más un conteo +N. No tiene efecto con --json, que siempre devuelve el objeto de puntuación completo. Para leer una sesión de principio a fin, combina el rastro de eventos con su evaluación:

agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
agenteye --json evals  --session-id run-001                       # sus puntuaciones + estado

Administrar (con permisos requeridos): `keys` · `users` · `settings` · `alerts` · `incidents`

keys: claves de API. El secreto se genera localmente, se envía al servidor (que solo almacena un hash), y se muestra una única vez al crear/regenerar; captúralo en ese momento. Con --json aparece solo en el campo key. Se referencian por nombre.

agenteye keys list                                   # claves activas primero, luego revocadas
agenteye keys show ci-bot
agenteye keys create ci-bot --add events:read.add    # limita al alcance necesario; imprime el secreto UNA VEZ
agenteye keys create ops --permission-set standard --remove queries:run   # comienza con un preset y recorta
agenteye keys update ci-bot --add evaluations:read --yes
agenteye keys regenerate ci-bot --yes                # rota el secreto (el anterior deja de funcionar)
agenteye keys disable ci-bot --yes                   # revoca

Los permisos funcionan como (permission-set ∪ --add) − --remove. Los tokens son slug:acción (p. ej., events:read) o slug:acción.acción para expandir varios en un recurso (events:read.add → events:read, events:add). Presets: read-only, standard, admin. Los permisos exclusivos de humanos (keys:update) no pueden concederse a una clave. users: miembros de la org, referenciados por email (también se acepta un UUID id).

agenteye users list [--active-only]
agenteye users show dev@corp.com
agenteye users create dev@corp.com --permission-set standard
agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # predice + confirma
agenteye users disable dev@corp.com --yes            # tiene protecciones de usuarios protegidos/propios
agenteye users enable dev@corp.com

settings: un registro fijo (lees y cambias claves existentes; no puedes crear nuevas).

agenteye settings list                               # clave · valor · tipo · actualizado (secretos enmascarados)
agenteye settings schema                             # lo que acepta cada clave (tipo · rango · descripción)
agenteye settings set session_ttl_secs --value 86400 --yes

alerts: definiciones de alertas, referenciadas por nombre. create toma un NAME posicional más flags o un cuerpo JSON completo vía --file.

agenteye alerts list
agenteye alerts show high-errors
agenteye alerts create high-errors --file alert.json          # NAME es requerido (posicional)
agenteye alerts update high-errors --severity critical --yes
agenteye alerts test high-errors --yes                        # dispara una notificación de prueba
agenteye alerts delete high-errors --yes

incidents: incidentes de alertas, referenciados por ID (se aceptan IDs cortos). show imprime el registro de actividad completo; léelo antes de actuar.

agenteye incidents list --state firing                # también: acknowledged, resolved
agenteye incidents count
agenteye incidents show <id>
agenteye incidents ack <id>
agenteye incidents assign <id> you@corp.com           # el asignado debe ser un operador
agenteye incidents resolve <id> --yes
agenteye incidents open --alert-id <id> --severity critical    # abre uno manualmente contra una alerta
agenteye incidents comment-add <id> "root cause: upstream 5xx"
agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>

Análisis y asistente: `query` · `agent`

query: SQL guardado contra tu almacén de análisis más un ejecutor ad-hoc. Las consultas guardadas se referencian por nombre; el SQL se valida en el servidor (solo SELECT/WITH, timeout de declaración, límite de filas).

agenteye query schema [TABLE]                         # estructura de columnas de las vistas de análisis
agenteye query run --sql "select count(*) from analytics.events"
agenteye query run errs --arg prod --limit 100        # ejecuta una consulta guardada + un $1 posicional
agenteye query list ; agenteye query show errs
agenteye query create errs --sql @errs.sql --description "errored events (24h)"
agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes

agent: habla con el asistente de IA integrado (el mismo analista de solo lectura con el que puedes chatear en el dashboard). Los chats se referencian por un chat-id corto (resuelto por prefijo).

agenteye agent health                                 # si el asistente de IA está configurado/accesible
agenteye agent models                                 # modelos que puedes pasar a --model (el predeterminado aparece marcado)
agenteye agent ask "which agents errored most in the last day?"    # inicia un chat; imprime su ID corto
agenteye agent ask --chat <short-id> "and which tools did they call?"   # continúa ese chat
agenteye agent chats ; agenteye agent show <short-id>
agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>

Códigos de salida

Código	Significado
0	Éxito
1	Error inesperado (p. ej., el dashboard devolvió un 5xx)
2	Error de uso (argumentos inválidos, comando/flag desconocido, colisión de nombres)
3	No se puede alcanzar el dashboard
4	No has iniciado sesión o la sesión expiró; ejecuta `agenteye login`
5	Autenticado, pero tu cuenta no tiene el permiso requerido (el mensaje lo nombra)
6	El recurso solicitado no se encontró (p. ej., sesión o ID de incidente desconocido)

Esto hace que el CLI sea seguro para usar en scripts: un agente de código puede ramificar en un 4 para pedirte que te vuelvas a autenticar, o en un 5 para mostrar el permiso faltante. Consulta recetas de CLI para agentes para patrones de manejo de códigos de salida y formas de salida JSON.

Próximos pasos

Recetas de CLI para agentes: patrones de consulta listos para copiar, one-liners de jq, proyecciones con --fields, manejo de códigos de salida y formas de salida JSON, escritos para agentes de código que controlan el CLI.
Habilidad de CLI para agentes: empaqueta este CLI como una skill instalable de Claude Code / Codex para que un agente de código controle la Observabilidad de Failproof AI desde solicitudes en lenguaje natural.
Claves de API: el modelo de permisos detrás de keys create --add ….
Asistente de IA: cómo habilitar el asistente con el que habla agent ask.

Overview

Features

SDK and CLI

Administration

Inicio rápido

Instalación

Autenticación

Elegir tu organización (multi-tenant)

Configuración

TLS autofirmado o interno

Telemetría y privacidad

Opciones globales y convenciones

Referencia de comandos

Los 5 comandos que más usarás

Todo lo que puede hacer el CLI

Observar (solo lectura): `events` · `sessions` · `evals` · `errors` · `list`

Administrar (con permisos requeridos): `keys` · `users` · `settings` · `alerts` · `incidents`

Análisis y asistente: `query` · `agent`

Códigos de salida

Próximos pasos

​Inicio rápido

​Instalación

​Autenticación

​Elegir tu organización (multi-tenant)

​Configuración

​TLS autofirmado o interno

​Telemetría y privacidad

​Opciones globales y convenciones

​Referencia de comandos

​Los 5 comandos que más usarás

​Todo lo que puede hacer el CLI

​Identidad: login · logout · whoami · orgs · version · help

​Observar (solo lectura): events · sessions · evals · errors · list

​Administrar (con permisos requeridos): keys · users · settings · alerts · incidents

​Análisis y asistente: query · agent

​Códigos de salida

​Próximos pasos

Inicio rápido

Instalación

Autenticación

Elegir tu organización (multi-tenant)

Configuración

TLS autofirmado o interno

Telemetría y privacidad

Opciones globales y convenciones

Referencia de comandos

Los 5 comandos que más usarás

Todo lo que puede hacer el CLI

Identidad: `login` · `logout` · `whoami` · `orgs` · `version` · `help`

Observar (solo lectura): `events` · `sessions` · `evals` · `errors` · `list`

Administrar (con permisos requeridos): `keys` · `users` · `settings` · `alerts` · `incidents`

Análisis y asistente: `query` · `agent`

Códigos de salida

Próximos pasos