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, bulk-delete |
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.
Output contract
Every command outputs structured JSON. Schema is stable across releases.
{
"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] |
| Configure BYOK OpenAI key | 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.
See also: MCP Integration · Quickstart · API Reference