Failproof Cloud CLI

Use fp para inspecionar telemetria do Cloud, gerenciar aplicação gerenciada pela nuvem (políticas, implantações em frota, decisões de guardrail) e gerenciar auditorias, descobertas, problemas, alertas, chaves, usuários, consultas e configurações. Use failproofai para hooks locais, políticas, captura e registro de máquinas. Instale o Cloud CLI lançado como uma ferramenta isolada:

uv tool install fp-cloud-cli
fp version

Entrar

fp login
fp whoami

Sintaxe

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

As opções globais devem vir antes do comando:

fp --json sessions --since 24h

Execute fp COMMAND --help ou fp COMMAND SUBCOMMAND --help para obter ajuda no terminal.

Comandos da CLI

Autenticação

Comando	Finalidade	Opções
`fp login`	Entrar com um código único enviado por e-mail e selecionar uma organização.	`--email`, `-e`; `--org`; `--force`
`fp logout`	Revogar e remover a sessão de usuário salva.	—
`fp whoami`	Exibir a identidade atual, modo de autenticação, organização e permissões.	—
`fp version`	Exibir a versão da CLI instalada.	—
`fp help`	Exibir a ajuda dos comandos de nível superior.	—

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

Eventos

fp events [OPTIONS]

Lista eventos individuais de agentes. O feed leve padrão exclui payloads brutos; use --full apenas para investigações com escopo definido.

Opção	Descrição
`--limit`, `-n <n>`	Total máximo de linhas. Padrão: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h` ou `7d`.
`--from <timestamp>` / `--to <timestamp>`	Intervalo UTC em ISO 8601; substitui `--since`.
`--env <value>`	Filtro de ambiente; repita ou separe valores por vírgula.
`--event-type <value>`	Filtro de tipo de evento; repita ou separe valores por vírgula.
`--agent-id <value>`	Filtro de agente; repita ou separe valores por vírgula.
`--session-id <value>`	Filtro de sessão; repita ou separe valores por vírgula.
`--search <text>`	Busca de texto no payload; repetível, com correspondência de qualquer termo.
`--order asc\|desc`	Ordem temporal. Padrão: mais recente primeiro.
`--all`	Pagina automaticamente até o limite de `--limit`.
`--cursor <token>`	Retomar a partir de um cursor opaco.
`--page-size <n>`	Linhas por requisição com `--all`; máximo de `200`.
`--full`	Incluir payloads brutos via endpoint de eventos mais pesado.
`--fields <csv>`	Retornar apenas os campos selecionados; solicitar `payload` habilita o 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 até --limit, cujo padrão é 50 — portanto, --all sozinho para em 50 linhas. Quando para antes do esperado, a resposta traz um next_cursor para continuar; "next_cursor": null significa que o feed foi realmente esgotado.

Sessões

fp sessions [OPTIONS]

Opção	Descrição
`--limit`, `-n <n>`	Total máximo de linhas. Padrão: `50`.
`--since <window>`	`all`, `15m`, `1h`, `6h`, `24h` ou `7d`.
`--from <timestamp>` / `--to <timestamp>`	Intervalo UTC em ISO 8601; substitui `--since`.
`--env <value>`	Filtro de ambiente; repita ou separe valores por vírgula.
`--status <value>`	`done`, `error` ou `timeout`; repita ou separe valores por vírgula.
`--agent-id <value>`	Corresponder sessões que envolvem qualquer agente selecionado.
`--session-id <value>`	Filtro de sessão; repita ou separe valores por vírgula.
`--all`	Pagina automaticamente até o limite de `--limit`.
`--cursor <token>`	Retomar a partir de um cursor opaco.
`--page-size <n>`	Linhas por requisição com `--all`; máximo de `200`.
`--fields <csv>`	Retornar apenas os campos selecionados.
`--full-ids`	Não abreviar IDs de sessão na saída do terminal.
`--agents`	Expandir a lista de agentes para sessões com múltiplos agentes.

Avaliações

fp evals [OPTIONS]

Opção	Descrição
`--aggregate`	Exibir totais e estatísticas por pontuação em vez de avaliações individuais.
`--limit`, `-n <n>`	Máximo de linhas na listagem. Padrão: `50`.
`--since`, `--from`, `--to`	Selecionar o intervalo de tempo.
`--env`, `--status`, `--agent-id`, `--session-id`	Restringir a um único valor por filtro.
`--score KEY:MIN..MAX`	Intervalo de pontuação; repetível e todos os intervalos devem corresponder.
`--all`, `--cursor`, `--page-size`	Controlar a paginação da listagem.
`--fields <csv>`	Retornar apenas os campos selecionados.
`--full-ids`	Exibir IDs de sessão completos.
`--scores-full`	Exibir todas as pontuações na saída do terminal.

Erros

fp errors [OPTIONS]

Opção	Descrição
`--aggregate`	Resumir erros correspondentes em vez de listar linhas.
`--limit`, `-n <n>`	Máximo de linhas na listagem. Padrão: `50`.
`--since`, `--from`, `--to`	Selecionar o intervalo de tempo.
`--env`, `--error-type`, `--event-type`, `--agent-id`, `--session-id`	Restringir o conjunto de erros.
`--search <text>`	Buscar texto no payload; repetível.
`--order asc\|desc`	Ordem temporal.
`--all`, `--cursor`, `--page-size`	Controlar a paginação da listagem.
`--fields <csv>`	Retornar apenas os campos selecionados.
`--full-ids`	Exibir IDs de sessão completos.

Uso e valores de filtro

Comando	Finalidade
`fp usage`	Exibir o uso da janela de medição atual.
`fp list envs`	Listar ambientes observados.
`fp list agents`	Listar IDs de agentes observados.
`fp list event_types`	Listar tipos de eventos.
`fp list score_filters`	Listar chaves de pontuação de avaliação.
`fp list models`	Listar nomes de modelos.
`fp list hooks`	Listar nomes de hooks.
`fp list tools`	Listar nomes de ferramentas.
`fp list error_types`	Listar tipos de erros.

Organizações

Comando	Finalidade
`fp orgs list`	Listar organizações acessíveis.
`fp orgs switch [SLUG]`	Salvar uma organização ativa; solicita quando omitido.
`fp orgs current`	Exibir a organização ativa.
`fp orgs perms`	Exibir suas permissões na organização ativa.

Chaves de API

Comando	Finalidade	Opções
`fp keys list`	Listar chaves da organização.	`--show-id`; `--fields <csv>`
`fp keys show NAME`	Exibir uma chave e suas concessões.	—
`fp keys create NAME`	Criar uma chave e revelar seu segredo uma única vez.	`--permission-set`; `--add`; `--remove`
`fp keys update NAME`	Substituir o conjunto de permissões ou ajustar concessões.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp keys regenerate NAME`	Rotacionar o segredo e revelar o substituto uma única vez.	`--yes`, `-y`
`fp keys disable NAME`	Revogar permanentemente uma chave.	`--yes`, `-y`

