CLI Reference
The usertold CLI is the primary authoring interface for agents and power users. Every operation supports --format json for machine-readable output.
Install
npm install -g usertold
usertold auth login
Run usertold --help or usertold <command> --help for the human-readable flag reference. Add --json to any help command for structured discovery, for example usertold --help --json.
Project defaults
The CLI defaults to your personal workspace for project discovery and creation:
usertold project list
usertold project create --name "Demo"
usertold init --name "My Product" --format json --yes
Set a current project once, then omit <projectRef> from project-scoped commands:
usertold project use acme/checkout
usertold work list
usertold interview list
usertold config set --key openai_api_key --value sk-...
If you belong to multiple orgs, pass --org <orgHandle> or an explicit <orgHandle> to target a different workspace.
Command groups
| Group | What it does |
|---|---|
auth | login, logout, whoami, token — authenticate and inspect the current session |
init | Bootstrap project + study + intake — interactive on TTY, non-interactive with --yes |
project | list, create, get, update, delete, snippet (embed code), status (evidence-health summary), overview (dashboard summary) |
study | list, create, get, update, delete, export, import, reprocess, validate-script, guide (design guide for agents) |
intake | list, create, get, update, delete, set-questions, list-responses, get-response, qualify-response, disqualify-response |
interview | list, create, upload-video, import-transcript, forensics, end, get, status, events, update, delete, transcript, timeline, enriched-timeline, media, audio, screen, reprocess, retry-media-merge, watch |
evidence | list, get, annotate, dismiss, undismiss, link, unlink, delete, bulk-link |
work | list, get, create, create-from-evidence, update, delete, push, push-status (provider state — issue URL, sync status) |
api | Raw HTTP calls to the REST API using stored credentials |
config | set, get, list, delete — per-project / per-env configuration (openai_api_key, etc.) |
billing | status (credit balance), history (recent billing events) |
completions | Emit shell completion scripts for bash / zsh / fish |
extract | Run evidence extraction on local transcript/event files using your OpenAI key — offline alternative to server-side interview reprocess |
admin | Administrative operations (admin embed-backfill, admin credits grant); requires elevated auth |
Every command and subcommand accepts --help for the full flag reference. Use --help --json when an agent or script needs the command manifest without parsing text.
Everyday Workflows
Project-scoped commands accept <projectRef> as orgHandle/projectHandle or a project ID. Set a current project with usertold project use <projectRef> when you want shorter commands.
Create the first research loop
Use init when you want a project, study, intake, and embed snippet in one non-interactive step:
usertold init --name "Acme Checkout" --format json --yes
usertold project use <orgHandle>/<projectHandle>
usertold project snippet --json
If you want to build the pieces yourself:
usertold project create --name "Acme Checkout" --json
usertold project use <orgHandle>/<projectHandle>
usertold intake create --title "Checkout testers" --questions @intake-questions.json --json
usertold study create --title "Checkout friction" --script @study-script.json --intake-id <intakeRef> --activate --json
usertold project snippet --json
Success means the study and linked intake are active, and the snippet contains the public project key for the widget embed.
Design and validate a study
Create a study, then export, edit, validate, and import replacement scripts as files:
usertold study guide > study-design.md
usertold study create --title "Checkout usability" --script @study-script.json --json
usertold study export <studyRef> > current-script.json
usertold study validate-script <studyRef> --script @current-script.json --json
usertold study import <studyRef> --script @current-script.json --json
Use Studies and Study Runtime for script shape and segment behavior.
Import or upload an interview
Use transcript import when you already have text. Use upload when you have audio and optional playback video:
usertold interview import-transcript ./transcript.txt --study <studyRef> --wait --json
usertold interview upload-video --audio ./interview.ogg --video ./screen.mp4 --study <studyRef> --json
usertold interview watch <interviewId> --evidence --json
For large recordings, prepare a small audio file for transcription and an optional visible video for playback.
Inspect source context
Review the source before turning evidence into work:
usertold interview get <interviewId> --json
usertold interview transcript <interviewId> --json
usertold interview timeline <interviewId> --json
usertold interview enriched-timeline <interviewId> --json
usertold evidence list --interview <interviewId> --json
usertold evidence get <evidenceId> --json
usertold evidence case-file <evidenceId> --json
Evidence is useful only when the quote, page context, and surrounding actions support the interpretation.
Curate evidence
Use evidence commands to keep review packets grounded:
usertold evidence list --type struggling_moment --min-confidence 0.7 --json
usertold evidence coverage-gaps --json
usertold evidence annotate <evidenceId> --text "Verified against checkout recording" --json
usertold evidence dismiss <evidenceId> --reason "Duplicate of sig_..." --json
usertold evidence undismiss <evidenceId> --json
Link evidence when a work item already represents the same user problem:
usertold evidence link <evidenceId> <workId> --json
usertold evidence bulk-link <workId> --evidence sig_1,sig_2,sig_3 --json
Create and verify work
create-from-evidence drafts the work item; you still need to verify the evidence before marking it ready.
usertold work create-from-evidence --title "Clarify checkout payment failure" --evidence sig_1,sig_2 --json
usertold work get <workId> --json
usertold work update <workId> --status ready --json
Before moving work to ready, inspect the linked evidence, transcript or playback context, grouping fit, and current product area.
Push verified work
Push only after you have checked the source evidence and current product context:
usertold work push <workId> --provider linear --json
usertold work push-status <workId> --json
Use --provider github, --provider linear, or --provider auto depending on project settings.
Recover processing
Use status and reprocess commands when an interview or study looks stuck:
usertold interview status <interviewId> --json
usertold interview watch <interviewId> --timeout 600 --interval 5 --evidence
usertold interview reprocess <interviewId> --wait --json
usertold interview retry-media-merge <interviewId> --json
usertold study reprocess <studyRef> --wait --json
If reprocessing still produces no evidence, inspect the transcript, study context, and Methodology before assuming the extractor is wrong.
Export project data
Use export commands when another tool needs project data for analysis, migration, or archive:
usertold export start --wait --output usertold-export.json
usertold study export <studyRef> > study-script.json
Run usertold export --help for the exact export job commands available in your installed CLI.
Output contract
Every command outputs structured JSON, documented in the OpenAPI spec at /api/openapi.
{
"id": "sig_abc123",
"signal_type": "struggling_moment",
"quote": "I tried this flow three times and still cannot find where to change billing.",
"confidence": 0.91,
"intensity": 0.8,
"session_id": "ses_xyz789",
"timestamp_ms": 142300,
"page_url": "/checkout/step-3"
}
Environments
--env accepts production (default), stage, or local. Credentials are stored per environment.
Web parity
This table maps the main dashboard flows to their CLI equivalents. Project-scoped commands accept <projectRef> explicitly, or use the current project set by usertold project use <projectRef>. Rows marked Web-only do not have a CLI verb yet.
| Dashboard action | CLI verb |
|---|---|
| Sign in (Google OAuth) | usertold auth login |
| Sign out | usertold auth logout |
| Create project | usertold project create --name "..." |
| List projects | usertold project list or usertold project list <orgHandle> |
| Select current project | usertold project use <projectRef> |
| Update project (name, repo, branch) | usertold project update [projectRef] [...] |
| Delete project | usertold project delete <projectRef> |
| Get embed snippet | usertold project snippet [projectRef] |
| Project readiness check | usertold project status [projectRef] |
| Project dashboard | usertold project overview [projectRef] |
| Use your OpenAI key (BYOK) | usertold config set [projectRef] --key openai_api_key --value sk-... |
| Install GitHub App | Web-only today: install from project settings |
| Create study | usertold study create <projectRef> --title "..." |
| Activate / pause study | usertold study update <projectRef> <studyRef> --status active|paused |
| Edit study script | usertold study export … > script.json → edit → usertold study import … --script @script.json |
| Re-run evidence extraction on a study | usertold study reprocess <projectRef> <studyRef> --wait |
| Validate study script | usertold study validate-script <projectRef> <studyRef> |
| Create intake | usertold intake create <projectRef> --title "..." |
| Edit intake settings | usertold intake update <projectRef> <intakeRef> [--title "..." | --description "..." | ...] |
| Activate / pause / close intake | usertold intake update <projectRef> <intakeRef> --status active|paused|closed |
| Delete intake | usertold intake delete <projectRef> <intakeRef> |
| Set intake questions | usertold intake set-questions <projectRef> <intakeRef> --questions @q.json |
| List intake responses | usertold intake list-responses <projectRef> <intakeRef> |
| Qualify response | usertold intake qualify-response <projectRef> <intakeRef> <responseId> [--reason "..."] |
| Disqualify response | usertold intake disqualify-response <projectRef> <intakeRef> <responseId> --reason "..." |
| List interviews | usertold interview list <projectRef> |
| Upload a custom recording for processing | usertold interview upload-video <projectRef> --audio ./interview.ogg --video ./visible.mp4 --json |
| Import a transcript and run extraction | usertold interview import-transcript <projectRef> ./transcript.txt --wait |
| Run extraction forensics on an imported transcript | usertold interview forensics <projectRef> <interviewId> --key sk-... --json |
| Watch an interview process | usertold interview watch <projectRef> <interviewId> |
| View transcript / timeline | usertold interview transcript|timeline|enriched-timeline <projectRef> <interviewId> |
| Download audio / screen recording | usertold interview audio|screen <projectRef> <interviewId> --output file.webm |
| Reprocess an interview | usertold interview reprocess <projectRef> <interviewId> --wait |
| Retry stuck media merge | usertold interview retry-media-merge <projectRef> <interviewId> |
| List evidence | usertold evidence list <projectRef> [--type ...] |
| Dismiss evidence | usertold evidence dismiss <projectRef> <evidenceId> --reason "..." |
| Undismiss evidence | usertold evidence undismiss <projectRef> <evidenceId> |
| Annotate evidence | usertold evidence annotate <projectRef> <evidenceId> --text "..." |
| Link evidence to work item | usertold evidence link <projectRef> <evidenceId> <workId> |
| Create work item from evidence | usertold work create-from-evidence <projectRef> --title "..." --evidence sig_1,sig_2 |
| Update work item status / priority | usertold work update <projectRef> <workId> [...] |
| Push work item to GitHub / Linear | usertold work push <projectRef> <workId> [--provider github|linear|auto] |
| Inspect provider state of pushed work item | usertold work push-status <projectRef> <workId> |
| View credit balance / billing history | usertold billing status|history |
Web-only actions today: org membership management, Linear OAuth connect (CLI uses auth login's session). These will surface as CLI verbs as the integration surface stabilizes.
Troubleshooting
| Symptom | Next action |
|---|---|
| Login succeeded in the browser but commands still fail | Run usertold auth whoami --json and confirm the same --env you use for project commands. |
A project-scoped command asks for <projectRef> | Run usertold project use <orgHandle>/<projectHandle> or pass the project reference explicitly. |
| The output is human text instead of JSON | Add --json or --format json, depending on the command. Help discovery supports --help --json. |
| You have a project snippet but no intake handle | Run usertold intake list --json, confirm an active intake, then link it to the study with usertold study update <studyRef> --intake-id <intakeRef>. |
| An uploaded or imported interview is still processing | Run usertold interview status <interviewId> --json, then usertold interview watch <interviewId> --evidence. |
| No evidence appears | Inspect interview transcript, interview timeline, and the study script. Reprocess only after confirming the source record has enough participant language or behavior. |
work push fails | Confirm the project tracker is connected in the dashboard, the work item is verified, and usertold work push-status <workId> --json does not already show an active provider item. |
| Commands hit the wrong environment | Pass --env production, --env stage, or --env local and check usertold project current --env <env>. |
See also: MCP Integration · Quickstart · API Reference