Metadata-Version: 2.4
Name: agenteye
Version: 0.1.10
Summary: Command-line client for the AgentEye dashboard API
Author-email: Failproof AI <support@exosphere.host>
License: Proprietary
Project-URL: Homepage, https://befailproof.ai
Project-URL: Documentation, https://github.com/agenteye-enterprise/releases
Keywords: agents,observability,ai,monitoring,agenteye,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: click>=8.1
Requires-Dist: rich>=13
Requires-Dist: pygments>=2.13
Requires-Dist: posthog<8,>=3.5
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# 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

```bash
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:

```bash
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:

```bash
agenteye login --email you@example.com
# 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:

```bash
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**

```text
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)

```text
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**

```text
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:

```bash
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

```bash
cd cli
uv run --extra dev pytest
```

<!-- ci: no-op touch to exercise the auto-release trigger (safe to remove) -->
