# @zcouncil/cli

`@zcouncil/cli` is the shell client for [zcouncil.com](https://zcouncil.com).
It can run councils directly from a terminal, list members/profiles for scripts,
and optionally run a local bridge so supported council members use local Codex
and Claude Code subscriptions on your computer.

For headless use, run `zcouncil run` or `zcouncil ask`. For local subscription
routing, leave `zcouncil bridge` running while you chat on zcouncil.com.

## Why Use It?

zcouncil is built around comparison: one chat, multiple AI models, clear
disagreements. Agents and scripts can call that council directly from a shell,
without MCP setup. GPT and Claude members can also use the local bridge while
the rest of the council continues through zcouncil's hosted service.

That means:

- your Codex access token stays on your computer
- zcouncil still receives the prompt and GPT response needed to show your chat
- you can close the terminal whenever you want to disconnect the bridge
- if the bridge is not running, zcouncil will only use hosted routes for models that have hosted routing enabled

The CLI is not required to use zcouncil. It is there if you want local
subscriptions to power supported council members.

## Install

You need Node 22+.

```bash
npx -y @zcouncil/cli --help
```

For direct council calls, create an API token and pass it with `--token` or
`ZCOUNCIL_TOKEN`. The CLI saves valid tokens per bridge/API environment.

```bash
npx -y @zcouncil/cli run --token ztk_... "Review this plan"
ZCOUNCIL_TOKEN=ztk_... npx -y @zcouncil/cli members --json
```

For local bridge routing, set up at least one supported local provider:

```bash
# Codex route
npm i -g @openai/codex
codex login

# Claude route
claude setup-token

npx -y @zcouncil/cli bridge
```

On first run, `@zcouncil/cli` prints a link to create a zcouncil API token:

```text
No zcouncil token found.

1. Create one: https://zcouncil.com/chat?action=new-token
2. Paste it here:
```

Create a token, paste it into the terminal, and leave the process running.
After the token is validated, it is saved under `~/.zcouncil/tokens/` with
local file permissions and scoped to the bridge URL you used. Production,
localhost, and preview/debug bridges can each keep their own token, so future
runs against the same bridge can start without `--token`:

```bash
npx -y @zcouncil/cli run "Review this plan"
npx -y @zcouncil/cli bridge
```

Local development keeps a separate token automatically:

```bash
node bridge.mjs --bridge ws://localhost:8787/bridge
```

If a newer CLI is published, startup prints an update notice. To update the globally installed CLI and the installed Pi package:

```bash
zcouncil update
```

To disconnect, close the terminal. To remove the saved zcouncil token for the
selected bridge:

```bash
npx -y @zcouncil/cli logout
npx -y @zcouncil/cli --bridge ws://localhost:8787/bridge logout
```

## Direct Council Commands

Ask the default council:

```bash
npx -y @zcouncil/cli run "Review this architecture and recommend next steps."
```

Read context from stdin:

```bash
npx -y @zcouncil/cli run - < prompt.md
```

Ask one member:

```bash
npx -y @zcouncil/cli ask anthropic_claude_opus_4_7 "Deeply critique this migration plan."
```

List available member IDs and profiles:

```bash
npx -y @zcouncil/cli members --json
npx -y @zcouncil/cli profiles --json
```

Use `--json` with `run` or `ask` when a script needs structured output.
Use `--api <url>` to target a non-production zcouncil API; token storage is scoped to that API URL unless `--bridge` is also passed.

## Local Bridge

Start the local bridge explicitly:

```bash
npx -y @zcouncil/cli@latest bridge start
```

When everything is connected:

```text
Codex: you@gmail.com · pro
Claude Code: you@example.com · max
zcouncil: you@example.com · pro
Connected to zcouncil.
Listening for council requests…
```

Leave that terminal open while you use zcouncil. If the terminal closes, the
local bridge disconnects.

## Provider Fallbacks

By default, the bridge uses your normal Codex and Claude Code logins. If an advanced local profile config exists, the bridge can try multiple local Codex auth files in order and fall back before any visible text is streamed. The normal command stays the same:

```bash
npx -y @zcouncil/cli@latest bridge start
```

## What Moves Where

```text
Your computer                         zcouncil bridge
-------------                         ---------------
@zcouncil/cli  <---- WebSocket ---->   api.zcouncil.com
     |
     | sends requests using local provider CLIs
     v
Codex / Claude Code
```

In plain terms:

- zcouncil sees the chat content needed to provide the service: your prompt, the
  model response, and basic usage information
- zcouncil does not receive your Codex or Claude Code credentials
- the CLI reads Codex auth from `~/.codex/auth.json`, the file managed by the
  official Codex CLI; Claude Code auth stays inside Claude Code
- the zcouncil API token is stored locally under `~/.zcouncil/tokens/`, scoped by bridge URL

For the full data and legal terms, read the zcouncil
[Privacy Policy](https://zcouncil.com/privacy) and
[Terms of Service](https://zcouncil.com/terms).

## What It Does Not Do

- It does not store your chat history locally.
- It does not send analytics, telemetry, or crash reports.
- It does not silently auto-update while the bridge is running; it prints an update notice when one is available, and `zcouncil update` installs the latest CLI and Pi package.
- It does not recover old zcouncil API tokens. If you lose one, create a new one
  from zcouncil settings.

## Your Responsibility

Only use the bridge with accounts and credentials you are allowed to use. You
are responsible for your device, your zcouncil API token, your Codex account,
and complying with the terms and usage policies that apply to the services you
connect.

Do not submit sensitive regulated data, credentials, payment card information,
or anything else prohibited by the zcouncil Terms of Service.

## Inspect Before Running

```bash
npm pack --dry-run @zcouncil/cli
```

## Requirements

- Node 22 or newer
- OpenAI's Codex CLI signed in
- a zcouncil account

## Source Layout

```text
bridge.mjs   # CLI, auth loading, token prompt, WebSocket bridge
package.json # npm package metadata
```

No build step. No bundled dependencies.

## License

MIT. See [LICENSE](./LICENSE).