⌘K

Command Reference

Detailed reference for all AskVerdict CLI commands — flags, options, examples, and exit codes.

9 min read

Complete reference for every askverdict command. Commands are grouped by category.

Global flags

All commands accept these flags. They can be placed before or after the subcommand.

Flag	Description
`--token <token>`	Auth token for this invocation (overrides config and `ASKVERDICT_TOKEN` env var)
`--json`	Output machine-readable JSON instead of formatted text. One JSON object per line for streaming commands.
`--help`	Print help for the command and exit

Set ASKVERDICT_TOKEN or ASKVERDICT_API_URL as environment variables to avoid passing --token on every command. Use askverdict config set-token to persist a token to disk.

Core

`debate`

Start a new AI debate. The debate runs asynchronously and streams live events to your terminal by default.

plaintext

askverdict debate <question> [options]

Arguments:

Argument	Description
`<question>`	The question or topic to debate (required)

Options:

Flag	Default	Description
`-m, --mode <mode>`	`fast`	Debate depth: `fast`, `balanced`, `thorough`, or `analytical`
`-c, --context <text>`	—	Background information passed to all agents
`--agents <count>`	—	Number of AI agents (2–6)
`--rounds <count>`	—	Maximum debate rounds
`--no-stream`	—	Create the debate but exit immediately — prints the ID and stream URL
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict debate "Should we rewrite our API in Go?"

Stream event display: While streaming, debate renders:

Agent thinking indicators
Arguments with agent name and confidence percentage
Web search queries (when --agents search is enabled)
Running cost updates
The final verdict with recommendation and key findings

`list`

List your debates with pagination and status filtering.

plaintext

askverdict list [options]

Options:

Flag	Default	Description
`-n, --limit <n>`	`20`	Number of debates to return
`--page <n>`	`1`	Page number
`--status <status>`	—	Filter: `active`, `completed`, `failed`, `pending`, `paused`
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict list

Table columns: id (truncated), question (truncated to 50 chars), mode, status (colored badge), created.

`view`

View the full details and verdict of a specific debate.

plaintext

askverdict view <id> [options]

Arguments:

Argument	Description
`<id>`	Debate ID (required)

Options:

Flag	Default	Description
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict view dbt_abc123

Output includes: ID, question, status, mode, agent count, round count, creation/completion timestamps, token cost breakdown, and the full verdict (summary, recommendation, confidence, key findings). If the debate is still running, an instruction to use stream is shown instead.

`stream`

Stream live SSE events from a running debate to your terminal.

plaintext

askverdict stream <id> [options]

Arguments:

Argument	Description
`<id>`	Debate ID (required)

Options:

Flag	Default	Description
`--json`	—	Print each SSE event as a JSON line
`--raw`	—	Print raw SSE protocol bytes — useful for piping to another parser
`--token <token>`	—	Override auth token

bash

askverdict stream dbt_abc123

Press Ctrl+C to exit the stream at any time. This disconnects your client but the debate continues server-side. Resume watching with the same command.

`vote`

Cast a vote on an argument claim within a debate.

plaintext

askverdict vote <debateId> <claimId> <agree|disagree|neutral> [options]

Arguments:

Argument	Description
`<debateId>`	Debate ID (required)
`<claimId>`	Claim ID to vote on (required)
`<vote>`	`agree`, `disagree`, or `neutral` — use `neutral` to remove a vote (required)

Options:

Flag	Default	Description
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict vote dbt_abc123 claim_xyz agree

Management

`delete`

Permanently delete a debate. Prompts for confirmation unless --force is passed.

plaintext

askverdict delete <id> [options]

Arguments:

Argument	Description
`<id>`	Debate ID to delete (required)

Options:

Flag	Default	Description
`--force`	—	Skip the `[y/N]` confirmation prompt
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON (no prompt, returns `{ "deleted": true, "id": "..." }`)

bash

askverdict delete dbt_abc123
# Delete debate dbt_abc123? [y/N]

Deletion is permanent and cannot be undone. Completed verdicts and outcome records for the debate are also removed.

`export`

Export a debate to JSON or Markdown format, printing to stdout or writing to a file.

plaintext

askverdict export <id> [options]

Arguments:

Argument	Description
`<id>`	Debate ID (required)

Options:

Flag	Default	Description
`--format <format>`	`json`	Output format: `json` or `md`
`--output <file>`	—	Write to a file instead of stdout
`--token <token>`	—	Override auth token
`--json`	—	Shorthand for `--format json`

bash

askverdict export dbt_abc123 --format md

Markdown output includes: question as heading, status, mode, timestamps, verdict section (recommendation, confidence, rationale, key findings), and argument lists if present.

`polls`

View, create, and vote on polls attached to a debate.

plaintext

askverdict polls <debateId> [subcommand] [options]

Arguments:

Argument	Description
`<debateId>`	Debate ID (required for all subcommands)

Subcommands:

`polls list` (default)

List all polls for a debate with vote tallies.

bash

askverdict polls list dbt_abc123
# or: askverdict polls dbt_abc123

Flag	Description
`--token <token>`	Override auth token
`--json`	Output raw JSON

`polls create`

Create a new poll on a debate you own.

bash

askverdict polls create <debateId> -q "<question>" --options "<A>,<B>,..."

Flag	Required	Description
`-q, --question <question>`	Yes	The poll question
`-o, --options <list>`	Yes	Comma-separated option labels (min 2, max 6)
`--token <token>`	No	Override auth token
`--json`	No	Output raw JSON

