> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install and configure the Qubrics CLI for management, mailbox, and sending workflows.

Use the `qubrics` CLI when you want terminal access to the same Management, Mailbox, and Sending API surfaces exposed by the SDKs.

> [!NOTE]
>
> OAuth profiles use the scopes approved during [sign-in](https://sendmux.ai/docs/developer-tools/oauth.md).
> API-key Sending commands accept a send-capable `smx_mbx_` key or owner-approved
> agent profile. Mailbox commands accept `smx_mbx_` keys or durable agent
> profiles. Management API-key commands require team-scoped
> `smx_root_` keys.

## Install

Install the Qubrics CLI from npm.

```bash theme={null}
npm install -g @qubrics/cli
```

On Linux, install the CLI from the [Snap Store](https://snapcraft.io/sendmux).

```bash theme={null}
sudo snap install sendmux
```

You can also install the CLI with Homebrew on macOS or Linux.

```bash theme={null}
brew install qubrics/tap/qubrics
```

Snap installs the legacy `sendmux` command. The examples below use `qubrics`, available from npm or Homebrew.

Download a standalone tarball from [GitHub Releases](https://github.com/qubrics/qubrics-sdk/releases) for `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, or `win32-x64`.

Check the installed command.

```bash theme={null}
qubrics --version
qubrics --help
```

The npm package's `sendmux` command remains for one major version and prints a deprecation notice before running `qubrics`.

## Sign in with OAuth

Create a separate profile for a user-approved connection. Repeat `--scope` for each required permission.

```bash theme={null}
qubrics auth:login work --scope mailbox.read --scope email.send
qubrics mailbox:get-connection --profile work --json
```

The command opens your browser for consent and uses a loopback callback on the same computer. Use `--no-browser` to open the printed URL yourself. Existing profiles are not overwritten.

OAuth profiles store tokens in a local file with restricted permissions. The CLI refreshes expiring tokens and serialises concurrent refreshes. An uncertain refresh fails and requires a new login; it does not replay the old refresh token.

```bash theme={null}
qubrics auth:logout work
```

Logout revokes the connection before removing the profile. A failed revocation keeps the profile for retry. Logout can also clear a login interrupted before tokens were saved.

For automation that manages its own tokens, supply `QUBRICS_ACCESS_TOKEN` through the process environment. This token is not refreshed by the CLI. Do not set it alongside an API key.

## Register an agent inbox

An agent can create an `@myagent.mx` inbox without an existing Qubrics account or API key. Registration saves the durable read credential in a private local profile and never prints it.

```bash theme={null}
qubrics agent:register my-agent \
  --mailbox-local-part my-agent \
  --client-name "My agent" \
  --owner-email owner@example.com \
  --default \
  --json
```

The command waits up to 10 minutes for inbox provisioning. Rerun the same command with the same profile to resume without creating another registration.

If you do not know the owner email during registration, invite them later.

```bash theme={null}
qubrics agent:invite-owner owner@example.com --profile my-agent --json
```

The durable profile can read and receive mail without an expiry date unless the complete registration is revoked. After the owner accepts the invitation and approves sending, Sending commands automatically exchange the durable credential for a one-hour `email.send` token.

The self-registered inbox is capped at 500 MiB before approval. Sending approval raises it to at least 5 GiB before the CLI can obtain a delegated sending token. Revoking sending does not itself change the current inbox storage allocation.

## Configure profiles

Save API keys as local CLI profiles so you do not pass a key on every command.

```bash Mailbox profile theme={null}
QUBRICS_API_KEY="$QUBRICS_MAILBOX_KEY" qubrics profiles:set mailbox \
  --default
```

```bash Management profile theme={null}
QUBRICS_API_KEY="$QUBRICS_ROOT_KEY" qubrics profiles:set management
```

The CLI stores profile configuration locally with restricted file permissions. `profiles:list --verbose` and `profiles:show` mask saved keys.

```bash theme={null}
qubrics profiles:list
qubrics profiles:list --verbose
qubrics profiles:show management
```

## Authentication order

An API command first uses `QUBRICS_ACCESS_TOKEN` when set. Supplying an API key at the same time is an error. Otherwise, it resolves credentials in this order:

1. `--api-key`
2. `QUBRICS_API_KEY`
3. `--profile`
4. `QUBRICS_PROFILE`
5. the configured default profile

`profiles:set` accepts `--api-key` as a reference option, but environment input keeps expanded credentials out of child-process arguments.

`--base-url` overrides the API base URL for one command. `QUBRICS_BASE_URL` overrides it for the current shell. A profile can also store a base URL override.

See [Compatibility names](https://sendmux.ai/docs/ai-integrations/mcp#compatibility-names) for retained `SENDMUX_*` settings, webhook headers and MCP tool names.

Before running the API call, the CLI checks that the key or profile matches the command surface. A management command fails early when it receives a mailbox-compatible key, and sending commands fail early when they receive a root key. Mailbox commands accept `smx_mbx_` keys and durable `smx_agent_` profiles. API permissions still apply, so a durable read token cannot send email before owner acceptance and approval.

## Run commands

Commands use colon-separated names.

```bash Sending theme={null}
qubrics sending:send \
  --profile mailbox \
  --body '{"from":{"email":"sender@example.com"},"to":{"email":"recipient@example.com"},"subject":"Hello","text_body":"Sent with the Qubrics CLI"}' \
  --idempotency-key send-cli-001
```

```bash Mailbox theme={null}
qubrics mailbox:messages:list \
  --profile mailbox \
  --query limit=25
```

```bash Management theme={null}
qubrics management:mailboxes:list \
  --profile management \
  --query limit=25
```

Pass request bodies inline with `--body` or from a file with `--body-file`.

```bash theme={null}
qubrics management:create-mailbox \
  --profile management \
  --body-file ./mailbox.json \
  --idempotency-key create-mailbox-001
```

Pass parameters with repeatable `name=value` flags:

* `--path name=value` for path parameters.
* `--query name=value` for query parameters.
* `--header name=value` for supported headers.

Typed values are validated before the request is sent. Unknown parameter names fail with the supported names for that command.

## Output

Without `--json`, API commands print formatted JSON for easy reading. Use `--json` when another process needs machine-readable output from the CLI.

```bash theme={null}
qubrics management:mailboxes:list --profile management --json
```

Text responses return `{ "text": "..." }` with `--json`. Binary responses return base64 data and `byte_length`.

## Request safety flags

Use the dedicated safety flags when the generated command supports the corresponding header:

| Flag | Header |
| - | - |
| `--idempotency-key` | `Idempotency-Key` |
| `--if-match` | `If-Match` |
| `--if-none-match` | `If-None-Match` |

The CLI rejects these flags on commands whose API operation does not accept the matching header.

## Command reference

The CLI command set is generated from the public API surfaces. Run `qubrics --help` to see the current topics, `qubrics <topic> --help` to browse a surface, and `qubrics <command> --help` for the flags supported by one command.

For example:

```bash theme={null}
qubrics sending --help
qubrics mailbox --help
qubrics management --help
qubrics sending:send --help
```

## Next steps

> [card] [SDK overview](https://sendmux.ai/docs/developer-tools/sdks)
>
> Choose package-managed clients for application code.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create scoped credentials before configuring CLI profiles.

> [card] [Mailbox API](https://sendmux.ai/docs/mailbox-api/introduction.md)
>
> Review the API used by mailbox commands.

> [card] [Management API](https://sendmux.ai/docs/api/introduction.md)
>
> Review the API used by management commands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.