Failproof Cloud CLI

Usa fp per ispezionare la telemetria Cloud, gestire l’enforcement gestito dal cloud (politiche, distribuzioni di flotta, decisioni di guardrail) e gestire audit, findings, issues, alert, chiavi, utenti, query e impostazioni. Usa failproofai per hook locali, politiche, acquisizione e registrazione di macchine. Installa la Cloud CLI rilasciata come strumento isolato:

uv tool install fp-cloud-cli
fp version

Accedi

fp login
fp whoami

Sintassi

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

Le opzioni globali devono venire prima del comando:

fp --json sessions --since 24h

Esegui fp COMMAND --help o fp COMMAND SUBCOMMAND --help per l’aiuto in terminale.

Comandi CLI

Autenticazione

Comando	Scopo	Opzioni
`fp login`	Accedi con un codice monouso inviato via email e seleziona un’organizzazione.	`--email`, `-e`; `--org`; `--force`
`fp logout`	Revoca e rimuovi la sessione utente salvata.	—
`fp whoami`	Mostra l’identità corrente, la modalità di autenticazione, l’organizzazione e i permessi.	—
`fp version`	Mostra la versione della CLI installata.	—
`fp help`	Mostra l’aiuto dei comandi di livello superiore.	—

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

Eventi

fp events [OPTIONS]

Elenca i singoli eventi dell’agente. Il feed leggero predefinito esclude i payload grezzi; usa --full solo per un’indagine limitata.

Opzione	Descrizione
`--limit`, `-n <n>`	Numero massimo totale di righe. Predefinito: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h`, o `7d`.
`--from <timestamp>` / `--to <timestamp>`	Intervallo ISO 8601 UTC; sostituisce `--since`.
`--env <value>`	Filtro ambiente; ripeti o separato da virgola.
`--event-type <value>`	Filtro tipo evento; ripeti o separato da virgola.
`--agent-id <value>`	Filtro agente; ripeti o separato da virgola.
`--session-id <value>`	Filtro sessione; ripeti o separato da virgola.
`--search <text>`	Ricerca testo payload; ripetibile, con qualsiasi termine corrispondente.
`--order asc\|desc`	Ordine temporale. Predefinito: più recente prima.
`--all`	Paginazione automatica fino a `--limit`.
`--cursor <token>`	Riprendi da un cursore opaco.
`--page-size <n>`	Righe per richiesta con `--all`; massimo `200`.
`--full`	Includi payload grezzi tramite l’endpoint dell’evento più pesante.
`--fields <csv>`	Restituisci solo i campi selezionati; richiedere `payload` abilita la modalità completa.

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

--all pagina fino a --limit, che è predefinito a 50 — quindi --all da solo si ferma a 50 righe. Quando si ferma prima, la risposta contiene un next_cursor per riprendere; "next_cursor": null significa che il feed era realmente esaurito.

Sessioni

fp sessions [OPTIONS]

Opzione	Descrizione
`--limit`, `-n <n>`	Numero massimo totale di righe. Predefinito: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h`, o `7d`.
`--from <timestamp>` / `--to <timestamp>`	Intervallo ISO 8601 UTC; sostituisce `--since`.
`--env <value>`	Filtro ambiente; ripeti o separato da virgola.
`--status <value>`	`done`, `error`, o `timeout`; ripeti o separato da virgola.
`--agent-id <value>`	Abbina sessioni che coinvolgono un agente selezionato.
`--session-id <value>`	Filtro sessione; ripeti o separato da virgola.
`--all`	Paginazione automatica fino a `--limit`.
`--cursor <token>`	Riprendi da un cursore opaco.
`--page-size <n>`	Righe per richiesta con `--all`; massimo `200`.
`--fields <csv>`	Restituisci solo i campi selezionati.
`--full-ids`	Non abbreviare gli ID sessione nell’output del terminale.
`--agents`	Espandi il roster agente per le sessioni multi-agente.

Valutazioni

fp evals [OPTIONS]

Opzione	Descrizione
`--aggregate`	Mostra i totali e le statistiche per punteggio invece delle valutazioni individuali.
`--limit`, `-n <n>`	Numero massimo di righe dell’elenco. Predefinito: `50`.
`--since`, `--from`, `--to`	Seleziona l’intervallo temporale.
`--env`, `--status`, `--agent-id`, `--session-id`	Limita a un valore esatto per filtro.
`--score KEY:MIN..MAX`	Intervallo punteggio; ripetibile e tutti gli intervalli devono corrispondere.
`--all`, `--cursor`, `--page-size`	Controlla la paginazione dell’elenco.
`--fields <csv>`	Restituisci solo i campi selezionati.
`--full-ids`	Mostra gli ID sessione completi.
`--scores-full`	Mostra ogni punteggio nell’output del terminale.

