Failproof Cloud CLI

Use fp para inspeccionar la telemetría de Cloud, gestionar la aplicación administrada en la nube (políticas, despliegues de flota, decisiones de guardrail) y administrar auditorías, hallazgos, incidencias, alertas, claves, usuarios, consultas y configuración. Use failproofai para hooks locales, políticas, captura e inscripción de máquinas. Instale el Cloud CLI publicado como herramienta aislada:

uv tool install fp-cloud-cli
fp version

Iniciar sesión

fp login
fp whoami

Sintaxis

fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS]

Las opciones globales deben ir antes del comando:

fp --json sessions --since 24h

Ejecute fp COMMAND --help o fp COMMAND SUBCOMMAND --help para obtener ayuda en la terminal.

Comandos de la CLI

Autenticación

Comando	Propósito	Opciones
`fp login`	Inicia sesión con un código de un solo uso enviado por correo y selecciona una organización.	`--email`, `-e`; `--org`; `--force`
`fp logout`	Revoca y elimina la sesión de usuario guardada.	—
`fp whoami`	Muestra la identidad actual, el modo de autenticación, la organización y los permisos.	—
`fp version`	Muestra la versión instalada de la CLI.	—
`fp help`	Muestra la ayuda de los comandos de nivel superior.	—

fp login --email you@example.com --org reliability-team
fp whoami

Eventos

fp events [OPTIONS]

Lista los eventos individuales de agentes. El feed ligero predeterminado excluye los payloads sin procesar; use --full solo para una investigación acotada.

Opción	Descripción
`--limit`, `-n <n>`	Máximo total de filas. Por defecto: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h` o `7d`.
`--from <timestamp>` / `--to <timestamp>`	Rango UTC en ISO 8601; reemplaza a `--since`.
`--env <value>`	Filtro de entorno; repita o separe con comas.
`--event-type <value>`	Filtro de tipo de evento; repita o separe con comas.
`--agent-id <value>`	Filtro de agente; repita o separe con comas.
`--session-id <value>`	Filtro de sesión; repita o separe con comas.
`--search <text>`	Búsqueda de texto en el payload; repetible, coincide con cualquier término.
`--order asc\|desc`	Orden temporal. Por defecto: más reciente primero.
`--all`	Pagina automáticamente hasta `--limit`.
`--cursor <token>`	Reanuda desde un cursor opaco.
`--page-size <n>`	Filas por solicitud con `--all`; máximo `200`.
`--full`	Incluye payloads sin procesar a través del endpoint de eventos más pesado.
`--fields <csv>`	Devuelve solo los campos seleccionados; solicitar `payload` activa el modo completo.

fp events --session-id <session-id> --order asc --all --limit 10000
fp --json events --full --session-id <session-id> --all --limit 10000

--all pagina hasta --limit, que por defecto es 50 — por lo que --all solo se detiene en 50 filas. Cuando se detiene antes de tiempo, la respuesta incluye un next_cursor para reanudar desde allí; "next_cursor": null significa que el feed realmente se agotó.

Sesiones

fp sessions [OPTIONS]

Opción	Descripción
`--limit`, `-n <n>`	Máximo total de filas. Por defecto: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h` o `7d`.
`--from <timestamp>` / `--to <timestamp>`	Rango UTC en ISO 8601; reemplaza a `--since`.
`--env <value>`	Filtro de entorno; repita o separe con comas.
`--status <value>`	`done`, `error` o `timeout`; repita o separe con comas.
`--agent-id <value>`	Coincide con sesiones que involucren algún agente seleccionado.
`--session-id <value>`	Filtro de sesión; repita o separe con comas.
`--all`	Pagina automáticamente hasta `--limit`.
`--cursor <token>`	Reanuda desde un cursor opaco.
`--page-size <n>`	Filas por solicitud con `--all`; máximo `200`.
`--fields <csv>`	Devuelve solo los campos seleccionados.
`--full-ids`	No abrevia los IDs de sesión en la salida de la terminal.
`--agents`	Expande el listado de agentes para sesiones multiagente.

Evaluaciones

fp evals [OPTIONS]

Opción	Descripción
`--aggregate`	Muestra totales y estadísticas por puntuación en lugar de evaluaciones individuales.
`--limit`, `-n <n>`	Máximo de filas en la lista. Por defecto: `50`.
`--since`, `--from`, `--to`	Selecciona el rango de tiempo.
`--env`, `--status`, `--agent-id`, `--session-id`	Limita a un valor exacto por filtro.
`--score KEY:MIN..MAX`	Rango de puntuación; repetible y todos los rangos deben coincidir.
`--all`, `--cursor`, `--page-size`	Controla la paginación de la lista.
`--fields <csv>`	Devuelve solo los campos seleccionados.
`--full-ids`	Muestra los IDs de sesión completos.
`--scores-full`	Muestra todas las puntuaciones en la salida de la terminal.