`polls vote`

Vote on a specific poll option.

bash

askverdict polls vote <debateId> <pollId> <optionId>

Flag	Description
`--token <token>`	Override auth token
`--json`	Output raw JSON

bash

askverdict polls dbt_abc123

Intelligence

`outcomes`

Track and record real-world outcomes to measure AI verdict accuracy over time.

plaintext

askverdict outcomes <subcommand> [options]

Subcommands:

`outcomes pending`

List debates with completed verdicts that have no outcome recorded yet.

bash

askverdict outcomes pending [--json] [--token <token>]

`outcomes record`

Record the real-world outcome for a debate.

bash

askverdict outcomes record <debateId> <outcome> [options]

Argument / Flag	Required	Description
`<debateId>`	Yes	The debate ID
`<outcome>`	Yes	Text describing what actually happened
`--notes <notes>`	No	Additional context or observations
`--correct`	No	Mark the AI verdict as correct
`--incorrect`	No	Mark the AI verdict as incorrect
`--token <token>`	No	Override auth token
`--json`	No	Output raw JSON

--correct and --incorrect are mutually exclusive. Omit both to record an outcome without judging the verdict.

`outcomes history`

View previously recorded outcomes with optional domain filtering.

bash

askverdict outcomes history [options]

Flag	Default	Description
`-n, --limit <n>`	`20`	Number of records to show
`--domain <domain>`	—	Filter by domain tag
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict outcomes pending

`stats`

Display dashboard statistics, decision accuracy score, and streak information.

plaintext

askverdict stats [options]

Options:

Flag	Default	Description
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON (returns `{ dashboard, score, streak }`)

bash

askverdict stats

Output sections:

Activity: Total debates, debates this week, average cost per debate, mode distribution breakdown
Streak: Current streak (days), longest streak, total debates, milestone progress
Decision Accuracy: Overall accuracy %, total decisions tracked, correct predictions, Brier score, calibration score

`search`

Search your debates by keyword with sorting and filtering.

plaintext

askverdict search <query> [options]

Arguments:

Argument	Description
`<query>`	Search query (required)

Options:

Flag	Default	Description
`--sort <sort>`	`relevance`	Sort order: `relevance`, `date`, or `popularity`
`-n, --limit <n>`	`20`	Number of results
`--page <n>`	`1`	Page number
`--status <status>`	—	Filter by debate status
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON

bash

askverdict search "kubernetes"

Table columns: id (truncated), question (truncated to 50 chars), status (colored badge), confidence (%, colored), created.

Config

`config`

Show and manage persistent CLI configuration stored at ~/.askverdict/config.json.

plaintext

askverdict config [subcommand] [options]

Running askverdict config without a subcommand shows the current configuration and lists available subcommands.

Subcommands:

`config show`

Print current configuration values.

bash

askverdict config show [--json]

Output includes: config file path, API URL, auth token presence.

`config set-token`

Save an auth token or API key to the config file.

bash

askverdict config set-token <token>

The token is stored in ~/.askverdict/config.json and used automatically for all subsequent commands.

`config set-url`

Override the default API base URL.

bash

askverdict config set-url <url>

Useful for self-hosted deployments or staging environments. Must be a valid URL.

`config clear-token`

Remove the saved auth token from config.

bash

askverdict config clear-token

`config reset`

Reset all configuration values back to defaults.

bash

askverdict config reset

bash

askverdict config set-token vrd_your_api_key_here
askverdict config show

Environment variables always take precedence over file config: ASKVERDICT_TOKEN overrides the saved token, and ASKVERDICT_API_URL overrides the saved API URL. The --token flag overrides both.

`whoami`

Show the currently authenticated user's profile and usage stats for the current billing period.

plaintext

askverdict whoami [options]

Options:

Flag	Default	Description
`--token <token>`	—	Override auth token
`--json`	—	Output raw JSON (returns merged profile + usage object)

bash

askverdict whoami

Output includes:

Name, email, plan, bio, location, member since date
Debates this month vs. monthly limit
Credits remaining
Free debate reset date (if on a free tier)

`health`

Check whether the AskVerdict API is reachable and healthy. No authentication required.

plaintext

askverdict health [options]

Options:

Flag	Default	Description
`--json`	—	Output raw JSON

bash

askverdict health
# API Health
#   Status:    ok
#   Service:   askverdict-api
#   Version:   1.4.2
#   API URL:   https://api.askverdict.ai

Status values:

Status	Meaning
`ok`	API is fully operational
`degraded`	API is reachable but some features may be impaired
`down`	API is not responding correctly (exits with code `1`)

Exit codes

Code	Meaning
`0`	Success
`1`	Error (API error, network failure, validation failure)

All error conditions print a descriptive message to stderr before exiting. Use --json to capture structured error output:

bash

askverdict view dbt_missing --json
# { "error": "Not Found: debate dbt_missing does not exist" }

Environment variables

Variable	Description
`ASKVERDICT_TOKEN`	Auth token / API key. Overrides config file.
`ASKVERDICT_API_URL`	API base URL. Overrides config file. Defaults to `https://api.askverdict.ai`.

Set these in your shell profile or CI environment:

bash

export ASKVERDICT_TOKEN="vrd_your_key"
export ASKVERDICT_API_URL="https://api.askverdict.ai"

Was this page helpful?

PreviousScripting & CI/CD NextCLI Workflow Recipes