⌘K

CLI Configuration

Configure the AskVerdict CLI: config file location, all options, environment variables, multiple profiles, and BYOK key setup.

4 min read

The AskVerdict CLI stores its configuration in a JSON file in your home directory. You can also set environment variables to override file config on a per-session or per-command basis.

Config file location

plaintext

~/.askverdict/config.json

The directory and file are created automatically on first use. The exact path depends on your OS:

OS	Path
macOS	`/Users/<you>/.askverdict/config.json`
Linux	`/home/<you>/.askverdict/config.json`
Windows (WSL)	`/home/<you>/.askverdict/config.json`

Check where your config file lives:

bash

askverdict config show --json | jq -r '.configFile'
# /Users/alice/.askverdict/config.json

Config file format

The config file is a plain JSON object. All fields are optional — missing fields fall back to defaults.

json

{
  "apiUrl": "https://api.askverdict.ai",
  "authToken": "vrd_your_api_key_here"
}

Fields:

Field	Type	Default	Description
`apiUrl`	`string`	`https://api.askverdict.ai`	The API base URL all commands connect to
`authToken`	`string`	—	Your API key or auth token. Used for all authenticated commands.

Keep your token secret

The config file is stored in plaintext. Do not commit it to version control. The file permissions are set to your user only (600) on creation.

Managing config with the CLI

Use askverdict config subcommands to read and update config without editing the file directly.

Show current config

bash

askverdict config show

Output:

plaintext

Configuration
  Config file:  /Users/alice/.askverdict/config.json
  API URL:      https://api.askverdict.ai
  Auth token:   [set]

The token value is always masked in display output. Use --json to get the structure (token still masked as "[set]"):

bash

askverdict config show --json
# {
#   "apiUrl": "https://api.askverdict.ai",
#   "authToken": "[set]",
#   "configFile": "/Users/alice/.askverdict/config.json"
# }

Set your API token

bash

askverdict config set-token vrd_your_api_key_here

This writes the token to ~/.askverdict/config.json. All subsequent commands use it automatically.

Get your API key from the Developer Portal.

Set the API URL

bash

askverdict config set-url https://api.askverdict.ai

The URL is validated before saving — an error is shown if it is not a valid URL. The trailing slash is stripped automatically.

Useful when pointing at a staging or self-hosted deployment:

bash

# Staging
askverdict config set-url https://api-staging.askverdict.ai
 
# Local development server
askverdict config set-url http://localhost:3035

Clear the saved token

bash

askverdict config clear-token

Removes the authToken field from the config file. The CLI will require a token via environment variable or --token flag on the next command.

Reset all config to defaults

bash

askverdict config reset

Writes {} to the config file, clearing all saved values and reverting to defaults.

Environment variables

Environment variables always take precedence over values in the config file. Use them for CI/CD, Docker containers, or any context where you do not want to write to disk.

Variable	Description
`ASKVERDICT_TOKEN`	API key or auth token. Overrides `authToken` in config file.
`ASKVERDICT_API_URL`	API base URL. Overrides `apiUrl` in config file. Defaults to `https://api.askverdict.ai`.
`NO_COLOR`	Set to any non-empty value to disable colored terminal output.

Precedence order (highest to lowest)

--token flag on the command line
ASKVERDICT_TOKEN environment variable
authToken in ~/.askverdict/config.json

For the API URL:

