Failproof Cloud CLI

Usa fp per ispezionare la telemetria del Cloud, gestire l’enforcement gestito dal cloud (policy, distribuzioni di flotte, decisioni di guardrail) e gestire audit, findings, issues, alert, chiavi, utenti, query e impostazioni. Usa failproofai per hook locali, policy, capture e enrollment 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 nel terminale.

Comandi CLI

Autenticazione

Comando	Scopo	Opzioni
`fp login`	Accedi con un codice monouso inviato per email e seleziona un’organizzazione.	`--email`, `-e`; `--org`; `--force`
`fp logout`	Revoca e rimuovi la sessione utente salvata.	—
`fp whoami`	Mostra l’identità attuale, 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’agent. Il feed leggero predefinito esclude i payload grezzi; usa --full solo per un’indagine limitata.

Opzione	Descrizione
`--limit`, `-n <n>`	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 per ambiente; ripeti o separa con virgola i valori.
`--event-type <value>`	Filtro per tipo di evento; ripeti o separa con virgola i valori.
`--agent-id <value>`	Filtro per agent; ripeti o separa con virgola i valori.
`--session-id <value>`	Filtro per sessione; ripeti o separa con virgola i valori.
`--search <text>`	Ricerca testo nel payload; ripetibile, corrisponde a qualsiasi termine.
`--order asc\|desc`	Ordine temporale. Predefinito: più recenti per primi.
`--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 attraverso l’endpoint 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 ha predefinito 50 — quindi --all da solo si ferma a 50 righe. Quando si ferma anticipatamente la risposta contiene un next_cursor per riprendere da lì; "next_cursor": null significa che il feed era veramente esaurito.

Sessioni

fp sessions [OPTIONS]

Opzione	Descrizione
`--limit`, `-n <n>`	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 per ambiente; ripeti o separa con virgola i valori.
`--status <value>`	`done`, `error` o `timeout`; ripeti o separa con virgola i valori.
`--agent-id <value>`	Corrisponde a sessioni che coinvolgono qualsiasi agent selezionato.
`--session-id <value>`	Filtro per sessione; ripeti o separa con virgola i valori.
`--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 di sessione nell’output del terminale.
`--agents`	Espandi il roster degli agent per le sessioni multi-agent.

Valutazioni

fp evals [OPTIONS]

Opzione	Descrizione
`--aggregate`	Mostra totali e statistiche per-score invece delle singole valutazioni.
`--limit`, `-n <n>`	Massimo righe elenco. Predefinito: `50`.
`--since`, `--from`, `--to`	Seleziona l’intervallo temporale.
`--env`, `--status`, `--agent-id`, `--session-id`	Restringi a un valore esatto per filtro.
`--score KEY:MIN..MAX`	Intervallo di score; 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 di sessione completi.
`--scores-full`	Mostra ogni score nell’output del terminale.

Errori

fp errors [OPTIONS]

Opzione	Descrizione
`--aggregate`	Riassumi gli errori corrispondenti invece di elencare le righe.
`--limit`, `-n <n>`	Massimo righe elenco. Predefinito: `50`.
`--since`, `--from`, `--to`	Seleziona l’intervallo temporale.
`--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id`	Restringi la popolazione di errori.
`--search <text>`	Ricerca testo nel 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 di sessione completi.

Utilizzo e valori 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 degli agent osservati.
`fp list event_types`	Elenca i tipi di evento.
`fp list score_filters`	Elenca le chiavi di score di valutazione.
`fp list models`	Elenca i nomi dei modelli.
`fp list hooks`	Elenca i nomi degli hook.
`fp list tools`	Elenca i nomi degli strumenti.
`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 se omessa.
`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 grant.	—
`fp keys create NAME`	Crea una chiave e rivela il suo segreto una volta.	`--permission-set`; `--add`; `--remove`
`fp keys update NAME`	Sostituisci il set di permessi o regola i grant.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp keys regenerate NAME`	Ruota il segreto e rivela il rimpiazzo una volta.	`--yes`, `-y`
`fp keys disable NAME`	Revoca permanentemente una chiave.	`--yes`, `-y`

I token di permesso usano resource:action, ad esempio events:add. Ripeti --add, separa con 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 grant.	—
`fp users create EMAIL`	Aggiungi un membro.	`--permission-set`; `--add`; `--remove`
`fp users update EMAIL`	Cambia i grant 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 attuali.	—
`fp settings schema`	Mostra i valori accettati e le descrizioni.	—
`fp settings set KEY`	Cambia un’impostazione esistente.	esattamente uno tra `--value`, `--json-value`, `--file`; facoltativo `--yes`, `-y`

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 di creazione 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à di alert sono info, warning e critical. I trigger kind 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 il suo stato.	—
`fp audits create NAME`	Crea un audit e accoda immediatamente 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 creazione; `--name`; `--yes`, `-y`
`fp audits delete NAME`	Elimina un audit, i suoi findings e la cronologia di esecuzione.	`--yes`, `-y`
`fp audits run NAME`	Accoda un’esecuzione manuale.	—
`fp audits runs NAME`	Elenca la cronologia di esecuzione.	`--limit`, `-n`; `--show-id`
`fp audits context-show NAME`	Mostra il briefing e lo stato di fetch dell’URL di riferimento.	—
`fp audits context-set NAME`	Cambia il briefing o gli URL di riferimento.	`--text`; `--text-file`; `--url`; `--clear-urls`
`fp audits context-refresh NAME`	Re-fetch degli 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 la sua evidenza.	—
`fp audits ack FINDING_ID`	Riconosci un finding.	`--reason`
`fp audits mute FINDING_ID`	Sopprimere un pattern ricorrente.	`--reason`; `--yes`, `-y`
`fp audits dismiss FINDING_ID`	Contrassegna un pattern come non azionabile e sopprimilo.	`--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 live e cancella la soppressione.	—
`fp audits assign FINDING_ID`	Imposta il proprietario del finding.	richiesto `--to <email>`

