UserTold.ai CLI

Bring human feedback into your agent's decision loop.

UserTold.ai is the research layer for autonomous product systems:

1. design studies
2. run real-time interviews while users are on your website
3. extract signals
4. create evidence-backed tasks
5. measure impact after release

The CLI is the automation-first interface for CI pipelines, agent workflows, and scripted operations.

What interviews look like

UserTold.ai conducts real-time interviews while participants actively use your website. The AI operates in three adaptive modes:

• Observe — Watches silently while the participant navigates, clicks, and thinks aloud. No prompting, no interruption. Captures page changes, interaction events, and spoken thoughts via microphone.
• Speak — Delivers one-way verbal guidance: task instructions, clarifications, a gentle nudge. Stops immediately if the participant starts speaking (barge-in).
• Talk — Full two-way voice conversation via OpenAI Realtime (speech-to-speech). The AI asks follow-up questions, probes emotional moments, and explores unexpected insights in real time.

Each study segment defines a base mode and a mode ceiling. The AI escalates automatically when it detects the participant is stuck — using heuristic checks (silence, confusion keywords, navigation loops) that fire in under a second without an API call. After the intervention it returns to the base mode automatically.

After each session, the platform extracts structured signals — struggling moments, desired outcomes, workarounds, behavioral context — each with a verbatim quote, confidence score, and a link back to the session recording and transcript timestamp. Signals cluster into tasks. Tasks push to GitHub Issues with evidence attached.

Install

npm i -g usertold
usertold --help

Why this CLI

• Scriptable and CI-friendly (--json, --yes)
• Full workflow coverage: projects, studies, sessions, signals, tasks, screeners
• Built for agent orchestration and non-interactive runs
• Works alongside MCP and Web UI

Quick start

# 1) Authenticate
usertold auth login

# 2) Create project
usertold project create acme --name "My Product"

# 3) Design a study (agent-friendly: read the guide first)
usertold study guide
usertold study create acme/my-product --title "Checkout friction study" --type usability --activate

# 4) Review completed sessions
usertold session list acme/my-product --json

# 5) Review extracted signals
usertold signal list acme/my-product --json

# 6) Create and push task
usertold task create-from-signals acme/my-product --title "Fix checkout step confusion" --signals sig_1,sig_2
usertold task push acme/my-product tsk_123

Agent mode

# Discover full command surface (flags, subcommands) in one call
usertold introspect

usertold init --org acme --name "My Product" --json --yes
usertold project status acme/my-product --json
usertold signal bulk-link acme/my-product tsk_123 --signals sig_1,sig_2,sig_3 --json

Errors are JSON on stderr when --json is active:

{"error":{"code":"ARGS_ERROR","message":"Unknown flag(s): --bad-flag","exitCode":2}}

Exit codes: 0 success · 1 error · 2 bad args · 3 auth · 4 not found

Core command groups

• auth
• project
• study
• session
• signal
• task
• screener
• billing
• overview
• config
• setup
• init
• api
• admin
• introspect

Run usertold <group> --help for details.

Requirements

• Node.js 18+

Links

• Docs: https://usertold.ai/docs/getting-started
• CLI reference: https://usertold.ai/docs/cli-reference