# ⌬ Zero CLI

> *Start from zero. Ship from anywhere.*

A geometric, multi-model AI coding agent for the terminal — concentric, focused, and at home in any shell. Drives Anthropic-protocol-compatible LLM APIs (Anthropic Claude, Zhipu GLM, DeepSeek, Volcengine, Alibaba Qwen, Moonshot, and more) from a single, brand-distinct CLI marked by the `⌬` Zero glyph.

Zero CLI focuses on optimizing the harness layer (context window management, token budgeting, request headers, timeouts, agent runtime) for *third-party* Anthropic-protocol providers. For the official Anthropic Claude models, use Anthropic's official Claude Code — that's where they're tuned best.

## Install

```bash
# Recommended (faster)
bun add -g @paean-ai/zero-cli

# Or via npm
npm install -g @paean-ai/zero-cli
```

### Guides

- **Windows + DeepSeek (English, npm-only):** [`docs/windows-install-zero-cli-deepseek.md`](./docs/windows-install-zero-cli-deepseek.md)
- **简体中文：** [`docs/windows-install-zero-cli-deepseek.zh.md`](./docs/windows-install-zero-cli-deepseek.zh.md)

## Quick Start

Zero supports two backends, picked at the CLI level without opening the TUI:

```bash
# 1) Paean AI (default, recommended)
zero login

# 2) Third-party provider (e.g. z.ai's GLM Coding Plan)
zero provider set zai --api-key <YOUR_GLM_API_KEY>
```

Then start a session:

```bash
zero                         # interactive
zero -p "explain this repo"  # one-shot
```

## Also available as `tide`

Zero CLI installs a second command called **`tide`** that launches the same binary under the **DeepTide** brand:

```bash
tide                         # same as `zero`, branded as DeepTide
tide -p "explain this repo"
```

**DeepTide** is our macOS-native AI coding app; Zero CLI is the cross-platform CLI from the same team that serves Linux, Windows, and non-native-app macOS users. The two products are developed in parallel and evolve independently — Zero CLI focuses on the harness layer for terminal-first workflows; DeepTide focuses on a tuned native macOS experience. The shared interface contract (tool names, slash commands, CLI flags, hook env vars, model aliases) lives in [`docs/tide-spec.md`](./docs/tide-spec.md) so a user's hooks and muscle memory port between the two.

On macOS we recommend the native DeepTide app for the best GUI experience. The `tide` CLI is the cross-platform terminal complement.

## `zero login` — Paean AI account

```bash
zero login           # browser-based OAuth
zero auth status     # check who you're logged in as
zero auth logout
```

## `zero provider` — Third-party API provider

Use this when you want Zero to talk to a non-Paean, Anthropic-protocol-compatible endpoint. Three presets ship out of the box: **z.ai (GLM)**, **Volcengine (Ark)**, **DeepSeek**. All commands are scriptable — no TUI required.

```bash
# Show currently active provider (if any)
zero provider
zero provider status --json

# List available provider presets
zero provider list

# Configure a preset (writes the API key to userSettings + cache)
zero provider set zai        --api-key <YOUR_GLM_API_KEY>
zero provider set volcengine --api-key <YOUR_ARK_API_KEY>
zero provider set deepseek   --api-key <YOUR_DEEPSEEK_API_KEY>

# Optional: override model IDs per tier
zero provider set zai --api-key <KEY> \
  --opus glm-5.1 --sonnet glm-5-turbo --haiku glm-4.5-air

# Switch back to Paean.ai
zero provider clear
```

The API key may also be supplied via the `ZERO_PROVIDER_API_KEY` environment variable (useful in CI). Restart `zero` after changing the provider for the new config to take effect.

### Quick switch between providers (cached credentials)

Once a preset has been configured at least once with `zero provider set`, its credentials are cached in `userSettings.providerCache`. You can then jump between providers without retyping the API key:

```bash
# Re-activate a preset from cache (no --api-key needed)
zero provider use zai
zero provider use volcengine
zero provider use deepseek

# Inspect what's cached (API keys are masked)
zero provider cache list
zero provider cache list --json

# Evict one entry, or wipe the whole cache
zero provider cache clear deepseek
zero provider cache clear
```

`zero provider use <preset>` fails fast if no cache entry exists — you'll be told to run `zero provider set` first.

### Preset defaults

#### z.ai (GLM Coding Plan)

Zero's z.ai preset is for the GLM Coding Plan key used through Z.ai's
Anthropic-compatible Claude Code endpoint:

```text
https://open.bigmodel.cn/api/anthropic
```

Z.ai's GLM Coding Plan docs also list
`https://open.bigmodel.cn/api/coding/paas/v4`; that is the dedicated
OpenAI-compatible Coding API endpoint for tools that speak the OpenAI protocol.
Do not paste that URL into Zero's z.ai preset. If you want to use Z.ai's
ordinary/OpenAI-compatible API path, route it through a BYOK endpoint that
implements the Anthropic Messages API.

