Skip to content

CLI.md

Latest commit

 

History

History
180 lines (144 loc) · 7.6 KB

CLI.md

File metadata and controls

180 lines (144 loc) · 7.6 KB
Raw

Unified CLI (zcode-acp)

Every surface of this package is available under one command — zcode-acp — installed alongside the zcode-acp-server bin your editor configures.

Interactive TUI

Bare zcode-acp opens an interactive terminal chat against this same bridge, powered by Martty — a terminal-native ACP client bundled as a dependency (ADR-0020). The in-house Ink REPL it replaced was removed entirely; the CLI surface is Martty + this bridge, on every platform including Windows.

zcode-acp            # chat in this directory
zcode-acp tui        # same thing, explicit

The TUI is a full ACP client: streaming output with markdown rendering, tool rows that expand/collapse on click, a model picker (Ctrl-P), queueing (enter queues, Ctrl-Enter steers the running turn), ! shell escapes, themes (Ctrl-T), and native mouse support (wheel scroll, click-select, drag-copy). /resume lists this project's previous conversations (from the bridge's session/list) and loads one; /new starts fresh. Keys: esc interrupts a turn and clears the draft, Ctrl-C clears then quits, ↑ recalls history. /help inside the TUI lists everything.

Two Martty behaviors worth knowing:

  • Resumed sessions keep their context but not their on-screen history. A fresh TUI boot starts a new session/new, and /resume uses ACP session/resume — which by protocol design carries no message history — so attaching to a session created elsewhere (the editor, the phone app, a previous remote window) starts a visually empty transcript (the status line notes resumed <id> — previous transcript was not replayed). The conversation itself is live: your next prompt runs with the full history in the backend.
  • Sessions persist in the ZCode backend like every other client of this bridge — close the TUI any time; the conversation stays available to your editor and to /resume.

Without a TTY (pipes, Windows editor shims — where the bin name is lost from argv), bare zcode-acp falls back to the stdio server, so editor configs pointing at either bin name keep working. Ask for the TUI explicitly with zcode-acp tui; without a TTY that errors instead of falling back. zcode-acp tui --check runs a headless wiring check (spawn + initialize handshake) — that is what CI smoke-tests.

Quota cards

Check plan usage from the terminal — no editor or running server needed. By default it shows GLM Coding Plan, Opencode Go, and Ollama Cloud (when configured) in one card; pass a provider to focus on one.

GLM credentials are read from ~/.zcode/v2/config.json. Opencode Go credentials come from environment variables (the dashboard needs a browser cookie — see Opencode Go setup below). Ollama Cloud needs an API key — see Ollama Cloud setup below.

# All configured providers (default): GLM + Opencode Go + Ollama Cloud
zcode-acp quota

# Focus on one provider
zcode-acp quota glm        # GLM Coding Plan only
zcode-acp quota go         # Opencode Go only (rolling + weekly + monthly)
zcode-acp quota oc         # Ollama Cloud only (5h + weekly)

# Live monitor: clear the screen and refresh every 30s (default)
zcode-acp quota -w
zcode-acp quota go -w      # watch Opencode Go only

# Refresh at a custom interval (seconds; minimum 10)
zcode-acp quota --watch --interval 60

# Plain monochrome bars (color is the default on a terminal)
zcode-acp quota --plain

By default the CLI renders heat-colored (green→yellow→red) progress bars with the usage numbers overlaid inside the bar, so each line stays short. Pass --plain (or -p) for the classic monochrome █/░ layout. Color is also disabled automatically when stdout is piped or redirected, so captured output stays clean.

The watch mode clears and redraws the card in place, like top/htop. Press Ctrl-C to exit. The 10s minimum exists because the quota API is cached for 10s internally — a shorter interval would just keep returning the stale cached value.

When the package isn't globally installed, run the built file directly:

node dist/cli.js quota -w

Opencode Go setup

Opencode Go has no JSON API for subscription usage — the CLI scrapes the authenticated dashboard at opencode.ai/workspace/<id>/go, so it needs your browser auth cookie. Credentials are read from three sources, merged field-by-field, highest precedence first:

  • Our config file (~/.config/zcode-acp/config.json, quota section — the preferred home): 
    { "quota": {
    "opencodeGoWorkspaceId": "wrk_your_workspace_id",
    "opencodeGoAuthCookie": "Fe26.2**your_cookie_value"
} }
  • Environment variables (override the legacy file below): 
    export OPENCODE_GO_WORKSPACE_ID="wrk_your_workspace_id"
export OPENCODE_GO_AUTH_COOKIE="Fe26.2**your_cookie_value"
  • Legacy config file: ~/.pi/agent/opencode-go.json — same convention as the @beyona/pi-zai-usage Pi extension, kept so existing setups keep working unchanged. 
    { "workspaceId": "wrk_your_workspace_id", "authCookie": "Fe26.2**your_cookie_value" }

How to get the values:

  1. Workspace ID — open https://opencode.ai, navigate to your Go workspace, and copy the wrk_… id from the URL (https://opencode.ai/workspace/<wrk_…>/go).
  2. Auth cookie — open browser DevTools (F12) → Application → Cookies → opencode.ai → copy the value of the cookie named auth (it starts with Fe26.2**).

Without credentials, the default multi-provider mode silently shows GLM only (no error). Running zcode-acp quota go without credentials prints a setup hint.

Ollama Cloud setup

Ollama Cloud exposes an (undocumented) usage endpoint at ollama.com/api/usage that the CLI queries with your API key. Create a key at cloud.ollama.ai → API keys. The key comes from two sources, with the config file taking precedence over the environment variable:

  • Config file (~/.config/zcode-acp/config.json, quota section): 
    { "quota": { "ollamaApiKey": "your_ollama_api_key" } }
  • Environment variable (fallback / one-off override): 
    export OLLAMA_API_KEY="your_ollama_api_key"

The card shows whatever usage windows the account's plan exposes — legacy plans get 5h + Week bars, current credit plans get a Month bar. The server returns fractions only, so reset moments are derived client-side (epoch-aligned 5h buckets, Monday 00:00 UTC weeks, and for monthly the /api/me billing period end or — on new credit plans, which return only a CreatedAt — the next subscription-day anniversary). Without a key, the default mode silently skips the Ollama section; zcode-acp quota oc without a key prints a setup hint.

Hub and server subcommands

zcode-acp hub runs the remote-access hub daemon manually (normally auto-spawned by bridges — see Remote Access). zcode-acp server speaks ACP on stdio — that is what editors invoke through the zcode-acp-server bin; you rarely need it by hand.

Upgrading from 0.11

0.12.0 folds the old standalone bins into the unified CLI (see ADR-0007):

Old (≤0.11) New (0.12)
zcode-acp-server unchanged (kept for editor configs)
zcode-quota [args] zcode-acp quota [args] (same flags)
zcode-acp-hub zcode-acp hub

Editor configs referencing zcode-acp-server keep working unchanged.