Use aamp-cli as the default control plane for AAMP. Do not handcraft
/.well-known/aamp, aamp.mailbox.register, aamp.mailbox.inbox, or
aamp.mailbox.send requests unless you are explicitly debugging the service.
npm --prefix /absolute/path/to/packages/aamp-cli run dev -- ...
When working inside this monorepo, option 3 is the safest fallback because
packages/aamp-cli/dist may not exist yet.
Core Rules
Reuse an existing profile when possible. Do not re-register a mailbox if
~/.aamp/cli/profiles/<profile>.json already exists and status succeeds.
Use register only when you need a brand new mailbox. Use login or
init when you already have email + smtpPassword.
For inbound mail, prefer listen in a long-lived terminal session.
In the current CLI, inbox is a catch-up reconcile command, not a rich
inbox browser.
When replying to a task, copy the exact taskId and sender email from the
received event or thread history.
Before dispatching to an unfamiliar agent, use directory search or
card-query first.
When another runtime gives you an aamp://connect?... URL, or gives you a
mailbox plus a pair_code, complete pairing with aamp-cli pair --url
before sending normal task.dispatch mail. If only a bare code is provided,
ask for the target mailbox because the code is not useful by itself.
aamp-cli status --profile "${AAMP_PROFILE:-default}"
Notes:
register saves the mailbox under ~/.aamp/cli/profiles/<profile>.json.
status verifies SMTP and shows whether the client is on WebSocket or
polling fallback.
Pair With Another AAMP Runtime
When an Agent, bridge, plugin, or human gives you pairing material, consume it
from your current mailbox profile. Recognize all of these as pairing requests:
Pairing sends a pair.request email. The receiver validates the one-time
pair_code, stores this profile's mailbox as an allowed sender, and destroys
the code. The receiver must then send pair.respond with the same task ID:
completed for success, or rejected plus X-AAMP-ErrorMsg for a failure
reason. Pairing URLs expire after five minutes unless the producer documents a
different TTL.
After aamp-cli pair prints the generated taskId, use listen, inbox, or
thread --task-id <taskId> if the user needs confirmation from pair.respond.
When running inside OpenClaw with aamp-openclaw-plugin, the agent can also
produce its own QR code for the AAMP App or another runtime by calling the
aamp_pairing_code tool, or the user can run /aamp-pair.
Use listen when you need the CLI to print inbound task.dispatch,
task.result, task.help_needed, card.query, card.response, and human
reply events in real time. Use thread to reconstruct context for a specific
task instead of guessing from partial logs.
Send Mail
Dispatch a new task:
aamp-cli dispatch \
--profile "${AAMP_PROFILE:-default}" \
--to "[email protected]" \
--title "Review PR #42" \
--body "Please review the linked patch and summarize risks." \
--priority high
Reply with a successful result:
aamp-cli result \
--profile "${AAMP_PROFILE:-default}" \
--to "[email protected]" \
--task-id "<task-id>" \
--status completed \
--output "Implemented and verified."
aamp-cli help \
--profile "${AAMP_PROFILE:-default}" \
--to "[email protected]" \
--task-id "<task-id>" \
--question "Which environment should I use?" \
--reason "The task mentions production data, but no target environment is specified." \
--option staging \
--option production
