twinsim-cli

Run TwinSim market research simulations from your terminal.

$ twinsim simulate --product "Meal kit for busy parents" \
    --question "Would you subscribe?" \
    --market india --personas 20

  Running simulation… (this may take 30–60 seconds)
  ✔ Simulation complete

  ┌──────────────────────┬──────────────┬──────────────────────────────────────────────────────
  │ Persona ID           │ Verdict      │ Response
  ├──────────────────────┼──────────────┼──────────────────────────────────────────────────────
  │ p_in_mum_f35_pro     │ positive     │ This is exactly what I need — the planning is the ha…
  │ p_in_del_m28_mid     │ neutral      │ Sounds useful but I'm not sure I'd pay ₹2000/month…
  └──────────────────────┴──────────────┴──────────────────────────────────────────────────────

  Total: 20 | Positive: 12 (60.0%) | Negative: 5 (25.0%) | Neutral: 3 (15.0%)

Install

npm install -g twinsim-cli

Requires Node.js 18+.

Quick Start

# 1. Get your API key from https://app.twinsim.ai/dashboard/settings
twinsim auth set tsk_live_...

# 2. Check your credit balance
twinsim credits

# 3. Run a simulation
twinsim simulate \
  --product "Your product description" \
  --question "Your research question?" \
  --market india \
  --personas 20

Commands

twinsim auth

Manage your API key.

twinsim auth set <key>    # Store key in ~/.twinsim/config.json
twinsim auth whoami       # Show active key and account details
twinsim auth clear        # Remove stored key

twinsim simulate

Run a market research simulation.

twinsim simulate \
  --product <text>              # Required: product description
  --question <text>             # Required: research question
  --market <slug>               # Required: market (india, us, uk, ...)
  --personas <n>                # Required: 1–50
  [--model <id>]                # LLM model (default: server default)
  [--response-length <length>]  # short | medium | detailed (default: medium)
  [--name <text>]               # Human-readable name for this run
  [--output json]               # Machine-readable JSON output

twinsim config

Persist a custom API base URL so you don't have to pass --api-url on every command.

twinsim config set-url <url>   # Save a custom API URL
twinsim config get-url         # Show the active API URL
twinsim config reset-url       # Reset back to https://app.twinsim.ai

Examples:

# Point at your staging environment permanently
twinsim config set-url https://staging.twinsim.ai

# Point at a local dev server
twinsim config set-url http://localhost:3000

# Confirm what URL is active
twinsim config get-url

# Go back to production
twinsim config reset-url

twinsim credits

Show your credit balance.

twinsim credits
twinsim credits --output json

twinsim simulations

List all simulation runs.

twinsim simulations
twinsim simulations --status completed
twinsim simulations --limit 50 --offset 0
twinsim simulations --output json

twinsim reports

List completed simulation reports.

twinsim reports
twinsim reports --limit 10 --output json

twinsim report <id>

Show full per-persona results for a run.

twinsim report <simulation-id>
twinsim report <simulation-id> --output json

Global Options

These work with every command:

| Flag | Description | |------|-------------| | --api-key <key> | Override stored key for this invocation | | --output json | Machine-readable JSON output | | --api-url <url> | Override API base URL (for staging/self-hosted) |

Configuration

API key resolution (highest → lowest priority)

| Source | How to set | |--------|------------| | --api-key <key> flag | Pass inline on any command | | TWINSIM_API_KEY env var | Export in your shell or CI secrets | | ~/.twinsim/config.json | twinsim auth set <key> |

API URL resolution (highest → lowest priority)

| Source | How to set | |--------|------------| | --api-url <url> flag | Pass inline on any command | | --local flag | Shortcut for http://localhost:3000 | | TWINSIM_API_URL env var | Export in your shell or CI secrets | | twinsim config set-url <url> | Persisted in ~/.twinsim/config.json | | Default | https://app.twinsim.ai |

# One-off: use a different key for a single command
twinsim credits --api-key tsk_live_...

# One-off: hit staging for a single command
twinsim simulate --api-url https://staging.twinsim.ai --product "..." --question "..." --market india --personas 5

# Persistent: store staging URL so all commands use it
twinsim config set-url https://staging.twinsim.ai
twinsim credits                    # hits staging
twinsim config reset-url           # back to production

# Local dev
twinsim simulate --local ...       # targets http://localhost:3000
# or persistently:
twinsim config set-url http://localhost:3000

# CI/CD: key and URL via env vars (no stored config needed)
TWINSIM_API_KEY=tsk_live_... TWINSIM_API_URL=https://staging.twinsim.ai twinsim credits

Config file location: ~/.twinsim/config.json (written with 0600 permissions — owner only).

CI/CD Usage

The --output json flag and predictable exit codes make twinsim composable in scripts and pipelines.

# GitHub Actions example
- name: Run market research simulation
  env:
    TWINSIM_API_KEY: ${{ secrets.TWINSIM_API_KEY }}
  run: |
    result=$(twinsim simulate \
      --product "$PRODUCT_DESC" \
      --question "$RESEARCH_Q" \
      --market us \
      --personas 30 \
      --output json)

    positive_rate=$(echo "$result" | jq '.results | map(select(.verdict=="positive")) | length / (.[] | length)')
    echo "Positive rate: $positive_rate"

Exit codes:

• 0 — success
• 1 — any error (auth failure, API error, validation error, network error)

Upgrade

npm update -g twinsim-cli
twinsim --version

License

MIT