@zcouncil/cli

@zcouncil/cli is the shell client for zcouncil.com. It runs councils directly from a terminal, asks individual members, executes council scripts, lists members/profiles for automation, and serves MCP.

For headless use, run zcouncil run or zcouncil ask.

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.

The CLI is not required to use zcouncil — it exists for terminals, scripts, and agents.

Install

You need Node 22+.

npx -y @zcouncil/cli --help

Create an API token and pass it with --token or ZCOUNCIL_TOKEN. The CLI saves valid tokens per API environment. Agents should let the CLI resolve saved tokens. Do not read, print, copy, or inline token files from ~/.zcouncil yourself.

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

On first run without a token, the CLI prints a link to create one:

No zcouncil token found.

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

After the token is validated, it is saved under ~/.zcouncil/tokens/ with local file permissions and scoped to the environment you used, so future runs can start without --token.

Commands

zcouncil run "Review this plan"     # Run the council
zcouncil run - < prompt.md
zcouncil ask <member> "Critique"    # Ask one member
zcouncil exec script.mjs            # Run a council script
zcouncil members --json             # List members
zcouncil profiles --json            # List profiles
zcouncil mcp                        # Serve MCP over stdio
zcouncil doctor                     # Check token + API reachability
zcouncil update                     # Update the CLI
zcouncil logout                     # Remove the saved token

zcouncil ask accepts short member aliases (claude, gpt, grok, gemini) when unambiguous; run zcouncil members for the full list.

If a newer CLI is published, startup prints an update notice:

zcouncil update

Local Repo Usage

When working inside the zcouncil repo, use the root dev runtime instead of npx, a global zcouncil, or direct package scripts. This keeps CLI auth/config/cache state local to the current worktree and points API calls at the worktree's Portless URLs.

bun run dev:print
bun run dev:run -- node packages/cli/cli.mjs --help
bun run dev:run -- node packages/cli/cli.mjs --version

Use API-backed commands only after the local Worker is running for that worktree:

bun run dev:run -- node packages/cli/cli.mjs members --json

dev:run installs missing workspace dependencies, builds the local SDK/CLI inputs, sets the current worktree's service URLs, and avoids host zcouncil token state.