sendmux-cli

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Sendmux CLI

Use this skill when the terminal is the right Sendmux surface.

## Boundaries

Before CLI setup, connection validation or account commands, start an isolated child process with inherited `QUBRICS_API_KEY`, `SENDMUX_API_KEY`, `QUBRICS_ACCESS_TOKEN`, `SENDMUX_ACCESS_TOKEN`, `QUBRICS_PROFILE`, `SENDMUX_PROFILE`, `QUBRICS_BASE_URL` and `SENDMUX_BASE_URL` cleared. Load only the intended credential from the user's secret store; for profile-based calls, leave direct credentials unset and select the intended `--profile`. Use the authorised endpoint and keep credentials out of arguments and output.

For the documented keyless self-registration flow, complete `agent:register` first, then verify the newly saved profile before content reads, sending or other mutations. For existing credentials or profiles, before content reads or mutations, validate the selected surface's connection and verify its returned identity and any authorised mailbox selection against the intended account and credential. A permission grant alone does not establish the intended identity. If identity differs or cannot be verified, stop and resolve it with the user.

- Do not ask the user to paste API keys.
- For API-key profiles, use `smx_root_` for `management:*` and `smx_mbx_` or scoped `smx_agent_` for `mailbox:*`.
- OAuth profiles require the operation's approved surface, scopes and mailbox access. REST OAuth tokens authenticate HTTP, not SMTP or IMAP.
- Durable agent profiles can read and receive mail while active, but cannot send until an invited owner accepts and approves sending.
- After owner approval, `sending:*` commands with an agent profile automatically exchange and cache a one-hour delegated token.
- Do not run destructive commands without explicit confirmation.
- Use `--json` for agent-readable output.
- Prefer task-specific Sendmux skills when the user needs strategy; use this skill for exact CLI mechanics.

## Install

```bash
npm install -g @sendmux/cli
sendmux --help
```

The package exposes the `sendmux` binary.

## OAuth login and connection checks

For an existing user's account, create a new named OAuth profile with the required scopes:

```bash
sendmux auth:login work --scope mailbox.read --scope email.send
sendmux mailbox:get-connection --profile work --json
```

The CLI opens browser consent and receives the callback on the same computer. `--no-browser` only suppresses automatic browser launch and prints the authorisation URL; the OAuth callback still requires the browser flow on the CLI host, so the flag alone is not a remote-machine authentication transport. The CLI preserves existing profiles.

When explaining the OAuth lifecycle, include all three storage and recovery facts: the CLI stores tokens locally with restricted file permissions; expiring tokens refresh automatically with concurrent refreshes serialised; and an uncertain refresh outcome requires authentication under a new profile name because `auth:login` preserves an occupied profile. To reuse the same name, first complete `sendmux auth:logout work`, then log in again.

Use `sending:get-connection`, `mailbox:get-connection`, or `management:get-connection` for the selected surface. These checks require no mailbox selector and send no email. Use `data.label` for the connection name and `data.team.id` for its stable team identifier.

Run `sendmux auth:logout work` to revoke the connection and remove its profile. A failed revocation keeps the profile for retry; logout also clears an interrupted login reservation.

For externally managed tokens, inject `SENDMUX_ACCESS_TOKEN` through the environment. The CLI does not refresh that token. Supplying it alongside an API key is an error. See [OAuth for REST APIs](https://sendmux.ai/docs/developer-tools/oauth) for grant scopes and refresh rules.

## Agent inbox onboarding

No existing Sendmux account or API key is required:

```bash
sendmux agent:register my-agent \
  --mailbox-local-part my-agent \
  --client-name "My agent" \
  --default \
  --json
```

Add `--owner-email owner@example.com` to invite the owner during registration. Otherwise invite later:

```bash
sendmux agent:invite-owner owner@example.com --profile my-agent --json
```

The CLI persists registration idempotency before the network request, stores the durable credential in the local profile with restricted permissions, never prints it, reloads it from disk, and waits up to 10 minutes for readiness. Rerun registration with the same profile and options to resume safely. Include this storage transition when explaining the onboarding lifecycle: the inbox is capped at 500 MiB before owner approval, and enabling owner-approved sending raises it to at least 5 GiB.

Use the profile for later reads:

```bash
sendmux mailbox:messages:list --profile my-agent --query limit=25 --json
```

Read/receive access has no expiry date while the registration remains active. Sending remains blocked until the owner accepts and approves it. After approval, a command such as `sending:send --profile my-agent` automatically exchanges the durable credential for a one-hour `email.send` token and caches it until near expiry. Full registration revocation removes read access and every delegated token.

Revoking sending does not itself change the current inbox storage allocation.

## Profiles

Create separate profiles for root and mailbox keys.

```bash
SENDMUX_API_KEY="$SENDMUX_ROOT_KEY" sendmux profiles:set default --default --json
SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux profiles:set mailbox --json
SENDMUX_API_KEY="$SENDMUX_MBX_KEY" sendmux profiles:set sending --json
sendmux profiles:list --json
sendmux profiles:show default --json
```

Released CLI 1.7.2 reads `SENDMUX_API_KEY` for `profiles:set`; use it in the isolated child examples above, after populating the source variables through the user's secret store. Candidate SDK `73bedb8` adds `QUBRICS_API_KEY` before that fallback. The direct `--api-key` flag takes precedence in both, but do not expand a secret into that flag because the resulting value is visible in process arguments.

Profile reads mask stored API keys and never reveal agent credentials. `profiles:set` reports `key_kind` as `root` or `mailbox`; `agent:register` creates a discriminated agent profile.

Released CLI 1.7.2 uses `SENDMUX_ACCESS_TOKEN`, `SENDMUX_API_KEY`, `SENDMUX_PROFILE` and `SENDMUX_BASE_URL`; it does not read their `QUBRICS_` equivalents. Explicit flags take precedence, and a token plus an API key is an error. The following QUBRICS-first resolution describes candidate SDK `73bedb8` only: it reads `QUBRICS_ACCESS_TOKEN`, then `SENDMUX_ACCESS_TOKEN`, and rejects a simultaneous API key from `--api-key`, `QUBRICS_API_KEY` or `SENDMUX_API_KEY`. Otherwise:

1. `--api-key`, then `QUBRICS_API_KEY`, then `SENDMUX_API_KEY`.
2. If no direct key is present, `--profile` / `-p`, then `QUBRICS_PROFILE`, then `SENDMUX_PROFILE`, then the configured default profile.
3. Base URL comes from `--base-url`, then `QUBRICS_BASE_URL`, then `SENDMUX_BASE_URL`, then the selected profile.

## Preflight

For API-key authentication, the CLI infers key kind from the prefix before sending a request. OAuth profiles use their approved grants instead of API-key prefix checks.

| Command surface | Required key                                                                      |
| --------------- | --------------------------------------------------------------------------------- |
| `management:*`  | `smx_root_`                                                                       |
| `mailbox:*`     | `smx_mbx_` or scoped `smx_agent_`                                                 |
| `sending:*`     | Send-capable `smx_mbx_` key or owner-approved Sending-resource `smx_agent_` token |

For an agent profile, `mailbox:*` uses the durable read credential. `sending:*` obtains a delegated token only after owner approval. `management:*` rejects agent profiles before the request.

Wrong-key examples fail before network:

```text
Command requires a root API key, but --api-key contains a mailbox API key.
Command requires a sending API key, but --api-key contains a root API key.
```

## Command catalogue

From Sendmux/skills, Apache-2.0.

More from Sendmux/skills