CLI Output

The CLI supports two output modes:

• default human-readable output
• --json for structured output designed for scripts and agents

JSON output (--json)

When you pass --json, the CLI prints a single JSON object to stdout.

Success envelope

{
  "success": true,
  "message": "logged out of agent@example.com",
  "data": { "removed": ["agent@example.com"] }
}

• success — always true
• message (string, optional) — present when there is no data
• data (any, nullable) — command-specific payload

Error envelope

{
  "success": false,
  "error": "imap: ECONNREFUSED",
  "code": "CONNECTION",
  "data": null
}

• success — always false
• error (string) — human-readable description of what went wrong
• code (string) — machine-readable identifier so agents can branch on error type without regex matching
• data — always null on failure

In JSON mode, the CLI suppresses any additional console output so parsers do not break.

Error codes

The code field in error envelopes takes one of these values:

Code	Meaning
AUTH	Authentication failed or not logged in
CONNECTION	Could not reach the server (IMAP or SMTP)
VALIDATION	Invalid input — a flag value or argument is malformed
TIMEOUT	Operation did not complete within the allowed time
NOT_FOUND	The requested resource does not exist (e.g. unknown mailbox, missing message)
POLICY	Server refused the operation by policy (e.g. blocked outbound email, plan-gated consent, or disabled consent settings)
UNKNOWN	Unclassified error — inspect error for details

Agents should branch on code, not on the error string. The error string is for human display and may change between releases.

When the CLI reports a missing mailbox or message directly, it uses a consistent human-readable pattern: {resource} {identifier} not found. Examples include mailbox agent@example.com not found and message 1234 not found.

Exit codes

The process exit code is derived from the error code:

Exit code	Meaning
0	Success
1	Error (VALIDATION, TIMEOUT, NOT_FOUND, POLICY, UNKNOWN)
2	Authentication error (AUTH)
3	Connection error (CONNECTION)

Scripts that only need a pass/fail check can rely on exit codes alone. Scripts that need to distinguish error types should use --json and read the code field.