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 positive number of 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. A zero or negative value is rejected. 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, confirms the keypair works by fetching a JWT, then writes aimo_agent.sh.

Arguments — Pass the registration token as the single positional argument after register.

On success you get an agent UUID and an aimo_agent.sh helper script. The script exports AIMO_AGENT_UUID, the base64 private key (AIMO_AGENT_PRIVATE_KEY_B64), a randomly generated AIMO_AGENT_PASSPHRASE, plus AIMO_AGENT_HOST and AIMO_AGENT_USE_TLS, and wraps a docker run of the agent image. Inspect it and replace the generated passphrase with your own if you prefer — all connection credentials are encrypted with it.

The script is written to /app/data when that mount exists (inside the agent container), otherwise the current directory; set AIMO_AGENT_REGISTER_OUTPUT_DIR to override. If the file cannot be written, registration still succeeds and the script contents are printed for you to save manually.

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

Manage encrypted connections through the API (under /api/v1/agent/connections). All connection ciphertext is stored server-side against this agent's JWT; the plaintext credentials never leave the agent. show, edit, test, and delete take an optional connection name — pass one to act on it directly, or omit it to pick interactively from the list.

Command	Purpose
add	Prompts for name, database type, and credentials; tests the connection locally; encrypts and POSTs the ciphertext.
list	Lists stored connections (name, type, id).
show	Shows non-secret fields for a connection (sensitive values masked); decrypts internally only as needed.
edit	Updates name, type, or credentials; re-encrypts and PUTs the result.
test	Opens the stored connection and verifies reachability and basic metadata (schemas, table count).
delete	DELETEs a connection after a yes/no 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.