ASKVERDICT_API_URL environment variable
apiUrl in ~/.askverdict/config.json
Built-in default (https://api.askverdict.ai)

Setting env vars in your shell profile

bash

# ~/.zshrc or ~/.bashrc
export ASKVERDICT_TOKEN="vrd_your_api_key_here"
export ASKVERDICT_API_URL="https://api.askverdict.ai"

Reload your shell after editing:

bash

source ~/.zshrc   # zsh
source ~/.bashrc  # bash

Per-command token override

Pass --token on any command to use a different token for that invocation only. This does not modify the config file.

bash

# Use a team token for one command
askverdict list --token vrd_team_key_abc
 
# Use a personal token even if env var is set
askverdict whoami --token vrd_personal_key_xyz

Multiple profiles

The CLI does not have built-in profile support, but you can manage multiple configurations using environment variables or by swapping config files with a shell function.

Method 1 — environment variable per session

Keep each workspace/project in a separate terminal session with its own token:

bash

# Terminal A — personal account
export ASKVERDICT_TOKEN="vrd_personal_key"
 
# Terminal B — work account
export ASKVERDICT_TOKEN="vrd_work_key"

Method 2 — config file profiles with a shell function

Store multiple config files and switch between them with a shell alias:

bash

# Create a directory for profiles
mkdir -p ~/.askverdict/profiles
 
# Save your personal config
cat > ~/.askverdict/profiles/personal.json <<'EOF'
{
  "apiUrl": "https://api.askverdict.ai",
  "authToken": "vrd_personal_key_here"
}
EOF
 
# Save your work config
cat > ~/.askverdict/profiles/work.json <<'EOF'
{
  "apiUrl": "https://api.askverdict.ai",
  "authToken": "vrd_work_key_here"
}
EOF
 
# Add a shell function to switch profiles
# Add to ~/.zshrc or ~/.bashrc:
avprofile() {
  local profile="${1:-}"
  if [[ -z "$profile" ]]; then
    echo "Usage: avprofile <profile-name>"
    echo "Available: $(ls ~/.askverdict/profiles/*.json | xargs -I{} basename {} .json | tr '\n' ' ')"
    return 1
  fi
  local src="$HOME/.askverdict/profiles/${profile}.json"
  if [[ ! -f "$src" ]]; then
    echo "Profile not found: $src" >&2
    return 1
  fi
  cp "$src" "$HOME/.askverdict/config.json"
  echo "Switched to profile: $profile"
  askverdict config show
}

bash

# Reload shell, then switch profiles
source ~/.zshrc
 
avprofile personal   # switches to personal config
avprofile work       # switches to work config

Method 3 — direnv per project

Use direnv to set ASKVERDICT_TOKEN automatically when you enter a project directory:

bash

# In your project root
cat > .envrc <<'EOF'
export ASKVERDICT_TOKEN="vrd_project_key_here"
export ASKVERDICT_API_URL="https://api.askverdict.ai"
EOF
 
direnv allow .

The token is loaded automatically when you cd into the project and unloaded when you leave.

If you have a BYOK (Bring Your Own Key) or BYOK Pro plan, you can supply your own AI provider keys for debate requests. Provider keys are never stored server-side — they are passed per-request via the X-Provider-Keys header.

BYOK keys are passed at the SDK/API level, not through the CLI config file. The CLI does not have a built-in --provider-keys flag — use the SDK or REST API directly for BYOK workflows requiring custom provider keys.

For shell automation that needs BYOK keys, use the SDK in a Node.js script:

typescript

import { AskVerdictClient } from "@askverdict/sdk";
 
const client = new AskVerdictClient({
  baseUrl: process.env.ASKVERDICT_API_URL ?? "https://api.askverdict.ai",
  authToken: process.env.ASKVERDICT_TOKEN!,
  providerKeys: {
    anthropic: process.env.ANTHROPIC_API_KEY,
    openai: process.env.OPENAI_API_KEY,
  },
});
 
const { debateId } = await client.createDebate({
  question: "Should we migrate to Edge Functions?",
  mode: "thorough",
});
 
console.log("Created:", debateId);

Config in CI/CD environments

In CI/CD pipelines, use environment variables exclusively — do not create or commit config files.

GitHub Actions

yaml

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: npm install -g @askverdict/cli
 
      - name: Check API health
        env:
          ASKVERDICT_TOKEN: ${{ secrets.ASKVERDICT_API_KEY }}
        run: askverdict health
 
      - name: Run debate
        env:
          ASKVERDICT_TOKEN: ${{ secrets.ASKVERDICT_API_KEY }}
          ASKVERDICT_API_URL: https://api.askverdict.ai
        run: |
          askverdict debate "Should we ship this feature?" \
            --mode fast \
            --no-stream \
            --json | jq '.debateId'

Docker

dockerfile

FROM node:22-alpine
RUN npm install -g @askverdict/cli
 
# Pass token at runtime — never bake keys into images
ENV ASKVERDICT_TOKEN=""
ENV ASKVERDICT_API_URL="https://api.askverdict.ai"
 
ENTRYPOINT ["askverdict"]

bash

docker run --rm \
  -e ASKVERDICT_TOKEN="vrd_your_key" \
  my-askverdict-image \
  list --status completed --json

Troubleshooting

"No auth token found"

The CLI cannot find a token. Fix with any of:

bash

# Option 1 — save to config file
askverdict config set-token vrd_your_key
 
# Option 2 — environment variable
export ASKVERDICT_TOKEN=vrd_your_key
 
# Option 3 — per-command flag
askverdict list --token vrd_your_key

"Not a valid URL" on set-url

The URL must include a scheme (https:// or http://):

bash

# Wrong
askverdict config set-url api.askverdict.ai
 
# Correct
askverdict config set-url https://api.askverdict.ai

Inspect the raw config file

bash

cat ~/.askverdict/config.json

If the file is malformed JSON, the CLI silently falls back to defaults. Reset it:

bash

askverdict config reset

Disable color output

Set NO_COLOR to suppress ANSI codes — useful when piping to log files:

bash

NO_COLOR=1 askverdict list

Was this page helpful?

PreviousCLI Workflow Recipes NextBYOK Setup

CLI Configuration

Config file location

Config file format

Managing config with the CLI

Show current config

Set your API token

Set the API URL

Clear the saved token

Reset all config to defaults

Environment variables

Precedence order (highest to lowest)

Setting env vars in your shell profile

Per-command token override

Multiple profiles

Method 1 — environment variable per session

Method 2 — config file profiles with a shell function

Method 3 — direnv per project

BYOK key configuration

Config in CI/CD environments

GitHub Actions

Docker

Troubleshooting

"No auth token found"

"Not a valid URL" on set-url

Inspect the raw config file

Disable color output

Product

Company

Use Cases

Teams

Content

Developer

Policies

Agreements