Errores

fp errors [OPTIONS]

Opción	Descripción
`--aggregate`	Resume los errores coincidentes en lugar de listar filas.
`--limit`, `-n <n>`	Máximo de filas en la lista. Por defecto: `50`.
`--since`, `--from`, `--to`	Selecciona el rango de tiempo.
`--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id`	Reduce el conjunto de errores.
`--search <text>`	Busca texto en el payload; repetible.
`--order asc\|desc`	Orden temporal.
`--all`, `--cursor`, `--page-size`	Controla la paginación de la lista.
`--fields <csv>`	Devuelve solo los campos seleccionados.
`--full-ids`	Muestra los IDs de sesión completos.

Uso y valores de filtro

Comando	Propósito
`fp usage`	Muestra el uso en la ventana de medición actual.
`fp list envs`	Lista los entornos observados.
`fp list agents`	Lista los IDs de agentes observados.
`fp list event_types`	Lista los tipos de evento.
`fp list score_filters`	Lista las claves de puntuación de evaluación.
`fp list models`	Lista los nombres de modelos.
`fp list hooks`	Lista los nombres de hooks.
`fp list tools`	Lista los nombres de herramientas.
`fp list error_types`	Lista los tipos de error.

Organizaciones

Comando	Propósito
`fp orgs list`	Lista las organizaciones accesibles.
`fp orgs switch [SLUG]`	Guarda una organización activa; solicita selección si se omite.
`fp orgs current`	Muestra la organización activa.
`fp orgs perms`	Muestra tus permisos en la organización activa.

Claves de API

Comando	Propósito	Opciones
`fp keys list`	Lista las claves de la organización.	`--show-id`; `--fields <csv>`
`fp keys show NAME`	Muestra una clave y sus permisos.	—
`fp keys create NAME`	Crea una clave y revela su secreto una sola vez.	`--permission-set`; `--add`; `--remove`
`fp keys update NAME`	Reemplaza el conjunto de permisos o ajusta los permisos concedidos.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp keys regenerate NAME`	Rota el secreto y revela el reemplazo una sola vez.	`--yes`, `-y`
`fp keys disable NAME`	Revoca permanentemente una clave.	`--yes`, `-y`

Los tokens de permiso usan el formato resource:action, como events:add. Repita --add, separe los tokens con comas o use acciones con puntos como events:read.add.

Consultas

Comando	Propósito	Opciones
`fp query list`	Lista las consultas guardadas.	`--show-id`; `--fields <csv>`
`fp query show NAME`	Muestra una consulta.	—
`fp query create NAME`	Guarda una consulta.	`--sql <text\|@file>`; `--description`
`fp query update NAME`	Actualiza o renombra una consulta.	`--name`; `--sql`; `--description`; `--yes`, `-y`
`fp query delete NAME`	Elimina una consulta guardada.	`--yes`, `-y`
`fp query run [NAME]`	Ejecuta una consulta guardada o SQL ad-hoc.	`--sql`; `--limit`; `--all`; `--arg`, `--param`
`fp query schema [TABLE]`	Lista las tablas consultables o inspecciona una tabla.	—

Usuarios

Comando	Propósito	Opciones
`fp users list`	Lista los miembros de la organización.	`--active-only`; `--show-id`
`fp users show EMAIL`	Muestra un miembro y sus permisos.	—
`fp users create EMAIL`	Agrega un miembro.	`--permission-set`; `--add`; `--remove`
`fp users update EMAIL`	Modifica los permisos de un miembro.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp users disable EMAIL`	Deshabilita el inicio de sesión.	`--yes`, `-y`
`fp users enable EMAIL`	Vuelve a habilitar el inicio de sesión.	`--yes`, `-y`

Configuración

Comando	Propósito	Opciones
`fp settings list`	Lista la configuración de la organización y sus valores actuales.	—
`fp settings schema`	Muestra los valores aceptados y sus descripciones.	—
`fp settings set KEY`	Modifica una configuración existente.	exactamente uno de `--value`, `--json-value`, `--file`; `--yes`, `-y` opcional

Alertas