Os tokens de permissão usam o formato resource:action, como events:add. Repita --add, separe tokens por vírgula ou use ações com ponto, como events:read.add.

Consultas

Comando	Finalidade	Opções
`fp query list`	Listar consultas salvas.	`--show-id`; `--fields <csv>`
`fp query show NAME`	Exibir uma consulta.	—
`fp query create NAME`	Salvar uma consulta.	`--sql <text\|@file>`; `--description`
`fp query update NAME`	Atualizar ou renomear uma consulta.	`--name`; `--sql`; `--description`; `--yes`, `-y`
`fp query delete NAME`	Excluir uma consulta salva.	`--yes`, `-y`
`fp query run [NAME]`	Executar uma consulta salva ou SQL ad-hoc.	`--sql`; `--limit`; `--all`; `--arg`, `--param`
`fp query schema [TABLE]`	Listar tabelas consultáveis ou inspecionar uma tabela.	—

Usuários

Comando	Finalidade	Opções
`fp users list`	Listar membros da organização.	`--active-only`; `--show-id`
`fp users show EMAIL`	Exibir um membro e suas concessões.	—
`fp users create EMAIL`	Adicionar um membro.	`--permission-set`; `--add`; `--remove`
`fp users update EMAIL`	Alterar as concessões de um membro.	`--permission-set`; `--add`; `--remove`; `--yes`, `-y`
`fp users disable EMAIL`	Desabilitar o login.	`--yes`, `-y`
`fp users enable EMAIL`	Reabilitar o login.	`--yes`, `-y`

Configurações

Comando	Finalidade	Opções
`fp settings list`	Listar configurações da organização e seus valores atuais.	—
`fp settings schema`	Exibir valores aceitos e descrições.	—
`fp settings set KEY`	Alterar uma configuração existente.	exatamente um de `--value`, `--json-value`, `--file`; opcional `--yes`, `-y`

Alertas