Errori

fp errors [OPTIONS]

Opzione	Descrizione
`--aggregate`	Riassumi gli errori corrispondenti invece di elencare le righe.
`--limit`, `-n <n>`	Numero massimo di righe dell’elenco. Predefinito: `50`.
`--since`, `--from`, `--to`	Seleziona l’intervallo temporale.
`--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id`	Limita la popolazione di errori.
`--search <text>`	Ricerca testo payload; ripetibile.
`--order asc\|desc`	Ordine temporale.
`--all`, `--cursor`, `--page-size`	Controlla la paginazione dell’elenco.
`--fields <csv>`	Restituisci solo i campi selezionati.
`--full-ids`	Mostra gli ID sessione completi.

Utilizzo e valori di filtro

Comando	Scopo
`fp usage`	Mostra l’utilizzo per la finestra di misurazione corrente.
`fp list envs`	Elenca gli ambienti osservati.
`fp list agents`	Elenca gli ID agente osservati.
`fp list event_types`	Elenca i tipi di evento.
`fp list score_filters`	Elenca le chiavi di punteggio di valutazione.
`fp list models`	Elenca i nomi dei modelli.
`fp list hooks`	Elenca i nomi degli hook.
`fp list tools`	Elenca i nomi dei tool.
`fp list error_types`	Elenca i tipi di errore.

Organizzazioni

Comando	Scopo
`fp orgs list`	Elenca le organizzazioni accessibili.
`fp orgs switch [SLUG]`	Salva un’organizzazione attiva; chiede quando omesso.
`fp orgs current`	Mostra l’organizzazione attiva.
`fp orgs perms`	Mostra i tuoi permessi nell’organizzazione attiva.

Chiavi API

Comando	Scopo	Opzioni
`fp keys list`	Elenca le chiavi dell’organizzazione.	`--show-id`; `--fields <csv>`
`fp keys show NAME`	Mostra una chiave e i suoi permessi.	—
`fp keys create NAME`	Crea una chiave e rivela il suo segreto una sola volta.	`--permission-set`; `--add`; `--remove`
`fp keys update NAME`	Sostituisci il set di permessi o aggiusta i permessi.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp keys regenerate NAME`	Ruota il segreto e rivela la sostituzione una sola volta.	`--yes`, `-y`
`fp keys disable NAME`	Revoca permanentemente una chiave.	`--yes`, `-y`

I token di permesso usano resource:action, come events:add. Ripeti --add, separato da virgola i token, o usa azioni puntate come events:read.add.

Query

Comando	Scopo	Opzioni
`fp query list`	Elenca le query salvate.	`--show-id`; `--fields <csv>`
`fp query show NAME`	Mostra una query.	—
`fp query create NAME`	Salva una query.	`--sql <text\|@file>`; `--description`
`fp query update NAME`	Aggiorna o rinomina una query.	`--name`; `--sql`; `--description`; `--yes`, `-y`
`fp query delete NAME`	Elimina una query salvata.	`--yes`, `-y`
`fp query run [NAME]`	Esegui una query salvata o SQL ad-hoc.	`--sql`; `--limit`; `--all`; `--arg`, `--param`
`fp query schema [TABLE]`	Elenca le tabelle interrogabili o ispeziona una tabella.	—

Utenti

Comando	Scopo	Opzioni
`fp users list`	Elenca i membri dell’organizzazione.	`--active-only`; `--show-id`
`fp users show EMAIL`	Mostra un membro e i suoi permessi.	—
`fp users create EMAIL`	Aggiungi un membro.	`--permission-set`; `--add`; `--remove`
`fp users update EMAIL`	Cambia i permessi di un membro.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp users disable EMAIL`	Disabilita l’accesso.	`--yes`, `-y`
`fp users enable EMAIL`	Riabilita l’accesso.	`--yes`, `-y`

Impostazioni

Comando	Scopo	Opzioni
`fp settings list`	Elenca le impostazioni dell’organizzazione e i valori correnti.	—
`fp settings schema`	Mostra i valori accettati e le descrizioni.	—
`fp settings set KEY`	Cambia un’impostazione esistente.	esattamente uno di `--value`, `--json-value`, `--file`; `--yes`, `-y` opzionale

Alert

