at-email CLI

Portable Go CLI for working with an AgentTeam Email mailbox through the WildDuck API and the safe message-read Control API.

Configuration

The CLI reads AT_EMAIL_* environment variables:

• AT_EMAIL_WILDDUCK_API_BASE_URL (required)
• AT_EMAIL_WILDDUCK_ACCESS_TOKEN (required)
• AT_EMAIL_WILDDUCK_USER_ID (required)
• AT_EMAIL_MAILBOX_ADDRESS (optional; used for status output and reply-all self-recipient filtering)
• AT_EMAIL_CONTROL_API_BASE_URL (required for read)
• AT_EMAIL_MESSAGE_READ_TOKEN (required for read)

The message-read Control API calls intentionally keep the existing upstream JSON-RPC methods and X-Agent-Mail-Message-Read-Token header.

Commands

Every command has scoped help:

at-email <command> --help

at-email status
at-email inbox --unseen
at-email read 7
at-email search invoice --json
at-email send --to [email protected] --subject Hello --body 'Hi there'
at-email reply 7 --body 'Thanks, received.'
at-email version
at-email self-update
at-email skill > at-email-cli/SKILL.md

send accepts an intentionally empty subject with --subject=. Message bodies from --body, --body-file, or stdin must be valid UTF-8.

skill prints the bundled Codex skill markdown to stdout and does not require mailbox runtime configuration. Pipe it to the target skill directory when a runtime has the CLI binary but not the skill file installed.

When installed from npm through @agentteamhq/email, the JavaScript wrapper sets AT_EMAIL_DISTRIBUTION=npm. In that distribution, self-update is disabled because npm owns the installed package version. Update notices still run, but they tell users to update the npm package instead of running self-update.

In text mode, interpreted usage, configuration, and operation errors print to stdout and stderr stays quiet. With --json, successful JSON is written to stdout; failures keep stdout clean and write concise errors to stderr.

Exit codes:

• 0: success
• 1: normal API or operation failure
• 2: usage error
• 69: service unavailable or unreachable before a valid service response
• 70: malformed service response or protocol mismatch
• 78: missing runtime configuration

Local Checks

From this directory:

go test ./...
go mod tidy -diff
mise run fmt:check
mise run mod:check
mise run test
mise run check
mise run image:test

Builds

The canonical build is containerized for reproducibility and multi-architecture image support. Do not use host-local go build for normal workflows.

Container checks and builds:

mise run image:test
mise run image:build
mise run release:check
mise run release:snapshot
mise run release:npm:check

Release assets are built with GoReleaser from .goreleaser.yml. Release builds stamp version, commit, and date into the CLI and attach raw binaries plus checksums.txt to the GitHub Release.

Direct Install

Install the latest GitHub Release binary directly:

curl -fsSL https://raw.githubusercontent.com/agentteamhq/agentteam-email/main/apps/at-email-cli/install.sh | sh

Install a specific release or target directory:

curl -fsSL https://raw.githubusercontent.com/agentteamhq/agentteam-email/main/apps/at-email-cli/install.sh | sh -s -- --version v0.1.0
curl -fsSL https://raw.githubusercontent.com/agentteamhq/agentteam-email/main/apps/at-email-cli/install.sh | sh -s -- --bin-dir PATH

npm Distribution

The release workflow generates npm packages from GoReleaser output under dist/npm/, packs them under dist/npm-packages/, and publishes platform packages before the root package.

The user-facing package is:

npx @agentteamhq/email

It exposes at-email, atemail, agentteam-email, and email command aliases that all run the same CLI wrapper. It depends on platform packages such as @agentteamhq/email-linux-x64-gnu, @agentteamhq/email-linux-x64-musl, @agentteamhq/email-darwin-arm64, and @agentteamhq/email-win32-x64. The Linux glibc and musl packages contain the same static Go binary, but publish separate npm package metadata so package managers can install the exact platform target.