Comando	Finalidade	Opções
`fp alerts list`	Listar regras de alerta.	`--show-id`
`fp alerts show NAME`	Exibir um alerta.	—
`fp alerts create NAME`	Criar um alerta.	`--file`; `--description`; `--severity`; `--trigger-kind`; `--trigger-spec`; `--channels`; `--eval-interval-secs`; `--min-breaches`; `--eval-window`
`fp alerts update NAME`	Atualizar ou renomear um alerta.	opções de criação mais `--name`; `--yes`, `-y`
`fp alerts delete NAME`	Excluir um alerta.	`--yes`, `-y`
`fp alerts test NAME`	Enviar uma notificação de teste.	`--channels`; `--yes`, `-y`

As severidades de alerta são info, warning e critical. Os tipos de gatilho são metric_threshold, custom_sql, evaluation_score, eval_compound e per_event. Os intervalos de avaliação devem estar entre 30 e 86.400 segundos.

Auditorias

Comando	Finalidade	Opções
`fp audits list`	Listar auditorias.	`--enabled-only`; `--show-id`
`fp audits show NAME`	Exibir uma definição de auditoria e seu estado.	—
`fp audits create NAME`	Criar uma auditoria e enfileirar imediatamente sua primeira execução.	Veja opções de criação.
`fp audits edit NAME`	Substituir configurações da auditoria mantendo os valores não especificados.	opções de definição de criação; `--name`; `--yes`, `-y`
`fp audits delete NAME`	Excluir uma auditoria, suas descobertas e o histórico de execuções.	`--yes`, `-y`
`fp audits run NAME`	Enfileirar uma execução manual.	—
`fp audits runs NAME`	Listar histórico de execuções.	`--limit`, `-n`; `--show-id`
`fp audits context-show NAME`	Exibir o resumo e o estado de busca das URLs de referência.	—
`fp audits context-set NAME`	Alterar o resumo ou as URLs de referência.	`--text`; `--text-file`; `--url`; `--clear-urls`
`fp audits context-refresh NAME`	Rebuscar as URLs de referência.	—
`fp audits findings`	Listar descobertas.	`--audit`; `--run-id`; `--status`; `--limit`, `-n`; `--offset`; `--show-id`
`fp audits finding FINDING_ID`	Exibir uma descoberta e suas evidências.	—
`fp audits ack FINDING_ID`	Reconhecer uma descoberta.	`--reason`
`fp audits mute FINDING_ID`	Suprimir um padrão recorrente.	`--reason`; `--yes`, `-y`
`fp audits dismiss FINDING_ID`	Marcar um padrão como não acionável e suprimi-lo.	`--reason`; `--yes`, `-y`
`fp audits resolve FINDING_ID`	Marcar uma descoberta como corrigida sem supressão futura.	`--yes`, `-y`
`fp audits reopen FINDING_ID`	Devolver uma descoberta à fila ativa e limpar a supressão.	—
`fp audits assign FINDING_ID`	Definir o responsável pela descoberta.	`--to <email>` obrigatório

Opções de criação de auditoria

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

Opção	Descrição
`--file <path>`	Basear a definição em JSON ou usar `-` para stdin. Flags explícitas substituem os valores do arquivo.
`--description <text>`	Descrever a questão de falha ou o propósito.
`--enabled` / `--disabled`	Iniciar o agendamento ativado ou desativado. Padrão: habilitado.
`--schedule-interval-secs <n>`	`3600`–`604800`. Padrão: `86400`.
`--schedule-anchor <timestamp>`	Fase UTC fixa em formato ISO 8601. Padrão: próxima 09:00 UTC.
`--window-mode since_last\|fixed`	Continuar após a última janela totalmente analisada ou inspecionar repetidamente uma janela contínua. Padrão: `since_last`.
`--lookback-window-secs <n>`	`3600`–`7776000`. Padrão: `604800`.
`--scope '<json>'`	Filtrar por `environments`, `agent_ids` ou outros campos de escopo suportados.
`--ignore-error-type <type>`	Excluir tipos de erro; repita ou separe por vírgula.
`--llm` / `--no-llm`	Habilitar ou desabilitar a análise agêntica. Padrão: habilitado.
`--top-k <n>`	Reter `1`–`500` descobertas. Padrão: `50`.
`--sensitivity low\|medium\|high`	Definir a sensibilidade de relatórios. Padrão: `medium`.
`--channels '<json>'`	Array de canais de notificação.
`--text <brief>`	Resumo inline, máximo de 8.192 caracteres.
`--text-file <path>`	Ler o resumo de um arquivo; mutuamente exclusivo com `--text`.
`--url <https-url>`	Adicionar uma referência HTTPS pública; repita até cinco vezes.

