# Tritonium CLI

The official CLI uses the same scoped product tools as the remote MCP service,
through the official Python MCP SDK. Requires Python 3.11+. Install the versioned
wheel from the public developer site, without access to this repository:

```sh
python3 -m pip install https://tritonium.com/developers/mcp/tritonium_agent-1.0.3-py3-none-any.whl
tritonium discover
# A workspace admin creates a scoped key in Settings > API keys.
export TRITONIUM_API_KEY='trtn_live_...'
tritonium tools
tritonium workspace
tritonium tool list_apps --input '{"limit":10}'
tritonium tool search_reviews --input '{"app_uuid":"<id from list_apps>","max_rating":2,"limit":20}'
tritonium guide
tritonium prompt triage_negative_reviews --input '{"app_uuid":"<id from list_apps>","days":"7"}'
```

Use the `next_cursor` in a result as the next call's `cursor`; the CLI retrieves
one bounded page per call. Tool schemas are authoritative (`tritonium tools`).
Pipe a JSON object with `--input -`. JSON results and errors go to stdout; a
short diagnostic goes to stderr. Commands do not prompt or retry automatically.
For a delegated OAuth workflow, supply a short-lived access token that was
issued for this MCP endpoint instead of an API key:

```sh
unset TRITONIUM_API_KEY
export TRITONIUM_OAUTH_ACCESS_TOKEN='trtn_oat_...'
tritonium workspace
```

Set exactly one credential variable. The CLI accepts an access token but does
not perform OAuth sign-in or refresh it. Use a current token obtained by an
authorized integration; the original OAuth grant remains the identity shown in
Tritonium's Connected agents and audit history. Do not extract a token from an
unrelated agent or share one across integrations. Expired or revoked tokens
return exit code 3; obtain a new token from the integration's OAuth flow.
Neither token type grants more access than its server-side scopes. The CLI
never sends credentials to `tritonium discover`.

Never put a real credential in a command argument or source control; use your
shell's secret injection or a CI secret for the chosen environment variable.

Side-effecting tools require `--allow-write` for **each authorized call**, including
`get_rating_forecast`, which may start a forecast on a cache miss and requires
both `analytics:read` and `apps:write`. Use `get_cached_rating_forecast` with
`analytics:read` to inspect a forecast without starting one. The flag does
not confer server permission or constitute any organization's human approval.
There is no publish, delete, billing, arbitrary HTTP, SQL or shell command.

```sh
# Preview reads current analysis status; it does not queue analysis.
tritonium tool start_app_analysis --input '{"app_uuid":"<id>","dry_run":true}'
# Only after authorization: queues analysis, then inspect get_app until complete.
tritonium tool start_app_analysis --allow-write --input '{"app_uuid":"<id>"}'
# Generates a pending draft, never an app-store publication.
tritonium tool generate_reply_draft --allow-write --input '{"app_uuid":"<id>","review_id":"<id>"}'
```

Credentials with `apps:read` can discover and invoke the preview; their tool schema
requires `dry_run=true`. Workspace context reports `preview_available`
separately from permission to start an analysis (`apps:write`).

Global options precede the command: `--timeout 45` sets the total deadline
(default 30 seconds, maximum 300). `--endpoint` or `TRITONIUM_MCP_URL` selects
an HTTPS `/mcp` endpoint; HTTP is accepted only for loopback development.
TLS verification is always enabled and cross-origin redirects are refused. No config file
or interactive login is needed for CLI commands. MCP transport is Streamable HTTP; there is no
local server or stdio mode, since these workflows operate on hosted workspaces.

Exit codes: 0 success, 1 permanent/unclassified failure or uncertain execution,
2 invalid arguments, 3 authentication required/rejected, 4 permission, missing OAuth scope or write
opt-in required, 5 conflict/not found, 6 retryable service/rate-limit failure.
For uncertain execution, inspect `error.execution_state` and authoritative state
before deciding to retry. `force_refresh` is not idempotent: it can consume AI
capacity again after the first analysis completes.
Transient read transport failures, including discovery or catalog failures before
an action is dispatched, report `retryable: true` and exit 6. Use backoff; the CLI
still never retries automatically. Published versioned wheels remain available
when a newer release is deployed.
Tool results are validated against their advertised output schemas. A malformed
action result reports `execution_state: unknown` and is never automatically
retryable. Inspect the app status or pending draft queue before retrying.
Analysis `outcome: needs_retry` means a stale lock was cleared and no analysis
was queued; repeat the same authorized call. `analysis_resuming` remains in
progress and includes polling guidance.
Packaged source or README changes require a version bump after publication;
deployment refuses different bytes under an existing versioned filename.

For development: `python3.11 -m pip install -e clients/agent` at the repo root.
This CLI is a machine interface, not a claim of compatibility with a named
agent. Record actual client workflow evidence separately.