npm package: @suiyongsuiqi/sysq-cli
Description: Official agent-first CLI for SYSQ mailbox automation.
Latest version: 0.1.0

# `@suiyongsuiqi/sysq-cli`

Official agent-first CLI for SYSQ mailbox automation.

## Install

Install from npm:

```bash
npm i -g @suiyongsuiqi/sysq-cli
sysq --help
```

Or run without installing globally:

```bash
npx @suiyongsuiqi/sysq-cli --help
```

Build from source:

```bash
git clone https://github.com/suiyongsuiqi/sysq-cli.git
cd sysq-cli
pnpm install
pnpm build
node dist/cli.js --help
```

## Design

This CLI is optimized for agents and scripts first.

- Use explicit commands, not natural-language prompts.
- Use `--json` for stable machine-readable output.
- Use `--yes` for destructive commands in non-interactive flows.
- Treat `stdout` as success output and `stderr` as human-readable error output.

## Get Credentials

If you are using the official hosted SYSQ service:

1. Visit `https://suiyongsuiqi.com/`.
2. Register an account.
3. Sign in to your account.
4. Open `Console -> API Keys`.
5. Create or copy an API key from that page.

For the hosted service, use:

- `SYSQ_BASE_URL=https://suiyongsuiqi.com/api`
- `SYSQ_API_KEY=<your API key from Console -> API Keys>`

## Configuration

The CLI reads configuration from flags or environment variables.

| Option | Environment Variable | Required |
| --- | --- | --- |
| `--base-url` | `SYSQ_BASE_URL` | Yes |
| `--api-key` | `SYSQ_API_KEY` | Yes |
| `--json` | N/A | No |
| `--yes` | N/A | No |

Example:

```bash
export SYSQ_BASE_URL="https://suiyongsuiqi.com/api"
export SYSQ_API_KEY="ak-xxxxxxxx"
```

If you are self-hosting SYSQ, replace `SYSQ_BASE_URL` with your own deployment URL.

The CLI always sends the platform-required header `Tenant-Id: 000000`.
SYSQ backend responses are keyed by `errorKey`, and localization is handled client-side, so the CLI does not expose a locale override.

## Commands

Mailbox asset commands:

- `sysq mailbox list`
- `sysq mailbox remove <mailboxId>`
- `sysq mailbox remove-batch [mailboxIds...] --file <path>`
- `sysq mailbox buy --prefix <prefix> [--suffix <suffix>]`
- `sysq mailbox buy-random [--suffix <suffix>] [--count <n>]`
- `sysq mailbox buy-batch --file <path>`
- `sysq mailbox bind --target-user-id <id> (--mailbox-id <id> | --full-address <address>)`

Mail reading commands:

- `sysq mail unread-summary`
- `sysq mail unread-list`
- `sysq mail messages --mailbox-id <id> [--current <n>] [--size <n>] [--after-id <id>]`
- `sysq mail mark-read --mailbox-id <id> --message-id <id> [...]`

## JSON Contract

Successful `--json` output is wrapped in a stable envelope:

```json
{
  "ok": true,
  "data": {},
  "meta": {
    "command": "sysq mailbox list"
  }
}
```

Failed `--json` output is also normalized:

```json
{
  "ok": false,
  "error": {
    "type": "biz",
    "errorKey": "mail.box.notFound",
    "message": "Mailbox not found"
  }
}
```

Exit codes:

- `0`: success
- `1`: remote or business error
- `2`: usage or configuration error
- `130`: cancelled by user

## Agent Workflows

List purchased mailboxes:

```bash
sysq mailbox list --json
```

Remove one mailbox in agent mode:

```bash
sysq --json --yes mailbox remove 2234567890123456789
```

Buy one mailbox with a custom prefix:

```bash
sysq --json mailbox buy --prefix demo --suffix gmail.com
```

Pull unread mailboxes, then fetch messages:

```bash
sysq --json mail unread-list
sysq --json mail messages --mailbox-id 2234567890123456789 --current 1 --size 20
```

Mark messages as read:

```bash
sysq --json mail mark-read --mailbox-id 2234567890123456789 --message-id 1001 --message-id 1002
```

## Batch File Formats

Batch remove accepts either of these JSON shapes:

```json
["2234567890123456789", "2234567890123456790"]
```

```json
{
  "mailBoxIds": ["2234567890123456789", "2234567890123456790"]
}
```

Batch buy accepts either of these JSON shapes:

```json
[
  { "prefix": "demo1", "suffix": "gmail.com" },
  { "prefix": "demo2", "suffix": "outlook.com" }
]
```

```json
{
  "items": [
    { "prefix": "demo1", "suffix": "gmail.com" },
    { "prefix": "demo2", "suffix": "outlook.com" }
  ]
}
```

## Development

```bash
pnpm install
pnpm build
pnpm typecheck
```