fp para inspecionar telemetria Cloud e gerenciar auditorias, achados, 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 como uma ferramenta isolada:
uv tool install fp-cli
fp version
Autenticar
fp login
fp whoami
Sintaxe
fp [GLOBAL_OPTIONS] COMMAND [SUBCOMMAND] [ARGUMENTS] [OPTIONS]
fp --json sessions --since 24h
fp COMMAND --help ou fp COMMAND SUBCOMMAND --help para ajuda no terminal.
Comandos da CLI
Autenticação
| Comando | Finalidade | Opções |
|---|---|---|
fp login | Entrar com um código de uso ú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 ajuda de comandos de nível superior. | — |
fp login --email voce@exemplo.com --org equipe-confiabilidade
fp whoami
Eventos
fp events [OPTIONS]
--full apenas para investigações delimitadas.
| 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 ISO 8601; substitui --since. |
--env <value> | Filtro de ambiente; repita ou separe por vírgula. |
--event-type <value> | Filtro de tipo de evento; repita ou separe por vírgula. |
--agent-id <value> | Filtro de agente; repita ou separe por vírgula. |
--session-id <value> | Filtro de sessão; repita ou separe por vírgula. |
--search <text> | Busca em texto do payload; repetível, com correspondência de qualquer termo. |
--order asc|desc | Ordem temporal. Padrão: mais recente primeiro. |
--all | Paginação automática até --limit. |
--cursor <token> | Retomar a partir de um cursor opaco. |
--page-size <n> | Linhas por requisição com --all; máximo 200. |
--full | Incluir payloads brutos pelo endpoint de eventos completo. |
--fields <csv> | Retornar apenas os campos selecionados; solicitar payload ativa o modo completo. |
fp events --session-id <session-id> --order asc --all
fp --json events --full --session-id <session-id> --all
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 ISO 8601; substitui --since. |
--env <value> | Filtro de ambiente; repita ou separe por vírgula. |
--status <value> | done, error ou timeout; repita ou separe por vírgula. |
--agent-id <value> | Corresponde sessões que envolvam qualquer agente selecionado. |
--session-id <value> | Filtro de sessão; repita ou separe por vírgula. |
--all | Paginação automática até --limit. |
--cursor <token> | Retomar a partir de um cursor opaco. |
--page-size <n> | Linhas por requisição com --all; máximo 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 em sessões multi-agente. |
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 os 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 a população de erros. |
--search <text> | Buscar no texto do 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 para a 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 |
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 | Desativar o acesso. | --yes, -y |
fp users enable EMAIL | Reativar o acesso. | --yes, -y |
Configurações
| Comando | Finalidade | Opções |
|---|---|---|
fp settings list | Listar configurações da organização e valores atuais. | — |
fp settings schema | Exibir valores aceitos e descrições. | — |
fp settings set KEY | Alterar uma configuração existente. | exatamente uma de --value, --json-value, --file; --yes, -y opcional |
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 |
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 imediatamente enfileirar sua primeira execução. | Veja opções de criação. |
fp audits edit NAME | Substituir configurações de 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, seus achados e 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 briefing e o estado de busca das URLs de referência. | — |
fp audits context-set NAME | Alterar o briefing ou as URLs de referência. | --text; --text-file; --url; --clear-urls |
fp audits context-refresh NAME | Rebuscar URLs de referência. | — |
fp audits findings | Listar achados. | --audit; --run-id; --status; --limit, -n; --offset; --show-id |
fp audits finding FINDING_ID | Exibir um achado e suas evidências. | — |
fp audits ack FINDING_ID | Confirmar o recebimento de um achado. | --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 um achado como corrigido sem supressão futura. | --yes, -y |
fp audits reopen FINDING_ID | Retornar um achado à fila ativa e limpar a supressão. | — |
fp audits assign FINDING_ID | Definir o responsável pelo achado. | --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 use - para stdin. Flags explícitas substituem os valores do arquivo. |
--description <text> | Descrever a pergunta de falha ou o propósito. |
--enabled / --disabled | Iniciar o agendamento ativado ou desativado. Padrão: ativado. |
--schedule-interval-secs <n> | 3600–604800. Padrão: 86400. |
--schedule-anchor <timestamp> | Fase UTC fixa no formato ISO 8601. Padrão: próximo 09:00 UTC. |
--window-mode since_last|fixed | Continuar após a última janela completamente 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 erros; repita ou separe por vírgula. |
--llm / --no-llm | Ativar ou desativar a análise agêntica. Padrão: ativado. |
--top-k <n> | Manter 1–500 achados. Padrão: 50. |
--sensitivity low|medium|high | Definir a sensibilidade dos relatórios. Padrão: medium. |
--channels '<json>' | Array de canais de notificação. |
--text <brief> | Briefing inline, máximo de 8.192 caracteres. |
--text-file <path> | Ler o briefing de um arquivo; mutuamente exclusivo com --text. |
--url <https-url> | Adicionar uma referência HTTPS pública; repita até cinco vezes. |
fp audits run é assíncrono. Consulte fp audits runs NAME até que a execução mais recente seja concluída com sucesso ou falhe antes de ler seus achados.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 um alerta. | --summary obrigatório; --title, --alert-id, --severity opcionais |
fp issues ack INCIDENT_ID | Confirmar o recebimento de 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 uma 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 | Assinar você mesmo ou outro operador. | --email |
fp issues unsubscribe INCIDENT_ID | Remover uma assinatura. | --email |
firing, acknowledged e resolved. As severidades de problemas avulsos são info, warning e critical.
Assistente Cloud
| Comando | Finalidade | Opções |
|---|---|---|
fp agent health | Verificar a 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 |
Flags globais
| Flag | Descrição |
|---|---|
--json | Emitir JSON legível por máquina. |
--base-url <url> | Usar um dashboard 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> | Tempo limite HTTP; deve ser positivo. Padrão: 30. |
--quiet, -q | Suprimir saída de status no stderr. |
--no-color | Desativar saída colorida. |
--insecure / --secure | Desativar ou restaurar a verificação de certificado TLS. |
--version | Imprimir a versão e sair. |
--help, -h | Exibir ajuda. |
--api-key é destinado a automações. 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 |
|---|---|
AGENTEYE_DASHBOARD_URL | --base-url |
AGENTEYE_ORG | --org |
AGENTEYE_CLI_TOKEN | --token |
AGENTEYE_CLI_API_KEY | --api-key |
AGENTEYE_CLI_JSON | --json |
AGENTEYE_INSECURE | --insecure |
AGENTEYE_HOME | Realocar o diretório de configuração atual da CLI. |
AGENTEYE_ANALYTICS_DISABLED ou DO_NOT_TRACK | Desativar analytics anônimas da CLI. |
NO_COLOR | Desativar saída colorida. |
--org ou AGENTEYE_ORG.
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 alvo.