Comando	Propósito	Opciones
`fp alerts list`	Lista las reglas de alerta.	`--show-id`
`fp alerts show NAME`	Muestra una alerta.	—
`fp alerts create NAME`	Crea una alerta.	`--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window`
`fp alerts update NAME`	Actualiza o renombra una alerta.	opciones de creación más `--name`; `--yes`, `-y`
`fp alerts delete NAME`	Elimina una alerta.	`--yes`, `-y`
`fp alerts test NAME`	Envía una notificación de prueba.	`--channels`; `--yes`, `-y`

Las severidades de alerta son info, warning y critical. Los tipos de disparador son metric_threshold, custom_sql, evaluation_score, eval_compound y per_event. Los intervalos de evaluación deben estar entre 30 y 86 400 segundos.

Auditorías

Comando	Propósito	Opciones
`fp audits list`	Lista las auditorías.	`--enabled-only`; `--show-id`
`fp audits show NAME`	Muestra una definición de auditoría y su estado.	—
`fp audits create NAME`	Crea una auditoría y pone en cola su primera ejecución inmediatamente.	Ver opciones de creación.
`fp audits edit NAME`	Reemplaza la configuración de la auditoría conservando los valores no especificados.	opciones de definición de creación; `--name`; `--yes`, `-y`
`fp audits delete NAME`	Elimina una auditoría, sus hallazgos y el historial de ejecuciones.	`--yes`, `-y`
`fp audits run NAME`	Pone en cola una ejecución manual.	—
`fp audits runs NAME`	Lista el historial de ejecuciones.	`--limit`, `-n`; `--show-id`
`fp audits context-show NAME`	Muestra el resumen y el estado de obtención de las URLs de referencia.	—
`fp audits context-set NAME`	Modifica el resumen o las URLs de referencia.	`--text`; `--text-file`; `--url`; `--clear-urls`
`fp audits context-refresh NAME`	Vuelve a obtener las URLs de referencia.	—
`fp audits findings`	Lista los hallazgos.	`--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id`
`fp audits finding FINDING_ID`	Muestra un hallazgo y su evidencia.	—
`fp audits ack FINDING_ID`	Confirma un hallazgo.	`--reason`
`fp audits mute FINDING_ID`	Suprime un patrón recurrente.	`--reason`; `--yes`, `-y`
`fp audits dismiss FINDING_ID`	Marca un patrón como no accionable y lo suprime.	`--reason`; `--yes`, `-y`
`fp audits resolve FINDING_ID`	Marca un hallazgo como resuelto sin supresión futura.	`--yes`, `-y`
`fp audits reopen FINDING_ID`	Devuelve un hallazgo a la cola activa y elimina la supresión.	—
`fp audits assign FINDING_ID`	Establece el responsable del hallazgo.	`--to <email>` obligatorio

Opciones de creación de auditorías

fp audits create checkout-reliability \
  --description "Find checkout failures that agents do not recover from" \
  --scope '{"environments":["production"],"agent_ids":["checkout-agent"]}' \
  --schedule-interval-secs 86400 \
  --window-mode since_last \
  --sensitivity medium \
  --text-file ./checkout-audit-brief.txt \
  --url https://runbooks.example.com/checkout

Opción	Descripción
`--file <path>`	Basa la definición en JSON, o use `-` para stdin. Los flags explícitos reemplazan los valores del archivo.
`--description <text>`	Describe la pregunta de fallo o el propósito.
`--enabled` / `--disabled`	Inicia la programación activada o desactivada. Por defecto: activada.
`--schedule-interval-secs <n>`	`3600`–`604800`. Por defecto: `86400`.
`--schedule-anchor <timestamp>`	Fase UTC fija en formato ISO 8601. Por defecto: próximas 09:00 UTC.
`--window-mode since_last\|fixed`	Continúa tras la última ventana completamente analizada o inspecciona repetidamente una ventana deslizante. Por defecto: `since_last`.
`--lookback-window-secs <n>`	`3600`–`7776000`. Por defecto: `604800`.
`--scope '<json>'`	Filtra por `environments`, `agent_ids` u otros campos de alcance admitidos.
`--ignore-error-type <type>`	Excluye tipos de error; repita o separe con comas.
`--llm` / `--no-llm`	Activa o desactiva el análisis agéntico. Por defecto: activado.
`--top-k <n>`	Retiene entre `1` y `500` hallazgos. Por defecto: `50`.
`--sensitivity low\|medium\|high`	Establece la sensibilidad de los informes. Por defecto: `medium`.
`--channels '<json>'`	Array de canales de notificación.
`--text <brief>`	Resumen en línea, máximo 8 192 caracteres.
`--text-file <path>`	Lee el resumen desde un archivo; excluyente con `--text`.
`--url <https-url>`	Agrega una referencia HTTPS pública; repita hasta cinco veces.