Opzioni di creazione 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. Flag espliciti sostituiscono i valori del file.
`--description <text>`	Dichiara la domanda di errore o lo scopo.
`--enabled` / `--disabled`	Avvia la pianificazione attiva o no. Predefinito: abilitato.
`--schedule-interval-secs <n>`	`3600`–`604800`. Predefinito: `86400`.
`--schedule-anchor <timestamp>`	Fase UTC fissa in formato ISO 8601. Predefinito: prossimo 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 separa con virgola.
`--llm` / `--no-llm`	Abilita o disabilita l’analisi agentiva. Predefinito: abilitato.
`--top-k <n>`	Conserva `1`–`500` findings. Predefinito: `50`.
`--sensitivity low\|medium\|high`	Imposta la sensibilità di reporting. Predefinito: `medium`.
`--channels '<json>'`	Array di canali di notifica.
`--text <brief>`	Briefing inline, massimo 8.192 caratteri.
`--text-file <path>`	Leggi il briefing da un file; mutualmente 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 è asincrona. Esegui il polling di fp audits runs NAME fino a quando l’esecuzione più recente riesce o non fallisce prima di leggere i suoi findings.

Issue

Comando	Scopo	Opzioni
`fp issues list`	Elenca le issue.	`--state`; `--alert-id`; `--limit`, `-n`; `--show-id`
`fp issues count`	Conta gli stati di 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 collegata a un alert.	richiesto `--summary`; facoltativo `--title`, `--alert-id`, `--severity`
`fp issues ack INCIDENT_ID`	Riconosci un’issue.	—
`fp issues assign INCIDENT_ID`	Sostituisci gli assegnatari; ometti l’opzione per cancellarli.	ripetibile `--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 tra `--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 validi di issue sono firing, acknowledged e resolved. Le severità di issue autonome 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; legge 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.	richiesto `--title`
`fp agent delete CHAT_ID`	Elimina una conversazione.	`--yes`, `-y`

Policy

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

Comando	Scopo	Opzioni
`fp policies list`	Elenca le versioni di policy.	`--json`
`fp policies show POLICY_ID`	Mostra una policy 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 a ogni deployment da cui è stata rimossa, creando una nuova generazione su ognuna.	`--yes`, `-y`
`fp policies disable POLICY_ID`	Rimuovila da ogni deployment che la contiene, creando una nuova generazione su ognuna.	`--yes`, `-y`
`fp policies delete POLICY_ID`	Elimina una versione di policy.	`--yes`, `-y`
`fp policies test PATH`	Esegui una policy localmente su un contesto sintetico. Applica il filtro `match` di ogni policy, quindi una che non copre l’evento/strumento specificato è riportata come `skipped` piuttosto che eseguita.	`--event`; `--tool`; `--command`; `--file-path`; `--expect`
`fp policies compose PROMPT`	Elabora una policy con l’assistente. Necessita `policies:write`.	—

Fleet

Quali macchine eseguono quali policy. Solo sessione, stesso motivo di cui sopra.

Comando	Scopo	Opzioni
`fp fleet list`	Elenca le macchine iscritte e la loro generazione di deployment.	—
`fp fleet show MACHINE_ID`	Il set di policy che una macchina attualmente esegue.	—
`fp fleet deploy MACHINE_ID`	Sostituisce l’intero set di policy 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 altro deployment.	—
`fp fleet history MACHINE_ID`	Deployment precedenti per una macchina.	—
`fp fleet rollback MACHINE_ID`	Ripristina un deployment precedente.	`--yes`, `-y`
`fp fleet rename MACHINE_ID`	Assegna a una macchina un nome leggibile.	richiesto `--name`

Guardrail

Cosa l’enforcement ha effettivamente fatto. Solo sessione, stesso motivo di cui sopra.

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

Flag globali

Flag	Descrizione
`--json`	Emetti JSON leggibile da macchina.
`--base-url <url>`	Usa un dashboard auto-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 è destinato all’automazione. L’accesso, il cambio di organizzazione e i comandi dell’assistente richiedono una sessione utente.

Variabili d’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’analitiche anonime della CLI.
`NO_COLOR`	Disabilita l’output colorato.

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

I nomi 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 reindirizz la CLI; viene ignorato e il comando è eseguito silenziosamente contro il dashboard salvato.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 filtro

Organizzazioni

Chiavi API

Query

Utenti

Impostazioni

Alert

Audit

Opzioni di creazione audit

Issue

Assistente Cloud

Policy

Fleet

Guardrail

Flag globali

Variabili d’ambiente

​Accedi

​Sintassi

​Comandi CLI

​Autenticazione

​Eventi

​Sessioni

​Valutazioni

​Errori

​Utilizzo e valori filtro

​Organizzazioni

​Chiavi API

​Query

​Utenti

​Impostazioni

​Alert

​Audit

​Opzioni di creazione audit

​Issue

​Assistente Cloud

​Policy

​Fleet

​Guardrail

​Flag globali

​Variabili d’ambiente

Accedi

Sintassi

Comandi CLI

Autenticazione

Eventi

Sessioni

Valutazioni

Errori

Utilizzo e valori filtro

Organizzazioni

Chiavi API

Query

Utenti

Impostazioni

Alert

Audit

Opzioni di creazione audit

Issue

Assistente Cloud

Policy

Fleet

Guardrail

Flag globali

Variabili d’ambiente