Comando	Scopo	Opzioni
`fp alerts list`	Elenca le regole di alert.	`--show-id`
`fp alerts show NAME`	Mostra un alert.	—
`fp alerts create NAME`	Crea un alert.	`--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window`
`fp alerts update NAME`	Aggiorna o rinomina un alert.	opzioni create più `--name`; `--yes`, `-y`
`fp alerts delete NAME`	Elimina un alert.	`--yes`, `-y`
`fp alerts test NAME`	Invia una notifica di test.	`--channels`; `--yes`, `-y`

Le severità degli alert sono info, warning e critical. I tipi di trigger sono metric_threshold, custom_sql, evaluation_score, eval_compound e per_event. Gli intervalli di valutazione devono essere tra 30 e 86.400 secondi.

Audit

Comando	Scopo	Opzioni
`fp audits list`	Elenca gli audit.	`--enabled-only`; `--show-id`
`fp audits show NAME`	Mostra una definizione di audit e lo stato.	—
`fp audits create NAME`	Crea un audit e metti subito in coda la sua prima esecuzione.	Vedi opzioni di creazione.
`fp audits edit NAME`	Sostituisci le impostazioni di audit mantenendo i valori non specificati.	opzioni di definizione create; `--name`; `--yes`, `-y`
`fp audits delete NAME`	Elimina un audit, i suoi findings e la cronologia di esecuzione.	`--yes`, `-y`
`fp audits run NAME`	Metti in coda un’esecuzione manuale.	—
`fp audits runs NAME`	Elenca la cronologia di esecuzione.	`--limit`, `-n`; `--show-id`
`fp audits context-show NAME`	Mostra il testo breve e lo stato del recupero dell’URL di riferimento.	—
`fp audits context-set NAME`	Cambia il testo breve o gli URL di riferimento.	`--text`; `--text-file`; `--url`; `--clear-urls`
`fp audits context-refresh NAME`	Recupera di nuovo gli URL di riferimento.	—
`fp audits findings`	Elenca i findings.	`--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id`
`fp audits finding FINDING_ID`	Mostra un finding e le sue evidenze.	—
`fp audits ack FINDING_ID`	Riconosci un finding.	`--reason`
`fp audits mute FINDING_ID`	Sopprimi un pattern ricorrente.	`--reason`; `--yes`, `-y`
`fp audits dismiss FINDING_ID`	Contrassegna un pattern come non attuabile e supprimi.	`--reason`; `--yes`, `-y`
`fp audits resolve FINDING_ID`	Contrassegna un finding come risolto senza soppressione futura.	`--yes`, `-y`
`fp audits reopen FINDING_ID`	Restituisci un finding alla coda attiva e cancella la soppressione.	—
`fp audits assign FINDING_ID`	Imposta il proprietario del finding.	required `--to <email>`

Opzioni di creazione di audit

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

Opzione	Descrizione
`--file <path>`	Basa la definizione su JSON, o usa `-` per stdin. I flag espliciti sostituiscono i valori del file.
`--description <text>`	Dichiara la domanda o lo scopo del fallimento.
`--enabled` / `--disabled`	Avvia la programmazione attiva o inattiva. Predefinito: abilitato.
`--schedule-interval-secs <n>`	`3600`–`604800`. Predefinito: `86400`.
`--schedule-anchor <timestamp>`	Fase UTC fissa in forma ISO 8601. Predefinito: prossime 09:00 UTC.
`--window-mode since_last\|fixed`	Continua dopo l’ultima finestra completamente analizzata o ispeziona ripetutamente una finestra mobile. Predefinito: `since_last`.
`--lookback-window-secs <n>`	`3600`–`7776000`. Predefinito: `604800`.
`--scope '<json>'`	Filtra per `environments`, `agent_ids` o altri campi di scope supportati.
`--ignore-error-type <type>`	Escludi tipi di errore; ripeti o separato da virgola.
`--llm` / `--no-llm`	Abilita o disabilita l’analisi agentiva. Predefinito: abilitato.
`--top-k <n>`	Mantieni `1`–`500` findings. Predefinito: `50`.
`--sensitivity low\|medium\|high`	Imposta la sensibilità del report. Predefinito: `medium`.
`--channels '<json>'`	Array del canale di notifica.
`--text <brief>`	Testo breve inline, massimo 8.192 caratteri.
`--text-file <path>`	Leggi il testo breve da un file; mutuamente esclusivo con `--text`.
`--url <https-url>`	Aggiungi un riferimento HTTPS pubblico; ripeti fino a cinque volte.

Includi il contesto durante la creazione quando la prima esecuzione ne ha bisogno. La creazione impegna la definizione e il contesto insieme prima che l’esecuzione in coda inizi.

