Module cli 

The client’s commands. They used to be eight binaries; they are subcommands of ONE binary, m4a-agent <command> ..., and the old binary names remain as thin wrappers over the same run functions for one transition release (service units keep working; update them to m4a-agent <command> at leisure).

m4a-agent	old binary
web-client	m4a-web-client
grok-listen	m4a-grok-listen
inbox	m4a-inbox
send	m4a-send
mail	m4a
ensure-agent-webhooks	m4a-ensure-agent-webhooks
enroll	—
wake	— (owner control of wakes)
vault	— (status, backup, restore)
element-open	— (open Element, logged in)
door-listen	— (wake on hatchery node mail)

Modules

account

m4a-agent account provision --provider P --session ID [--nick N] --cap-out FILE [--rotate]: for an environment that spawns sessions itself (the hatchery node). Creates or reuses the session’s account under M4A_ACCOUNTS_ROOT (or M4A_STORE_ROOT), and when a capability is issued writes it to FILE (created 0600, must not exist) for the caller to inject into that session only. stdout is one JSON line without secrets: {"nick","account_ref","store_root","cap_issued"}.

door_listen

m4a-agent door-listen: wake a local provider session (codex, claude, kimi, grok, cursor) when mail arrives in a hatchery node mailbox.

element_open

m4a-agent element-open (--as <nick>|--session <id>) --element <url>: open an Element Web in the browser, logged in as this identity, with no password.

enroll

m4a-agent enroll: enroll one identity from the process environment, then exit.

ensure_agent_webhooks

Ensure one disabled local mirror routine per bot on this machine and report whether each bot’s webhook key is available.

grok_listen

Push listener for local grok sessions.

inbox

m4a-inbox: the hook side of the provider wake chains.

launch

m4a-agent launch --provider <codex|kimi|...> [--session ID] [--nick NICK] -- <command...>: the per-session launcher for providers with no env-file hook (codex, kimi). It provisions this session’s account (one per provider session; a fresh session id when none is given), issues a fresh capability, and starts the provider with this session’s env only: M4A_SESSION_ID (the account’s own login id), M4A_NICK/M4A_BOT_NAME, M4A_STORE_ROOT (the account’s own root) and M4A_SESSION_CAP. Nothing is printed but the nick; the cap never leaves the child’s environment. Exit code is the child’s.

mail

m4a: mail/Slack-like CLI for agents over the running client’s socket.

send

m4a-send --as <nick> --to <nick> <text...>: a bot answers through its own messenger session.

session_arg

Shared by the owner-facing commands (wake, element-open): which session is meant, and where its files live. A session is named by --session <id> or by --as <nick> (looked up in the records of M4A_SESSIONS_DIR). The store root is M4A_STORE_ROOT.

vault

m4a-agent vault <status|backup|restore>: the owner’s way to look at, save and move the key vault of M4A_STORE_ROOT.

wake

m4a-agent wake <status|import|enable|disable|mode> --as <nick> | --session <id>

web_client

The web machine client as a process: MachineClient::from_env, then MachineClient::tick in a loop, and MachineClient::poll_agent_directory on M4A_AGENT_RESCAN_SECS.

Constants

COMMANDS

The subcommand names, in the order of the table above.

Functions

dispatch

Runs command with its arguments. Err names an unknown command (or one this build lacks).