Agent CLI

The agent CLI ships with the AIMO agent image and Python package. It registers a new agent, runs the long-lived start worker that receives jobs, and manages database connections (encrypted at rest via the AIMO API).

Typical invocation: python -m aimo.agent.cli inside the agent container. With the backend package installed and console scripts enabled, the same entry point is available as aimo-credentials.

Registration tokens and aimo_agent.sh are described in Registration.

Requirements

• HQ host — Set AIMO_AGENT_HOST to your deployment’s API host only (for example your-aimo.example or localhost:8000). Paths (/api/v1, /api/v1/agents/channel) are fixed in the agent code.
• TLS — Set AIMO_AGENT_USE_TLS to true or false. When true, REST uses https and the channel uses wss; when false, http and ws. This must match how the server is reachable from the agent (not inferred from the hostname).
• Authentication — Connection commands use the agent JWT. Set AIMO_AGENT_UUID and AIMO_AGENT_PRIVATE_KEY_B64 for a registered agent. AIMO_AGENT_PASSPHRASE is used when encrypting credentials locally if your setup uses a passphrase.
• Job channel — The start subcommand uses the same AIMO_AGENT_HOST and AIMO_AGENT_USE_TLS for the WebSocket (see above).

See Operations for job behavior once the agent is connected.

start — Run the agent

Starts the agent: connects to the job channel, accepts the job types AIMO dispatches, and runs them against your databases using stored credentials.

Options

• --timeout / -t — Optional seconds. If set, the process exits after that much continuous idle time with no jobs queued or running; the timer resets when a job finishes. Omit to run until stopped.

Typical use — Long-lived container or service; some deployments use a short idle timeout for ephemeral agents.

register — Register a new agent

One-time pairing with AIMO. Generates an Ed25519 keypair, sends the public key with your registration token, and writes aimo_agent.sh (or equivalent) under the mounted data path.

Arguments — Pass the registration token as the positional argument after register (see python -m aimo.agent.cli register --help for the exact signature your build exposes).

On success you get an agent UUID, base64 private key, and aimo_agent.sh exporting AIMO_AGENT_UUID, AIMO_AGENT_PRIVATE_KEY_B64, and a generated AIMO_AGENT_PASSPHRASE (replaceable). Connection credentials are encrypted with that passphrase when you use credential commands.

Connection commands — add, list, show, edit, test, delete

Manage encrypted connections through the API. Commands are interactive unless a connection name is passed where supported.

Command	Purpose
add	Prompts for name, database type, credentials; tests locally; POSTs to the connections API.
list	Lists stored connections.
show	Shows non-secret fields for a connection (sensitive values masked); decrypts internally only as needed.
edit	Updates name, type, or credentials; PUT to the API.
test	Opens the database and verifies reachability and basic metadata.
delete	Removes a connection after confirmation.

Security — Operations require a valid agent JWT. See Security for ciphertext handling and masking.

Quick reference

python -m aimo.agent.cli start [--timeout SECONDS]
python -m aimo.agent.cli register <REGISTRATION_TOKEN>
python -m aimo.agent.cli add
python -m aimo.agent.cli list
python -m aimo.agent.cli show [CONNECTION_NAME]
python -m aimo.agent.cli edit [CONNECTION_NAME]
python -m aimo.agent.cli test [CONNECTION_NAME]
python -m aimo.agent.cli delete [CONNECTION_NAME]

Related

• Architecture — Network layout and trust boundaries.
• Operations — Job types the running agent executes.
• Monitors — Definitions jobs use when querying your data.