fp audits run è asincrono. Polling di fp audits runs NAME finché l’ultima esecuzione non riesce o fallisce prima di leggere i suoi findings.

Issues

Comando	Scopo	Opzioni
`fp issues list`	Elenca gli issue.	`--state`; `--alert-id`; `--limit`, `-n`; `--show-id`
`fp issues count`	Conta gli issue aperti o selezionati.	`--state`
`fp issues show INCIDENT_ID`	Mostra i dettagli dell’issue, i commenti, gli abbonati e l’attività.	—
`fp issues open`	Apri un issue manuale o collegato a un alert.	required `--summary`; optional `--title`, `--alert-id`, `--severity`
`fp issues ack INCIDENT_ID`	Riconosci un issue.	—
`fp issues assign INCIDENT_ID`	Sostituisci gli assegnati; ometti l’opzione per cancellarli.	repeatable `--assignee`
`fp issues resolve INCIDENT_ID`	Risolvi un issue.	`--yes`, `-y`
`fp issues comment-list INCIDENT_ID`	Elenca i commenti.	—
`fp issues comment-add INCIDENT_ID`	Aggiungi un commento.	esattamente uno di `--body`, `--file`
`fp issues comment-delete INCIDENT_ID COMMENT_ID`	Elimina un commento.	`--yes`, `-y`
`fp issues subscribers INCIDENT_ID`	Elenca gli abbonati.	—
`fp issues subscribe INCIDENT_ID`	Iscriviti tu stesso o un altro operatore.	`--email`
`fp issues unsubscribe INCIDENT_ID`	Rimuovi un abbonamento.	`--email`

Gli stati di issue validi sono firing, acknowledged e resolved. Le severità degli issue autonomi sono info, warning e critical.

Assistente Cloud

Comando	Scopo	Opzioni
`fp agent health`	Controlla la disponibilità e la configurazione dell’assistente.	—
`fp agent models`	Elenca i modelli di assistente disponibili.	—
`fp agent chats`	Elenca le chat salvate.	—
`fp agent ask [MESSAGE]`	Avvia o continua una chat; leggi stdin quando il messaggio è omesso.	`--chat`; `--model`; `--page-context`
`fp agent show CHAT_ID`	Mostra una conversazione salvata.	—
`fp agent rename CHAT_ID`	Rinomina una conversazione.	required `--title`
`fp agent delete CHAT_ID`	Elimina una conversazione.	`--yes`, `-y`

Politiche

Versioni di politica gestite dal cloud. Solo sessione — ogni comando qui esce con 2 sotto una chiave API, prima di qualsiasi richiesta, perché questi sono percorsi di scrittura solo root deliberatamente assenti da /v1.

Comando	Scopo	Opzioni
`fp policies list`	Elenca le versioni di politica.	`--json`
`fp policies show POLICY_ID`	Mostra una politica, con il suo sorgente.	—
`fp policies publish NAME PATH`	Crea una versione da un `.mjs` locale.	`--description`; `--no-verify`
`fp policies enable POLICY_ID`	Aggiungila di nuovo a ogni distribuzione da cui è stata rimossa, creando una nuova generazione su ciascuna.	`--yes`, `-y`
`fp policies disable POLICY_ID`	Rimuovila da ogni distribuzione che la contiene, creando una nuova generazione su ciascuna.	`--yes`, `-y`
`fp policies delete POLICY_ID`	Elimina una versione di politica.	`--yes`, `-y`
`fp policies test PATH`	Esegui una politica localmente contro un contesto sintetico. Applica il filtro `match` di ogni politica, quindi una che non copre l’evento/tool dato è segnalata come `skipped` piuttosto che eseguita.	`--event`; `--tool`; `--command`; `--file`; `--expect`
`fp policies compose PROMPT`	Bozza una politica con l’assistente. Richiede `policies:write`.	—

Flotta

Quali macchine eseguono quali politiche. Solo sessione, per lo stesso motivo di cui sopra.

Comando	Scopo	Opzioni
`fp fleet list`	Elenca le macchine registrate e la loro generazione di distribuzione.	—
`fp fleet show MACHINE_ID`	Il set di politiche che una macchina esegue attualmente.	—
`fp fleet deploy MACHINE_ID`	Sostituisce l’intero set di politiche della macchina. Stampa il piano e chiede solo su un terminale interattivo senza `--json`.	`--add`; `--remove`; `--set`; `--create`; `--yes`, `-y`
`fp fleet diff MACHINE_ID`	Confronta una macchina con un’altra distribuzione.	—
`fp fleet history MACHINE_ID`	Distribuzioni passate per una macchina.	—
`fp fleet rollback MACHINE_ID GENERATION`	Ripristina il set di politiche di una generazione passata, come una nuova generazione.	`--yes`, `-y`
`fp fleet rename MACHINE_ID`	Assegna un nome leggibile a una macchina.	required `--name`

