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 full flag reference.

Discover your org handle

Before usertold init --org ... or usertold project create <orgHandle> ..., discover your default personal workspace handle with:

usertold auth whoami --json

Read profile.personal_org_handle from the JSON response and pass that value as --org or <orgHandle>. If you belong to multiple orgs, choose the intended org explicitly.

Command groups

Group	What it does
`auth`	Authenticate, switch environments, output token for piping
`init`	Create a project, study, and screener in one non-interactive command
`project`	Manage projects; embed snippet; signal health check
`study`	Create and manage studies; `study guide` outputs the design guide for agents
`screener`	Manage screeners and qualification questions
`session`	List sessions, read transcripts and timelines, trigger reprocessing
`signal`	List, annotate, dismiss, and link signals to tasks
`task`	Create tasks from signals, push to GitHub/Linear, measure signal rate delta
`overview`	Summary view of signals and tasks for a project
`api`	Raw HTTP calls to the REST API using stored credentials
`config`	Manage per-environment configuration
`setup`	Interactive first-time setup
`billing`	Check credit balance and history

Output contract

Every command outputs structured JSON. Schema is stable across releases.

{
  "id": "sig_abc123",
  "type": "struggling_moment",
  "quote": "I tried this flow three times and still cannot find where to change billing.",
  "confidence": 0.91,
  "session_id": "ses_xyz789",
  "timestamp_ms": 142300,
  "url": "/checkout/step-3"
}

Environments

--env accepts production (default), stage, or local. Credentials are stored per environment.