agenteye 0.1.13

Command-line client for the AgentEye dashboard API

AgentEye CLI (agenteye)

A command-line client for the AgentEye dashboard API. It lets a developer — or the coding agent working alongside them — authenticate and query agent sessions, event logs, and evaluations from the terminal, with a --json flag on every command for scripting.

This is the agenteye CLI, distinct from the collector daemon (agenteye-collector). The PyPI package and the installed command are both agenteye.

Install

pipx install agenteye      # recommended (isolated)
# or: uv tool install agenteye  /  pip install agenteye

Install isolated (pipx / uv tool) — the AgentEye Python SDK shares the agenteye distribution name, so isolation avoids a clash in a shared virtualenv.

For development in this repo:

cd cli
uv sync --extra dev
uv run agenteye --help

Authentication

The CLI talks to your dashboard (set --base-url or AGENTEYE_DASHBOARD_URL) and logs in with an emailed one-time code:

agenteye login --email [e-mail]
# enter the 6-digit code; the session is stored in ~/.agenteye/cli.json (mode 0600)
agenteye whoami
agenteye logout

Sessions expire (24h by default); re-run agenteye login when prompted.

Working across orgs (multi-tenant)

Your account can belong to more than one org. The active org is chosen at login and saved:

agenteye login --org acme              # pick the tenant at login (saved for later commands)
agenteye orgs list                     # your orgs + your role in each (active one marked)
agenteye orgs switch globex            # switch the active org (pass a slug…)
agenteye orgs switch                   # …or omit it to pick from a list (in a terminal)
agenteye orgs current                  # which org you're acting as right now (identity card)
agenteye orgs perms                    # your permissions in the active org (grouped by resource)
agenteye --org globex sessions         # override for a single command

If you belong to exactly one org it's selected automatically. If you belong to several, you pick at login (or with orgs switch); pass --org to choose non-interactively. A slug you can't access (non-existent, or not yours) is rejected rather than saved. The active org is sent as the X-AgentEye-Org header on every request, and your permissions are resolved per org. (All tenant commands live under one group: orgs list / orgs switch / orgs current / orgs perms.)

Commands

Query & observability

agenteye sessions [--since 24h] [--status error] [--agent-id <id>] [--all]   # runs: time/env/agent/session/status
agenteye evals [--score helpfulness:..0.5] [--all]   # eval results + scores
agenteye evals --aggregate [--since 7d]              # rolled-up eval health (status mix + per-metric score stats)
agenteye events --session-id <id> [--event-type tool_use,tool_result] [--env prod] [--all]
agenteye errors [--since 24h] [--error-type TimeoutError] [--all]   # list errored events
agenteye errors --aggregate [--since 7d]            # error summary (count + sessions/agents/last seen)
agenteye list <thing>                   # discover dropdown values to filter on:
#   envs · agents · event_types · score_filters · models · hooks · tools · error_types

Manage your org (each gated by the matching permission)

agenteye keys list|show|create|update|disable|regenerate     # API keys (secret shown once)
agenteye users list|show|create|update|disable|enable
agenteye settings list|schema|set
agenteye alerts list|show|create|update|delete|test
agenteye incidents list|count|show|ack|assign|resolve|comment-add|comment-list|comment-delete|subscribe|subscribers|unsubscribe|open

Analytics & assistant

agenteye query list|show|create|update|delete|run|schema   # saved SQL + ad-hoc runner
agenteye agent health|models|chats|show|rename|delete|ask
#   agent models                 → models available for --model (with the default marked)
#   agent ask "…"                → starts a NEW chat, answers + persists, prints the chat id
#   agent ask --chat <id> "…"    → continue that chat (shows in the dashboard; 1st Q auto-titles)
#   agent chats|show <id>|rename <id> --title …|delete <id>   → manage saved chats
agenteye version | help

Mutations are non-interactive-safe. Create/update/delete prompt for confirmation in a terminal, but auto-skip the prompt under --json or when stdin isn't a TTY (so scripts/agents never hang). Pass --yes/-y to skip it explicitly. Request bodies can be supplied with --file payload.json (or --file - for stdin) on alerts, settings, and users create/update — mutually exclusive with the discrete flags. (Saved-query SQL uses --sql @file.sql.)

Every command and subcommand has --help / -h; agenteye -h documents auth, exit codes, and the global options. Global options go before the command (agenteye --json events, not agenteye events --json).

Add --json for machine-readable output, and --fields to project just the keys you need:

agenteye --json events --session-id run-001 --all | jq '.events[].payload'
agenteye --json sessions --since 7d --fields session_id,status,scores

Configuration

Setting	Flag	Env var	Default
Dashboard URL	--base-url	AGENTEYE_DASHBOARD_URL	required (no default)
Active org/tenant	--org	AGENTEYE_ORG	chosen at login; saved in ~/.agenteye/cli.json
Session token	--token	AGENTEYE_CLI_TOKEN	from ~/.agenteye/cli.json
JSON output	--json	AGENTEYE_CLI_JSON	off
Skip TLS verification	--insecure / --secure	AGENTEYE_INSECURE	off (saved at login)
Disable usage telemetry	(none)	AGENTEYE_ANALYTICS_DISABLED (or DO_NOT_TRACK)	telemetry on

Precedence is flag > environment variable > config file. The dashboard URL is required (no default) — set --base-url or AGENTEYE_DASHBOARD_URL, or it's saved after your first login. The config directory honours AGENTEYE_HOME (same as the SDK and collector).

For a dashboard with a self-signed or internal TLS certificate, add --insecure to skip certificate verification (saved at login, so you set it once). This disables protection against man-in-the-middle attacks — prefer a valid certificate outside internal/testing use.

Telemetry

The CLI sends anonymous usage analytics — which command ran (including its subcommand, e.g. keys create), success/exit status and duration, the names of flags used, and a per-action event for mutations (e.g. api_key_created, query_run) carrying only static names/enums and coarse counts. No data, URLs, tokens, emails, ids, SQL, key secrets, or query values are ever sent, and operators are identified only by an opaque id. It's on by default — disable it with AGENTEYE_ANALYTICS_DISABLED=1 (or the cross-tool DO_NOT_TRACK=1). Sending is time-bounded, so it never delays a command. See enterprise-docs/cli.md for the full privacy details.

Exit codes

Code	Meaning
0	Success
1	Unexpected error (e.g. an unhandled server status)
2	Usage error (bad arguments)
3	Cannot reach the dashboard
4	Not logged in / session expired
5	Authenticated but missing permission
6	Resource not found

Tests

cd cli
uv run --extra dev pytest