Guardrail

Cosa ha fatto realmente l’enforcement. Solo sessione, per lo stesso motivo di cui sopra.

Comando	Scopo	Opzioni
`fp guardrails summary`	Copertura, totali bloccati/valutati, una scintilla di negazione e la tabella per politica.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`
`fp guardrails timeline`	Decisioni raggruppate sulla finestra, sommate su ogni fonte di politica.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`

Flag globali

Flag	Descrizione
`--json`	Emetti JSON leggibile da macchina.
`--base-url <url>`	Usa un dashboard self-hosted o di sviluppo.
`--org <slug>`	Seleziona un’organizzazione per questa invocazione.
`--token <token>`	Sostituisci il token di sessione utente salvato.
`--api-key <key>`	Autentica l’automazione con una chiave API; mai salvata.
`--timeout <seconds>`	Timeout HTTP; deve essere positivo. Predefinito: `30`.
`--quiet`, `-q`	Sopprimere l’output di stato su stderr.
`--no-color`	Disabilita l’output colorato.
`--insecure` / `--secure`	Disabilita o ripristina la verifica del certificato TLS.
`--version`	Stampa la versione e esci.
`--help`, `-h`	Mostra l’aiuto.

--api-key è inteso per l’automazione. L’accesso, il cambio di organizzazione e i comandi dell’assistente richiedono una sessione utente.

Variabili di ambiente

Variabile	Equivalente o scopo
`FP_DASHBOARD_URL`	`--base-url`
`FP_ORG`	`--org`
`FP_TOKEN`	`--token`
`FP_API_KEY`	`--api-key`
`FP_JSON`	`--json`
`FP_INSECURE`	`--insecure`
`FP_HOME`	Riposiziona la directory di configurazione della CLI (predefinito `~/.failproofai/fpcli`).
`FP_ANALYTICS_DISABLED` o `DO_NOT_TRACK`	Disabilita l’analisi anonima della CLI.
`NO_COLOR`	Disabilita l’output colorato.

I flag espliciti sostituiscono le variabili di ambiente, che sostituiscono la configurazione salvata. In modalità chiave API, seleziona il tenant esplicitamente con --org o FP_ORG.

Gli spelling AGENTEYE_* di questi non sono letti da fp e non lo sono mai stati — la CLI dichiara FP_* (fp_cli/app.py), e una variabile sconosciuta non è un errore. Impostare AGENTEYE_DASHBOARD_URL non reindirizza la CLI; viene ignorato e il comando silenziosamente viene eseguito contro il dashboard salvato invece.AGENTEYE_HOME e AGENTEYE_ENVIRONMENT esistono ancora, ma appartengono al collector e all’SDK di telemetria, non a questa CLI.

I comandi che eliminano, revocano, sopprimono, risolvono o sostituiscono la configurazione chiedono per impostazione predefinita. Usa --yes solo dopo aver verificato l’organizzazione attiva e il target.

Connect your agents

Reference

Accedi

Sintassi

Comandi CLI

Autenticazione

Eventi

Sessioni

Valutazioni

Errori

Utilizzo e valori di filtro

Organizzazioni

Chiavi API

Query

Utenti

Impostazioni

Alert

Audit

Opzioni di creazione di audit

Issues

Assistente Cloud

Politiche

Flotta

Guardrail

Flag globali

Variabili di ambiente

​Accedi

​Sintassi

​Comandi CLI

​Autenticazione

​Eventi

​Sessioni

​Valutazioni

​Errori

​Utilizzo e valori di filtro

​Organizzazioni

​Chiavi API

​Query

​Utenti

​Impostazioni

​Alert

​Audit

​Opzioni di creazione di audit

​Issues

​Assistente Cloud

​Politiche

​Flotta

​Guardrail

​Flag globali

​Variabili di ambiente

Accedi

Sintassi

Comandi CLI

Autenticazione

Eventi

Sessioni

Valutazioni

Errori

Utilizzo e valori di filtro

Organizzazioni

Chiavi API

Query

Utenti

Impostazioni

Alert

Audit

Opzioni di creazione di audit

Issues

Assistente Cloud

Politiche

Flotta

Guardrail

Flag globali

Variabili di ambiente