Inclua o contexto durante a criação quando a primeira execução precisar dele. A criação confirma a definição e o contexto juntos antes que a execução enfileirada comece.

fp audits run é assíncrono. Monitore fp audits runs NAME até que a execução mais recente seja bem-sucedida ou falhe antes de ler suas descobertas.

Problemas

Comando	Finalidade	Opções
`fp issues list`	Listar problemas.	`--state`; `--alert-id`; `--limit`, `-n`; `--show-id`
`fp issues count`	Contar problemas abertos ou estados selecionados.	`--state`
`fp issues show INCIDENT_ID`	Exibir detalhes, comentários, assinantes e atividade de um problema.	—
`fp issues open`	Abrir um problema manual ou vinculado a alerta.	`--summary` obrigatório; `--title`, `--alert-id`, `--severity` opcionais
`fp issues ack INCIDENT_ID`	Reconhecer um problema.	—
`fp issues assign INCIDENT_ID`	Substituir responsáveis; omita a opção para limpá-los.	`--assignee` repetível
`fp issues resolve INCIDENT_ID`	Resolver um problema.	`--yes`, `-y`
`fp issues comment-list INCIDENT_ID`	Listar comentários.	—
`fp issues comment-add INCIDENT_ID`	Adicionar um comentário.	exatamente um de `--body`, `--file`
`fp issues comment-delete INCIDENT_ID COMMENT_ID`	Excluir um comentário.	`--yes`, `-y`
`fp issues subscribers INCIDENT_ID`	Listar assinantes.	—
`fp issues subscribe INCIDENT_ID`	Inscrever você mesmo ou outro operador.	`--email`
`fp issues unsubscribe INCIDENT_ID`	Remover uma assinatura.	`--email`

Os estados válidos de problema são firing, acknowledged e resolved. As severidades de problemas avulsos são info, warning e critical.

Assistente de nuvem

Comando	Finalidade	Opções
`fp agent health`	Verificar disponibilidade e configuração do assistente.	—
`fp agent models`	Listar modelos disponíveis do assistente.	—
`fp agent chats`	Listar conversas salvas.	—
`fp agent ask [MESSAGE]`	Iniciar ou continuar uma conversa; lê stdin quando a mensagem é omitida.	`--chat`; `--model`; `--page-context`
`fp agent show CHAT_ID`	Exibir uma conversa salva.	—
`fp agent rename CHAT_ID`	Renomear uma conversa.	`--title` obrigatório
`fp agent delete CHAT_ID`	Excluir uma conversa.	`--yes`, `-y`

Políticas

Versões de políticas gerenciadas pela nuvem. Somente sessão — cada comando aqui encerra com 2 sob uma chave de API, antes de qualquer requisição, pois são rotas de escrita exclusivas de root deliberadamente ausentes de /v1.

Comando	Finalidade	Opções
`fp policies list`	Listar versões de políticas.	`--json`
`fp policies show POLICY_ID`	Exibir uma política com seu código-fonte.	—
`fp policies publish NAME PATH`	Criar uma versão a partir de um `.mjs` local.	`--description`; `--no-verify`
`fp policies enable POLICY_ID`	Adicioná-la de volta a cada implantação da qual foi removida, criando uma nova geração em cada uma.	`--yes`, `-y`
`fp policies disable POLICY_ID`	Removê-la de cada implantação que a carrega, criando uma nova geração em cada uma.	`--yes`, `-y`
`fp policies delete POLICY_ID`	Excluir uma versão de política.	`--yes`, `-y`
`fp policies test PATH`	Executar uma política localmente contra um contexto sintético. Aplica o filtro `match` de cada política, portanto uma que não cubra o evento/ferramenta fornecido é reportada como `skipped` em vez de executada.	`--event`; `--tool`; `--command`; `--file`; `--expect`
`fp policies compose PROMPT`	Rascunhar uma política com o assistente. Requer `policies:write`.	—

Frota

Quais máquinas executam quais políticas. Somente sessão, pelo mesmo motivo acima.

Comando	Finalidade	Opções
`fp fleet list`	Listar máquinas registradas e sua geração de implantação.	—
`fp fleet show MACHINE_ID`	O conjunto de políticas que uma máquina executa atualmente.	—
`fp fleet deploy MACHINE_ID`	Substitui todo o conjunto de políticas da máquina. Exibe o plano e pergunta apenas em terminal interativo sem `--json`.	`--add`; `--remove`; `--set`; `--create`; `--yes`, `-y`
`fp fleet diff MACHINE_ID`	Comparar uma máquina com outra implantação.	—
`fp fleet history MACHINE_ID`	Implantações passadas de uma máquina.	—
`fp fleet rollback MACHINE_ID GENERATION`	Reinstaurar o conjunto de políticas de uma geração anterior, como uma nova geração.	`--yes`, `-y`
`fp fleet rename MACHINE_ID`	Dar um nome legível a uma máquina.	`--name` obrigatório