Incluya el contexto durante la creación cuando la primera ejecución lo necesite. La creación confirma la definición y el contexto juntos antes de que comience la ejecución en cola.

fp audits run es asíncrono. Consulte fp audits runs NAME hasta que la última ejecución tenga éxito o falle antes de leer sus hallazgos.

Incidencias

Comando	Propósito	Opciones
`fp issues list`	Lista las incidencias.	`--state`; `--alert-id`; `--limit`, `-n`; `--show-id`
`fp issues count`	Cuenta las incidencias abiertas o en los estados seleccionados.	`--state`
`fp issues show INCIDENT_ID`	Muestra los detalles de la incidencia, comentarios, suscriptores y actividad.	—
`fp issues open`	Abre una incidencia manual o vinculada a una alerta.	`--summary` obligatorio; `--title`, `--alert-id`, `--severity` opcionales
`fp issues ack INCIDENT_ID`	Confirma una incidencia.	—
`fp issues assign INCIDENT_ID`	Reemplaza los responsables; omita la opción para eliminarlos.	`--assignee` repetible
`fp issues resolve INCIDENT_ID`	Resuelve una incidencia.	`--yes`, `-y`
`fp issues comment-list INCIDENT_ID`	Lista los comentarios.	—
`fp issues comment-add INCIDENT_ID`	Agrega un comentario.	exactamente uno de `--body`, `--file`
`fp issues comment-delete INCIDENT_ID COMMENT_ID`	Elimina un comentario.	`--yes`, `-y`
`fp issues subscribers INCIDENT_ID`	Lista los suscriptores.	—
`fp issues subscribe INCIDENT_ID`	Suscribe al operador actual u otro operador.	`--email`
`fp issues unsubscribe INCIDENT_ID`	Elimina una suscripción.	`--email`

Los estados de incidencia válidos son firing, acknowledged y resolved. Las severidades de incidencias independientes son info, warning y critical.

Asistente en la nube

Comando	Propósito	Opciones
`fp agent health`	Verifica la disponibilidad y configuración del asistente.	—
`fp agent models`	Lista los modelos de asistente disponibles.	—
`fp agent chats`	Lista los chats guardados.	—
`fp agent ask [MESSAGE]`	Inicia o continúa un chat; lee stdin cuando se omite el mensaje.	`--chat`; `--model`; `--page-context`
`fp agent show CHAT_ID`	Muestra una conversación guardada.	—
`fp agent rename CHAT_ID`	Renombra una conversación.	`--title` obligatorio
`fp agent delete CHAT_ID`	Elimina una conversación.	`--yes`, `-y`

Políticas

Versiones de políticas administradas en la nube. Solo de sesión — cada comando aquí termina con código 2 bajo una clave de API, antes de cualquier solicitud, porque estas son rutas de escritura solo para root deliberadamente ausentes de /v1.

Comando	Propósito	Opciones
`fp policies list`	Lista las versiones de políticas.	`--json`
`fp policies show POLICY_ID`	Muestra una política con su fuente.	—
`fp policies publish NAME PATH`	Crea una versión a partir de un archivo `.mjs` local.	`--description`; `--no-verify`
`fp policies enable POLICY_ID`	La vuelve a agregar a cada despliegue del que fue eliminada, creando una nueva generación en cada uno.	`--yes`, `-y`
`fp policies disable POLICY_ID`	La elimina de cada despliegue que la contiene, creando una nueva generación en cada uno.	`--yes`, `-y`
`fp policies delete POLICY_ID`	Elimina una versión de política.	`--yes`, `-y`
`fp policies test PATH`	Ejecuta una política localmente contra un contexto sintético. Aplica el filtro `match` de cada política, por lo que una que no cubra el evento/herramienta dado se reporta como `skipped` en lugar de ejecutarse.	`--event`; `--tool`; `--command`; `--file`; `--expect`
`fp policies compose PROMPT`	Redacta una política con el asistente. Requiere `policies:write`.	—

Flota

Qué máquinas ejecutan qué políticas. Solo de sesión, por el mismo motivo anterior.

