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

• The image for your environment — Each AIMO environment publishes its own agent image (rg.nl-ams.scw.cloud/aimo/agent:latest for production, …/aimo/agent-dev:latest for the dev environment), built together with that environment's server and preset with its host and TLS mode. The web UI's commands and the aimo_agent.sh that register writes name the right one; AIMO_AGENT_IMAGE_REF is that name as the image knows it (shown in upgrade instructions).
• Pinning a build — :latest always points at the build published together with the currently deployed server. Every build is also kept under an immutable tag p<protocol>-<yyyymmdd>-<sha> (for example p1-20260914-5c0f879): the p number is the agent protocol the server requires an exact match on, so only same-p tags are interchangeable, and the date orders them. To run a fixed build, export AIMO_AGENT_IMAGE=<image>:<tag> before ./aimo_agent.sh start — no need to edit the script. When the server later refuses an agent whose protocol it no longer speaks, its message names the build it expects. Each image reports the tag it was built as (AIMO_AGENT_BUILD) to the server at connect; the Build column of the agents table shows it.
• HQ host — AIMO_AGENT_HOST is preset in the image to its environment's API host; set it only to reach AIMO through another address (for example localhost:8000 against a local stack). Host only, no path: /api/v1 and /api/v1/agents/channel are fixed in the agent code.
• TLS — AIMO_AGENT_USE_TLS is preset alongside the host: true means REST over https and the channel over wss, false means http and ws. Override it together with the host; it 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.