CLI

Ask questions, manage audiences, and explore projects — all from your terminal.

The OriginalVoices CLI (ov) gives you direct access to Digital Twins without writing any integration code.

Installation

npm install -g @originalvoices/cli

Requires Node.js 18+.

Authentication

Get your API key from platform.originalvoices.ai, then log in:

ov auth login

You'll be prompted to enter your key. Alternatively, pass it directly:

ov auth login --key ov_live_your_key_here

The key is stored in ~/.ov/config.json with restricted file permissions.

You can also set the OV_API_KEY environment variable — it takes priority over the config file:

export OV_API_KEY=ov_live_your_key_here

Check auth status

ov auth status

Log out

ov auth logout

Asking Questions

The ov ask command supports three modes: open-ended questions, multiple choice, and project-scoped questions.

Open-ended (default)

ov ask "What frustrates you about project management tools?" \
  --audience "US, 25-45, tech professionals"

Ask multiple questions at once:

ov ask "What do you look for in a running shoe?" "How much do you typically spend?" \
  --audience "UK, 18-30, fitness enthusiasts"

Sample size

Control how many Digital Twins respond with --sample-size:

ov ask "What matters most when choosing a bank?" \
  --audience "US, 30-50, homeowners" \
  --sample-size high

Options: low, medium (default), high, very_high

Multiple choice

ov ask "Which feature matters most?" \
  --audience "US, 25-45, tech professionals" \
  --type choices \
  --choices "Price,Ease of use,Integrations,Support"

Allow multiple selections:

ov ask "Which features do you use?" \
  --audience "US, 25-45, tech professionals" \
  --type choices \
  --choices "Dashboard,Reports,API,Webhooks" \
  --multiple-choice

Project mode

Query Digital Twins within a specific project:

ov ask "How often do you use navigation apps?" \
  --project your-project-id

Filter to a subset of respondents:

ov ask "What would make you switch apps?" \
  --project your-project-id \
  --filter "people who use navigation apps daily"

Managing Audiences

Save audience definitions to reuse across questions.

List audiences

ov audiences list

Create an audience

ov audiences create \
  --title "US Tech Professionals" \
  --prompt "US, 25-45, tech professionals working remotely"

Use a saved audience

ov ask "What's your biggest productivity blocker?" \
  --audience-id your-audience-id

Update an audience

ov audiences update your-audience-id --title "US Remote Tech Workers"

Delete an audience

ov audiences delete your-audience-id

Exploring Projects

ov projects list

JSON Output

Add --json to any command for machine-readable output. Useful for scripting and piping with jq:

ov ask "What matters most when choosing a bank?" \
  --audience "US, 30-50, homeowners" \
  --json | jq '.answers'

ov audiences list --json

Command Reference

Command	Description
ov auth login	Authenticate with your API key
ov auth status	Show current auth status
ov auth logout	Clear stored credentials
ov ask <questions...>	Ask questions to Digital Twins
ov audiences list	List saved audiences
ov audiences create	Create a saved audience
ov audiences update <id>	Update an audience title
ov audiences delete <id>	Delete an audience
ov projects list	List available projects

Next Steps

• Question Guidelines — what types of questions work best
• API Quickstart — integrate via the Node.js SDK
• API Reference — full endpoint documentation