| Tier | Model | Context |
|------|-------|---------|
| **pro** (default) | `glm-5.1` | 200K |
| **flash** | `glm-5-turbo` | 200K |
| **lite** | `glm-4.5-air` | 128K |

Get an API key at https://bigmodel.cn/usercenter/proj-mgmt/apikeys.

When the z.ai preset is active, Zero also exposes `/zai-usage` (aliases:
`/glm-usage`, `/coding-plan-usage`) to query GLM Coding Plan model usage, tool
usage, and quota limits. This is built into Zero and follows Z.ai's
`glm-plan-usage` plugin behavior; no separate `@z_ai/coding-helper`
installation is required.

#### Volcengine (火山引擎 Ark Coding Plan)

| Tier | Model | Context |
|------|-------|---------|
| **pro** (default) | `ark-code-latest` | 256K |
| **flash** | `ark-code-latest` | 256K |
| **lite** | `ark-code-latest` | 256K |

Volcengine's coding endpoint serves a single unified model (`ark-code-latest`) across all tiers. Pin to a specific snapshot with `zero provider set volcengine --opus <snapshot-id>` or via the wizard.

Get an API key at https://console.volcengine.com/ark.

#### DeepSeek (Official)

| Tier | Model | Context |
|------|-------|---------|
| **pro** | `deepseek-v4-pro` | 1M |
| **flash** (default) | `deepseek-v4-flash` | 1M |
| **lite** | `deepseek-v4-flash` | 1M |

Two-model lineup: `deepseek-v4-pro` is the flagship, `deepseek-v4-flash` is the daily driver. The default tier is `flash`, mirroring DeepSeek's own pricing-page recommendation.

Get an API key at https://platform.deepseek.com/api_keys.

## Model Tiers

Zero maps three capability tiers to any supported model:

| Preferred alias | Legacy alias | Role |
|---|---|---|
| **pro** | `opus` | Flagship — most capable, highest cost |
| **flash** | `sonnet` | Standard — best for everyday tasks |
| **lite** | `haiku` | Fast / cheap — quick answers, simple tasks |

Switch tiers in-session with either name — both resolve to the same model:

```
/model pro      # or /model opus
/model flash    # or /model sonnet
/model lite     # or /model haiku
```

The `pro` / `flash` / `lite` naming aligns with how third-party Anthropic-protocol providers (DeepSeek, Volcengine, GLM, Gemini, Qwen) tier their own catalogs. Zero CLI's display layer prefers these names; the legacy `opus` / `sonnet` / `haiku` remain accepted inputs for backward compatibility.

`zero provider set` writes the right env vars for you; to override manually:

```bash
export ZERO_CLI_DEFAULT_OPUS_MODEL=glm-5.1        # pro tier
export ZERO_CLI_DEFAULT_SONNET_MODEL=glm-5-turbo  # flash tier
export ZERO_CLI_DEFAULT_HAIKU_MODEL=glm-4.5-air   # lite tier
```

(Env-var infixes still use the canonical internal form `OPUS` / `SONNET` / `HAIKU` so existing scripts and CI keep working.)

Or switch models in-session with `/model`.

### Supported Models

| Model | Provider | Tier |
|-------|----------|------|
| `claude-sonnet-4-6` | Claude (Vertex AI) | Standard |
| `claude-opus-4-5` | Claude (Vertex AI) | Flagship |
| `gemini-3.5-flash` | Google AI Studio | Standard |
| `gemini-3.1-flash-lite` | Google AI Studio | Fast |
| `glm-5.1` | z.ai / ZhipuAI | Flagship |
| `glm-5-turbo` | z.ai / ZhipuAI | Standard |
| `glm-4.5-air` | z.ai / ZhipuAI | Fast |
| `qwen3-max` | Alibaba (DashScope) | Flagship |
| `qwen-plus` | Alibaba (DashScope) | Standard |
| `deepseek-v3.2` | DeepSeek (DashScope) | Standard |
| `deepseek-r1` | DeepSeek (DashScope) | Flagship |
| `kimi-k2.5` | Moonshot (DashScope) | Standard |

## Configuration

Zero stores config in `~/.zero/`. Key environment variables:

| Variable | Description |
|----------|-------------|
| `ZERO_CLI_AUTH_TOKEN` | API key for the configured provider |
| `ZERO_CLI_BASE_URL` | API base URL (defaults to Paean AI) |
| `ZERO_CLI_DEFAULT_OPUS_MODEL` | Model for the "opus" (flagship) tier |
| `ZERO_CLI_DEFAULT_SONNET_MODEL` | Model for the "sonnet" (standard) tier |
| `ZERO_CLI_DEFAULT_HAIKU_MODEL` | Model for the "haiku" (fast) tier |
| `ZERO_PROVIDER_API_KEY` | Fallback key read by `zero provider set` in CI |

Legacy `ANTHROPIC_*` equivalents are still honored but the `ZERO_CLI_*` names are preferred.

## License

MIT