Guardrails

O que a aplicação realmente fez. Somente sessão, pelo mesmo motivo acima.

Comando	Finalidade	Opções
`fp guardrails summary`	Cobertura, totais bloqueados/avaliados, um sparkline de negações e a tabela por política.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`
`fp guardrails timeline`	Decisões agrupadas ao longo da janela, somadas por todas as fontes de política.	`--since` (`1h`, `6h`, `24h`, `7d`); `--machine`

Flags globais

Flag	Descrição
`--json`	Emitir JSON legível por máquina.
`--base-url <url>`	Usar um painel auto-hospedado ou de desenvolvimento.
`--org <slug>`	Selecionar uma organização para esta invocação.
`--token <token>`	Substituir o token de sessão de usuário salvo.
`--api-key <key>`	Autenticar automação com uma chave de API; nunca salva.
`--timeout <seconds>`	Timeout HTTP; deve ser positivo. Padrão: `30`.
`--quiet`, `-q`	Suprimir saída de status no stderr.
`--no-color`	Desabilitar saída colorida.
`--insecure` / `--secure`	Desabilitar ou restaurar a verificação de certificado TLS.
`--version`	Imprimir a versão e sair.
`--help`, `-h`	Exibir ajuda.

--api-key é destinado a automação. Login, troca de organização e comandos do assistente requerem uma sessão de usuário.

Variáveis de ambiente

Variável	Equivalente ou finalidade
`FP_DASHBOARD_URL`	`--base-url`
`FP_ORG`	`--org`
`FP_TOKEN`	`--token`
`FP_API_KEY`	`--api-key`
`FP_JSON`	`--json`
`FP_INSECURE`	`--insecure`
`FP_HOME`	Realocar o diretório de configuração da CLI (padrão `~/.failproofai/fpcli`).
`FP_ANALYTICS_DISABLED` ou `DO_NOT_TRACK`	Desabilitar a telemetria anônima da CLI.
`NO_COLOR`	Desabilitar saída colorida.

Flags explícitas substituem variáveis de ambiente, que substituem a configuração salva. No modo de chave de API, selecione o tenant explicitamente com --org ou FP_ORG.

As variações AGENTEYE_* dessas variáveis não são lidas por fp e nunca foram — a CLI declara FP_* (fp_cli/app.py), e uma variável desconhecida não é um erro. Definir AGENTEYE_DASHBOARD_URL não redireciona a CLI; ela é ignorada e o comando executa silenciosamente contra o painel salvo.AGENTEYE_HOME e AGENTEYE_ENVIRONMENT ainda existem, mas pertencem ao coletor e ao SDK de telemetria, não a esta CLI.

Comandos que excluem, revogam, suprimem, resolvem ou substituem configurações solicitam confirmação por padrão. Use --yes somente após verificar a organização ativa e o destino.

Connect your agents

Reference

Entrar

Sintaxe

Comandos da CLI

Autenticação

Eventos

Sessões

Avaliações

Erros

Uso e valores de filtro

Organizações

Chaves de API

Consultas

Usuários

Configurações

Alertas

Auditorias

Opções de criação de auditoria

Problemas

Assistente de nuvem

Políticas

Frota

Guardrails

Flags globais

Variáveis de ambiente

​Entrar

​Sintaxe

​Comandos da CLI

​Autenticação

​Eventos

​Sessões

​Avaliações

​Erros

​Uso e valores de filtro

​Organizações

​Chaves de API

​Consultas

​Usuários

​Configurações

​Alertas

​Auditorias

​Opções de criação de auditoria

​Problemas

​Assistente de nuvem

​Políticas

​Frota

​Guardrails

​Flags globais

​Variáveis de ambiente

Entrar

Sintaxe

Comandos da CLI

Autenticação

Eventos

Sessões

Avaliações

Erros

Uso e valores de filtro

Organizações

Chaves de API

Consultas

Usuários

Configurações

Alertas

Auditorias

Opções de criação de auditoria

Problemas

Assistente de nuvem

Políticas

Frota

Guardrails

Flags globais

Variáveis de ambiente