aoto-cli

Task automation CLI — create per-site tasks, then list, run and fetch their structured JSON results. Every account is personal-first: your API key authenticates you as your own tenant, no external user ids to manage.

Quickstart

npm install -g aoto-cli
aoto login          # opens the browser to authorize this device
aoto demo           # two-minute live demo: creates and runs a sample task
aoto sites          # list your sites
aoto automate "<instruction>"   # create your first task
aoto run <task>     # run it
aoto get <task>     # fetch the structured JSON result

Authentication

aoto login uses a device-code flow: it prints a short code and opens https://login.aoto.ai/cli for you to approve (the old https://aoto.ai/auth/cli redirects there). The issued user-level API key is stored locally. Alternatives:

• aoto --api-key <key> … — one-off override (good for servers/CI)
• AOTO_API_KEY=<key> — environment variable

Create or revoke keys on the portal's Developer page.

Pairing a local agent (aoto agent pair) never asks you to log in twice: if the CLI already holds credentials, pairing reuses them with a single API call — no browser. If you pair first without a CLI login, the browser flow's key is adopted into the CLI credentials in the same pass.

Running bare aoto (no arguments) prints a getting-started panel with your local progress (login → install → pair → run) above the full help.

Commands

| Command | What it does | |---|---| | aoto login / logout / whoami | Device authorization and credential management | | aoto sites | List sites with their tasks and last-run status | | aoto demo | Two-minute live demo: create + run a sample task (costs a few cents) | | aoto automate "<instruction>" | Create a per-site automation task from an instruction | | aoto tasks | List tasks | | aoto run <task> / aoto get <task> | Run a task / fetch its result | | aoto page <url> | Fetch a page through the cloud browser | | aoto deploy | Deploy a task script | | aoto recipe <slug> | Deploy a curated recipe from the recipe site (aoto.ai/recipes) as a task | | aoto balance / aoto recharge | Wallet balance / top-up | | aoto agent pair / start / doctor / status / install | Manage the local agent (run tasks on this machine) | | aoto mail bind / list / watch / unbind | Bind mailboxes via the local agent and watch incoming mail | | aoto mcp | Start the bundled MCP server (see below) |

Global flags: --json (machine-readable stdout), --api-key <key>.

Local agent

aoto agent wraps the standalone aoto-local-agent binary, which pairs this machine with your account and runs tasks on it over a long-lived control-plane connection:

aoto agent install   # download the binary for this platform into ~/.aoto/bin/
aoto agent pair      # pair this machine (reuses your aoto login; browser only if needed)
aoto agent start     # connect to the control plane and run tasks (auto-pairs first if needed)
aoto agent doctor    # environment self-check
aoto agent status    # pairing state + process check (supports --json)

start / doctor forward all arguments to the binary untouched and pass through its exit code. pair is handled by the CLI itself when you are already logged in (zero-interaction pairing via POST /api/v1/devices/auth); otherwise it forwards to the binary's browser flow and adopts the issued key into the CLI credentials. start silently pairs first when the machine is not paired yet but the CLI is logged in. The binary is resolved from AOTO_AGENT_BIN, then ~/.aoto/bin/aoto-local-agent. Downloads come from AOTO_AGENT_DOWNLOAD_BASE (or the built-in download page) as aoto-local-agent-<platform>-<arch>.

Mail

aoto mail binds mailboxes (Gmail, Outlook, …) to your account and streams incoming mail. Binding is driven by the local agent, which must be installed, paired and running first (aoto agent install / pair / start) — the agent opens a browser on this machine for the provider login:

aoto mail bind gmail.com                          # create a binding; browser opens for login
aoto mail bind outlook.com --webhook https://example.com/hook
aoto mail list                                    # bindings: domain, email, status, device, webhook
aoto mail watch [--domain gmail.com]              # stream new mail (Ctrl+C to stop)
aoto mail unbind gmail.com                        # remove a binding

aoto mail bind waits (up to 10 minutes) for the browser login to finish and reports the bound email address. aoto mail watch is display-only — the actual mail monitor runs inside the local agent. With --json, bind/list /unbind emit a JSON document and watch emits one JSON object per line (JSON Lines).

MCP server (AI clients)

The CLI bundles an MCP server (JSON-RPC over stdio) so AI clients can drive aoto as tools. Run aoto mcp, or point your client at it:

{
  "mcpServers": {
    "aoto": {
      "command": "aoto",
      "args": ["mcp"]
    }
  }
}

Works with Claude Desktop (claude_desktop_config.json), Cursor (mcp.json), and any MCP client.

Links

• Portal: https://aoto.ai
• API reference: https://api.aoto.ai/docs