CLI

Controle toda a Observabilidade do Failproof AI pelo terminal ou por um script: sem precisar acessar o dashboard. O CLI agenteye consulta seus dados (sessões, logs de eventos, avaliações) e administra sua organização (chaves de API, usuários, configurações, alertas, incidentes, consultas salvas), sendo ideal para automatizar verificações, integrar a Observabilidade ao CI ou permitir que um agente de codificação inspecione o ambiente de produção. Todos os comandos suportam o flag --json, funcionando igualmente bem para uso interativo no terminal ou para um agente de codificação (Claude Code, Cursor) que executa o comando e processa o resultado. Com um único binário você pode:

Ler seus dados: sessions, events, evals, errors (filtre por tempo, agente, ambiente, pontuação).
Gerenciar sua organização: keys, users, settings, alerts, incidents.
Executar análises: SQL salvo e um executor de consultas ad-hoc (query).
Consultar o assistente de IA: o mesmo analista somente leitura disponível no dashboard (agent).

Nota: Este é o CLI agenteye, uma ferramenta diferente do daemon coletor (agenteye-collector). O CLI se comunica com o seu dashboard; o coletor envia eventos para o servidor.

Início rápido

Do zero ao seu primeiro resultado em quatro linhas. Aponte o CLI para o seu dashboard, faça login, confirme quem você é e, em seguida, busque as execuções das últimas 24 horas:

pipx install agenteye
agenteye --base-url https://agenteye.example.com login --email you@example.com   # código de 6 dígitos enviado por e-mail
agenteye whoami                                                                  # confirma usuário + org ativa
agenteye --json sessions --since 24h                                             # uma linha por execução do agente, últimas 24h

O último comando imprime um objeto JSON com as sessões mais recentes (as mais novas primeiro, limitado a 50 por padrão). Encadeie com jq para filtrar, ou remova --json para obter uma tabela colorida em caixas. Cada linha contém o status da execução e, se um avaliador atribuiu uma pontuação, as métricas correspondentes (abreviadas aqui):

{
  "sessions": [
    {
      "session_id": "run-8f2a",
      "agent_id": "checkout-bot",
      "environment": "prod",
      "status": "error",
      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
      "event_count": 37,
      "started_at": "2026-07-16T09:14:02Z",
      "last_event_at": "2026-07-16T09:14:48Z"
    }
  ],
  "next_cursor": null
}

O restante desta página explica cada parte: instalação em ambiente isolado, autenticação, configuração, as convenções globais compartilhadas por todos os comandos e a referência completa de comandos.

Instalação

O CLI é um pacote público no PyPI chamado agenteye. Instale-o em um ambiente isolado para que sempre tenha suas próprias dependências:

pipx install agenteye
# ou
uv tool install agenteye

Requer Python 3.10+. O comando instalado é agenteye:

agenteye --version
agenteye --help

Nota: O SDK Python de Observabilidade do Failproof AI também usa o nome de distribuição agenteye. Instalar o CLI com pipx ou uv tool (em vez de pip install em um virtualenv compartilhado) evita conflitos entre os dois. Um simples pip install agenteye só é adequado se o SDK não estiver instalado no mesmo ambiente.

Autenticação

O CLI autentica no dashboard com um código de uso único enviado por e-mail:

agenteye login --email you@example.com
# Um código de 6 dígitos é enviado para você; cole-o no prompt.

O token de sessão é armazenado em ~/.agenteye/cli.json (legível apenas por você, modo 0600) e é válido por 24 horas por padrão. Quando expirar, execute agenteye login novamente.

agenteye whoami     # exibe o usuário atual, a org ativa e as permissões
agenteye logout     # revoga a sessão e limpa o token armazenado

whoami nunca retorna erro por sessão ausente ou expirada; em vez disso, retorna logged_in: false, para que um script ou agente possa verificar o estado de autenticação com segurança (ainda pode sair com código diferente de zero se nenhuma URL base estiver definida ou se o dashboard estiver inacessível). Requisitos: seu e-mail deve ter permissão para acessar o dashboard (solicite ao administrador do Failproof AI Observability), e o dashboard deve estar acessível na sua URL base (consulte Configuração). Se você solicitar um código e ele não chegar, provavelmente seu e-mail ainda não está habilitado para acesso ao dashboard.

Escolhendo sua organização (multi-tenant)

Se sua conta pertence a mais de uma organização, escolha a ativa no momento do login; ela é salva e usada em todos os comandos subsequentes:

agenteye login --org acme           # autentica e define o tenant ativo em uma etapa
agenteye orgs list                  # as orgs que você pode acessar (a ativa está marcada)
agenteye orgs switch globex         # altera o padrão salvo
agenteye --org globex sessions      # substituição para um único comando

Se você pertence a exatamente uma organização, ela é selecionada automaticamente e você pode ignorar --org completamente. Se pertencer a várias e não escolher uma, o CLI lista-as e solicita que você reexecute com --org <slug>. A org ativa é enviada ao dashboard em cada requisição, e suas permissões são resolvidas por organização; agenteye whoami exibe a org ativa, suas permissões nela e todas as suas associações.

Configuração

Configuração	Flag	Variável de ambiente	Padrão
URL base do dashboard	`--base-url`	`AGENTEYE_DASHBOARD_URL`	obrigatório (sem padrão)
Org/tenant ativa	`--org`	`AGENTEYE_ORG`	definida no login; salva em `~/.agenteye/cli.json`
Token de sessão	`--token`	`AGENTEYE_CLI_TOKEN`	de `~/.agenteye/cli.json`
Saída JSON	`--json`	`AGENTEYE_CLI_JSON`	desativado
Ignorar verificação TLS	`--insecure` / `--secure`	`AGENTEYE_INSECURE`	desativado (salvo no login)
Timeout da requisição (segundos)	`--timeout`	(nenhum)	30
Desativar telemetria de uso	(nenhum)	`AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`)	telemetria está desativada no momento; nada é enviado