Comando	Propósito	Opciones
`fp fleet list`	Lista las máquinas inscritas y su generación de despliegue.	—
`fp fleet show MACHINE_ID`	El conjunto de políticas que ejecuta actualmente una máquina.	—
`fp fleet deploy MACHINE_ID`	Reemplaza todo el conjunto de políticas de la máquina. Muestra el plan y solicita confirmación solo en una terminal interactiva sin `--json`.	`--add`; `--remove`; `--set`; `--create`; `--yes`, `-y`
`fp fleet diff MACHINE_ID`	Compara una máquina con otro despliegue.	—
`fp fleet history MACHINE_ID`	Despliegues anteriores de una máquina.	—
`fp fleet rollback MACHINE_ID GENERATION`	Reinstala el conjunto de políticas de una generación anterior como una nueva generación.	`--yes`, `-y`
`fp fleet rename MACHINE_ID`	Asigna un nombre legible a una máquina.	`--name` obligatorio

Guardrails

Lo que la aplicación realmente hizo. Solo de sesión, por el mismo motivo anterior.

Comando	Propósito	Opciones
`fp guardrails summary`	Cobertura, totales bloqueados/evaluados, un sparkline de denegaciones y la tabla por política.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`
`fp guardrails timeline`	Decisiones agrupadas en la ventana temporal, sumadas en todas las fuentes de políticas.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`

Flags globales

Flag	Descripción
`--json`	Emite JSON legible por máquina.
`--base-url <url>`	Usa un dashboard autoalojado o de desarrollo.
`--org <slug>`	Selecciona una organización para esta invocación.
`--token <token>`	Reemplaza el token de sesión de usuario guardado.
`--api-key <key>`	Autentica la automatización con una clave de API; nunca se guarda.
`--timeout <seconds>`	Tiempo de espera HTTP; debe ser positivo. Por defecto: `30`.
`--quiet`, `-q`	Suprime la salida de estado en stderr.
`--no-color`	Deshabilita la salida con colores.
`--insecure` / `--secure`	Deshabilita o restaura la verificación del certificado TLS.
`--version`	Imprime la versión y termina.
`--help`, `-h`	Muestra la ayuda.

--api-key está destinado a la automatización. Los comandos de inicio de sesión, cambio de organización y asistente requieren una sesión de usuario.

Variables de entorno

Variable	Equivalente o propósito
`FP_DASHBOARD_URL`	`--base-url`
`FP_ORG`	`--org`
`FP_TOKEN`	`--token`
`FP_API_KEY`	`--api-key`
`FP_JSON`	`--json`
`FP_INSECURE`	`--insecure`
`FP_HOME`	Reubica el directorio de configuración de la CLI (por defecto `~/.failproofai/fpcli`).
`FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK`	Deshabilita las analíticas anónimas de la CLI.
`NO_COLOR`	Deshabilita la salida con colores.

Los flags explícitos reemplazan las variables de entorno, que a su vez reemplazan la configuración guardada. En el modo de clave de API, seleccione el tenant explícitamente con --org o FP_ORG.

Las versiones AGENTEYE_* de estas variables no son leídas por fp y nunca lo fueron — la CLI declara FP_* (fp_cli/app.py), y una variable desconocida no es un error. Establecer AGENTEYE_DASHBOARD_URL no redirige la CLI; se ignora y el comando se ejecuta silenciosamente contra el dashboard guardado.AGENTEYE_HOME y AGENTEYE_ENVIRONMENT todavía existen, pero pertenecen al recolector y al SDK de telemetría, no a esta CLI.

Los comandos que eliminan, revocan, suprimen, resuelven o reemplazan configuración solicitan confirmación por defecto. Use --yes solo después de verificar la organización activa y el objetivo.

Connect your agents

Reference

Iniciar sesión

Sintaxis

Comandos de la CLI

Autenticación

Eventos

Sesiones

Evaluaciones

Errores

Uso y valores de filtro

Organizaciones

Claves de API

Consultas

Usuarios

Configuración

Alertas

Auditorías

Opciones de creación de auditorías

Incidencias

Asistente en la nube

Políticas

Flota

Guardrails

Flags globales

Variables de entorno

​Iniciar sesión

​Sintaxis

​Comandos de la CLI

​Autenticación

​Eventos

​Sesiones

​Evaluaciones

​Errores

​Uso y valores de filtro

​Organizaciones

​Claves de API

​Consultas

​Usuarios

​Configuración

​Alertas

​Auditorías

​Opciones de creación de auditorías

​Incidencias

​Asistente en la nube

​Políticas

​Flota

​Guardrails

​Flags globales

​Variables de entorno

Iniciar sesión

Sintaxis

Comandos de la CLI

Autenticación

Eventos

Sesiones

Evaluaciones

Errores

Uso y valores de filtro

Organizaciones

Claves de API

Consultas

Usuarios

Configuración

Alertas

Auditorías

Opciones de creación de auditorías

Incidencias

Asistente en la nube

Políticas

Flota

Guardrails

Flags globales

Variables de entorno