# Avola Agent CLI

Version: 1.0.1  
Official site: https://avola.uk  
API endpoint: https://avola.uk/api/v1  
CLI download: https://avola.uk/agent/avola-agent.mjs

Use the Avola Agent CLI when a user explicitly asks an agent to inspect Avola services, read their linked Avola balance, place an Avola order, or check an Avola order status.

## Authentication

The user creates an account-scoped key at https://avola.uk/account#api. Read it only from the `AVOLA_API_KEY` environment variable or an approved secret manager. Never ask the user to paste the full key into a prompt. Never print, log, persist, or return the key.

## Install

```bash
curl -fsSL https://avola.uk/agent/avola-agent.mjs -o avola-agent.mjs
node avola-agent.mjs version
```

Requires Node.js 18 or newer. The CLI has no package dependencies.

## Commands

```bash
node avola-agent.mjs doctor
node avola-agent.mjs services --search youtube
node avola-agent.mjs services --category "X / Twitter"
node avola-agent.mjs balance
node avola-agent.mjs order --service SERVICE_ID --link PUBLIC_TARGET_URL --request-id UNIQUE_ID
node avola-agent.mjs status ORDER_ID
node avola-agent.mjs status ORDER_ID_1 ORDER_ID_2
```

All successful results are JSON on stdout. Errors are JSON on stderr and use a non-zero exit code.

## Order safety

- Confirm the service ID and target URL with the user before placing an order.
- Always provide a stable, unique `--request-id` to prevent duplicate orders during retries.
- Treat `order` as a spending action because it charges the Avola balance.
- Do not retry an ambiguous timeout with a new request ID. Check status or retry with the same request ID.
- Do not expose supplier identities, supplier IDs, supplier rates, internal costs, credentials, or admin notes.

## Direct API compatibility

The CLI uses `Authorization: Bearer AVOLA_API_KEY` and JSON POST requests. Supported actions are `services`, `balance`, `add`, and `status`. Full documentation: https://avola.uk/api-docs.html