A ordem de resolução é flag → variável de ambiente → arquivo de configuração. Não há padrão; você deve apontar o CLI para o seu dashboard, seja por comando (--base-url https://agenteye.example.com) ou uma vez via variável de ambiente (também é salvo após o primeiro login):

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com

O diretório de configuração respeita AGENTEYE_HOME (a mesma convenção usada pelo SDK e pelo coletor); se definido, cli.json fica em $AGENTEYE_HOME/cli.json.

TLS autoassinado ou interno

Se o seu dashboard usa HTTPS com um certificado autoassinado ou interno (por exemplo, o nome de host bruto de um balanceador de carga), a verificação TLS rejeita a conexão com um erro CERTIFICATE_VERIFY_FAILED. Use --insecure para ignorar a verificação de certificado:

agenteye --base-url https://agenteye.internal --insecure login

--insecure é salvo em cli.json quando você faz login, portanto os comandos posteriores ignoram a verificação automaticamente; você não precisa repetir o flag. Use --secure para uma chamada verificada pontual, ou para restaurar a verificação no próximo login. O CLI exibe um aviso no stderr antes de qualquer comando que contate o dashboard com a verificação desativada. Ignorar a verificação remove a proteção contra ataques man-in-the-middle; certifique-se de confiar no caminho de rede até o seu dashboard (VPN, sub-rede privada etc.) antes de depender disso.

Telemetria e privacidade

Nota: O CLI distribuído não envia telemetria de uso hoje. Um interruptor mestre está ativo, portanto nada é transmitido independentemente do seu ambiente. A seção abaixo descreve a capacidade de desativação para quando a telemetria vier a ser habilitada.

Mesmo quando habilitada, a telemetria seria apenas análises de uso anônimo, nunca seus dados de agente, sessão ou eventos:

Nenhum dado de agente, sessão ou evento sai da sua infraestrutura. Apenas o uso do CLI seria reportado: o nome do comando e subcomando (ex.: keys create), os nomes dos flags usados (nunca seus valores), status de sucesso/saída e duração, além de um evento por ação para mutações (ex.: api_key_created, query_run) contendo apenas nomes/enums estáticos e contagens aproximadas. Sua URL do dashboard, token de sessão, e-mail, slug da org, IDs de recursos, SQL, segredos de chaves e filtros de consulta nunca seriam enviados. Os operadores seriam identificados apenas por um ID interno opaco, nunca por e-mail.
Desative antecipadamente definindo AGENTEYE_ANALYTICS_DISABLED=1 no ambiente do CLI (o CLI também respeita a convenção entre ferramentas DO_NOT_TRACK=1). Isso entra em vigor no momento em que a telemetria for ativada, permitindo que um ambiente voltado para privacidade permaneça desativado permanentemente.
Se a telemetria fosse habilitada, o CLI enviaria diretamente para o PostHog (https://us.i.posthog.com); uma máquina com esse host bloqueado simplesmente não enviaria nada e o CLI não seria afetado.

Opções globais e convenções

Leia esta seção uma vez; ela se aplica a todos os comandos.

As opções globais vêm ANTES do comando. agenteye --json sessions está correto; agenteye sessions --json é um erro de uso. As opções globais são --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet e --no-color.
--json imprime JSON puro no stdout e nada mais. Linhas de status, avisos e erros vão para o stderr, para que uma captura do stdout com --json permaneça limpa para encadear com jq, mesmo quando uma linha de status é exibida. Sem --json, você obtém uma visualização colorida em caixas para leitura humana.
Descubra com --help. Cada comando e subcomando tem --help (e o alias -h): agenteye -h, agenteye sessions -h, agenteye keys create -h. O help de nível superior também lista os códigos de saída e as opções globais. Não há uma superfície global legível por máquina; use --help por comando, além de agenteye query schema e agenteye settings schema específicos de domínio para esses dois registros.
Confirmações são ignoradas automaticamente para scripts e agentes. Comandos de criação/atualização/exclusão exibem “tem certeza?” em um terminal interativo, mas ignoram esse prompt automaticamente sob --json ou quando o stdin não é um TTY (um TTY é uma sessão de terminal interativa; um pipe ou um runner de CI não é), para que scripts e agentes nunca fiquem travados. Use --yes/-y para ignorá-lo explicitamente. Como o prompt não será exibido para um agente, ele deve confirmar ações destrutivas com o humano antes de executar.
Paginação: os resultados são os mais novos primeiro e usam paginação por cursor (cada página retorna um token para buscar a próxima). --limit N (alias -n) limita as linhas e tem padrão de 50; --all pagina automaticamente (em blocos de 200 linhas) até --limit, portanto um --all simples ainda para em 50. Para uma varredura completa, passe um limite alto explícito: --all --limit 1000. --page-size N controla o bloco por requisição (máximo 200); --cursor <id> retoma a partir do next_cursor de uma página anterior.
Filtros de tempo: --since aceita uma janela relativa: 15m, 1h, 6h, 24h, 7d ou all (os presets do dashboard). Para um intervalo mais longo ou personalizado (como os últimos 30 dias), use --from/--to: timestamps UTC explícitos no formato ISO-8601 com T e timezone (ex.: 2026-06-01T00:00:00Z) que substituem --since. Um valor separado por espaço ou sem timezone é um erro de uso.
--fields a,b,c (em events, sessions, evals, errors) restringe a saída a essas chaves, tanto na tabela quanto no --json. Nomes desconhecidos são rejeitados com a lista válida, uma forma barata de descobrir os nomes de campos.
--file payload.json (ou --file - para ler do stdin) fornece um corpo de requisição JSON completo quando um recurso tem uma forma complexa (em alerts create/update, settings set e users create/update). SQL de consultas salvas usa --sql @file.sql em vez disso.
Filtros com múltiplos valores são separados por vírgula → correspondidos como um conjunto (união dentro de um filtro, AND entre filtros): --event-type tool_use,tool_result. As opções Click não são variádicas, portanto --add a b não funciona. Use --add a,b, repita o flag (--add a --add b) ou use aspas (--add "a b").

Referência de comandos

Os 5 comandos que você mais usará

A maior parte do trabalho cotidiano passa por um conjunto de comandos de leitura. Comece por aqui e recorra à superfície completa abaixo quando necessário:

Comando	O que faz	Experimente
`sessions`	Uma linha por execução do agente: tempo, ambiente, agente, status, última pontuação.	`agenteye --json sessions --since 24h --status error`
`events`	O rastro bruto passo a passo dentro de uma execução (adicione `--full` para os payloads).	`agenteye --json events --session-id run-001 --all`
`evals`	Resultados de avaliação e pontuações; `--aggregate` os agrega.	`agenteye --json evals --aggregate --since 7d --env prod`
`errors`	Apenas os eventos com erro; `--aggregate` para contagens por tipo.	`agenteye --json errors --since 24h --aggregate`
`list`	Descubra os valores de filtro válidos (agentes, ambientes, modelos, …).	`agenteye list agents`

Tudo o que o CLI pode fazer

A superfície completa segue abaixo. O CLI tem 18 comandos de nível superior. Todos os comandos de leitura aceitam --json e as opções globais acima; execute agenteye <command> -h (ou <command> <subcommand> -h) para a lista completa de flags e o formato JSON de qualquer um deles.

agenteye login --email you@example.com [--org acme]   # código de uso único por e-mail; salva a sessão
agenteye logout                                       # limpa a sessão salva nesta máquina
agenteye whoami                                       # usuário atual, org ativa, permissões
agenteye version                                      # exibe a versão do CLI (igual a --version)
agenteye help                                         # help de nível superior (igual a --help)

orgs inspeciona e alterna o tenant ativo:

agenteye orgs list        # suas orgs + sua função em cada uma (a ativa está marcada)
agenteye orgs switch acme # altera a org ativa salva (omita o slug para escolher de uma lista em um TTY)
agenteye orgs current     # cartão de identidade da org ativa
agenteye orgs perms       # suas permissões na org ativa, agrupadas por recurso

Observar (somente leitura): `events` · `sessions` · `evals` · `errors` · `list`

Nenhum desses requer confirmação. Filtros compartilhados: --session-id, --agent-id, --env (não --environment) e o intervalo de tempo (--since / --from / --to).

# events (alias: rastro bruto passo a passo), mais novos primeiro
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'

# sessions: uma linha por execução do agente (tempo/ambiente/agente/sessão/status; sem filtro por pontuação)
agenteye --json sessions --since 24h --status error
agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000

# evals: resultados de avaliação + pontuações; --score filtra por métrica, --aggregate agrega
agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
agenteye --json evals --aggregate --since 7d --env prod        # mix de status + estatísticas de pontuação por chave

# errors: eventos com erro; --aggregate para contagens/sessões/agentes/último registro
agenteye --json errors --since 24h --aggregate
agenteye --json errors --since 24h --error-type timeout --all --limit 1000

# list: descubra valores de filtro válidos antes de filtrar
agenteye list envs        # também: agents event_types score_filters models hooks tools error_types

--score KEY:MIN..MAX (em evals, não em sessions) é repetível e combinado com AND; qualquer um dos limites é opcional (..0.5 significa ≤ 0,5; 0.9.. significa ≥ 0,9). Até 20 filtros de pontuação por requisição. evals --scores-full é um flag de exibição apenas para a tabela humana; mostra todos os pares de pontuação em vez dos primeiros mais uma contagem +N. Não tem efeito com --json, que sempre retorna o objeto de pontuação completo. Para ler uma sessão de ponta a ponta, combine o rastro de eventos com sua avaliação:

agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
agenteye --json evals  --session-id run-001                       # suas pontuações + status

Gerenciar (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents`

keys: chaves de API. O segredo é gerado localmente, enviado ao servidor (que armazena apenas um hash) e exibido uma única vez no momento da criação/regeneração; capture-o imediatamente. Com --json ele aparece apenas no campo key. Referenciado por nome.

agenteye keys list                                   # chaves ativas primeiro, depois revogadas
agenteye keys show ci-bot
agenteye keys create ci-bot --add events:read.add    # escopo mínimo necessário; imprime o segredo UMA VEZ
agenteye keys create ops --permission-set standard --remove queries:run   # começa com um preset, depois ajusta
agenteye keys update ci-bot --add evaluations:read --yes
agenteye keys regenerate ci-bot --yes                # rotaciona o segredo (o anterior para de funcionar)
agenteye keys disable ci-bot --yes                   # revoga

As permissões funcionam como (permission-set ∪ --add) − --remove. Os tokens são slug:action (ex.: events:read) ou slug:action.action para expandir várias ações em um recurso (events:read.add → events:read, events:add). Presets: read-only, standard, admin. Permissões exclusivas para humanos (keys:update) não podem ser concedidas a uma chave. users: membros da organização, referenciados por e-mail (um UUID de id também é aceito).

agenteye users list [--active-only]
agenteye users show dev@corp.com
agenteye users create dev@corp.com --permission-set standard
agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # prevê + confirma
agenteye users disable dev@corp.com --yes            # possui proteções para usuário protegido/próprio
agenteye users enable dev@corp.com

settings: um registro fixo (você lê e altera chaves existentes; não é possível criar novas).

agenteye settings list                               # chave · valor · tipo · atualizado (segredos mascarados)
agenteye settings schema                             # o que cada chave aceita (tipo · intervalo · descrição)
agenteye settings set session_ttl_secs --value 86400 --yes

alerts: definições de alertas, referenciadas por nome. create aceita um NOME posicional mais flags ou um corpo JSON completo via --file.

agenteye alerts list
agenteye alerts show high-errors
agenteye alerts create high-errors --file alert.json          # NAME é obrigatório (posicional)
agenteye alerts update high-errors --severity critical --yes
agenteye alerts test high-errors --yes                        # dispara uma notificação de teste
agenteye alerts delete high-errors --yes

incidents: incidentes de alerta, referenciados por id (ids curtos são aceitos). show imprime o log completo de atividades; leia-o antes de agir.

agenteye incidents list --state firing                # também: acknowledged, resolved
agenteye incidents count
agenteye incidents show <id>
agenteye incidents ack <id>
agenteye incidents assign <id> you@corp.com           # o responsável deve ser um operador
agenteye incidents resolve <id> --yes
agenteye incidents open --alert-id <id> --severity critical    # abre manualmente contra um alerta
agenteye incidents comment-add <id> "root cause: upstream 5xx"
agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>

Análises e assistente: `query` · `agent`

query: SQL salvo contra seu armazenamento de análises mais um executor ad-hoc. Consultas salvas são referenciadas por nome; o SQL é validado no servidor (apenas SELECT/WITH, timeout de instrução, limite de linhas).

agenteye query schema [TABLE]                         # layout de colunas das views de análise
agenteye query run --sql "select count(*) from analytics.events"
agenteye query run errs --arg prod --limit 100        # executa uma consulta salva + um $1 posicional
agenteye query list ; agenteye query show errs
agenteye query create errs --sql @errs.sql --description "errored events (24h)"
agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes

agent: fala com o assistente de IA integrado (o mesmo analista somente leitura disponível para chat no dashboard). Os chats são referenciados por um chat-id curto (resolvido por prefixo).

agenteye agent health                                 # verifica se o assistente de IA está configurado/acessível
agenteye agent models                                 # modelos que podem ser passados para --model (o padrão está marcado)
agenteye agent ask "which agents errored most in the last day?"    # inicia um chat; imprime seu id curto
agenteye agent ask --chat <short-id> "and which tools did they call?"   # continua aquele chat
agenteye agent chats ; agenteye agent show <short-id>
agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>

Códigos de saída

Código	Significado
0	Sucesso
1	Erro inesperado (ex.: o dashboard retornou um 5xx)
2	Erro de uso (argumentos inválidos, comando/flag desconhecido, colisão de nomes)
3	Não foi possível alcançar o dashboard
4	Não autenticado ou sessão expirada; execute `agenteye login`
5	Autenticado, mas sua conta não tem a permissão necessária (a mensagem a identifica)
6	O recurso solicitado não foi encontrado (ex.: sessão ou id de incidente desconhecido)

Esses códigos tornam o CLI seguro para scripts: um agente de codificação pode ramificar em um 4 para solicitar reautenticação, ou em um 5 para expor a permissão ausente. Consulte Receitas de CLI para agentes para padrões de tratamento de códigos de saída e formatos de saída JSON.

Próximos passos

Receitas de CLI para agentes: padrões de consulta prontos para uso, one-liners com jq, projeções com --fields, tratamento de códigos de saída e formatos de saída JSON, escritos para agentes de codificação que operam o CLI.
Skill de agente CLI: empacote este CLI como uma skill instalável para Claude Code / Codex, permitindo que um agente de codificação opere o Failproof AI Observability com solicitações em linguagem natural.
Chaves de API: o modelo de permissões por trás de keys create --add ….
Assistente de IA: habilitando o assistente que agent ask utiliza.

Overview

Features

SDK and CLI

Administration

Início rápido

Instalação

Autenticação

Escolhendo sua organização (multi-tenant)

Configuração

TLS autoassinado ou interno

Telemetria e privacidade

Opções globais e convenções

Referência de comandos

Os 5 comandos que você mais usará

Tudo o que o CLI pode fazer

Observar (somente leitura): `events` · `sessions` · `evals` · `errors` · `list`

Gerenciar (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents`

Análises e assistente: `query` · `agent`

Códigos de saída

Próximos passos

​Início rápido

​Instalação

​Autenticação

​Escolhendo sua organização (multi-tenant)

​Configuração

​TLS autoassinado ou interno

​Telemetria e privacidade

​Opções globais e convenções

​Referência de comandos

​Os 5 comandos que você mais usará

​Tudo o que o CLI pode fazer

​Identidade: login · logout · whoami · orgs · version · help

​Observar (somente leitura): events · sessions · evals · errors · list

​Gerenciar (com controle de permissão): keys · users · settings · alerts · incidents

​Análises e assistente: query · agent

​Códigos de saída

​Próximos passos

Início rápido

Instalação

Autenticação

Escolhendo sua organização (multi-tenant)

Configuração

TLS autoassinado ou interno

Telemetria e privacidade

Opções globais e convenções

Referência de comandos

Os 5 comandos que você mais usará

Tudo o que o CLI pode fazer

Identidade: `login` · `logout` · `whoami` · `orgs` · `version` · `help`

Observar (somente leitura): `events` · `sessions` · `evals` · `errors` · `list`

Gerenciar (com controle de permissão): `keys` · `users` · `settings` · `alerts` · `incidents`

Análises e assistente: `query` · `agent`

Códigos de saída

Próximos passos