CLI Reference

Use the usertold npm package when an agent has terminal access. It exposes JSON help and output.

Fast path: let your agent set it up

Install the UserTold CLI with `npm install -g usertold`, complete `usertold auth login`, and inspect my workspace with JSON output. If it is empty, create my first project and prepare a draft interview study. Show me the study for review before activating it. After approval, activate it and return the project widget embed from `usertold project snippet --json`, its guidance, and the next test step. Otherwise summarize the existing setup.

Install and sign in

npm install -g usertold
usertold auth login

Discover the current commands

Use CLI help as the source of truth instead of a copied command catalog:

usertold --help --json
usertold study --help --json
usertold study create --help --json

Every command and subcommand supports human-readable --help. Add --json to help when an agent needs the command manifest without parsing text. Add --json or --format json to operations for structured output.

Working contract

  • The CLI can set a current project so later project-scoped commands stay short.
  • Read source evidence and interview context before moving Work from backlog to ready; export only ready Work.
  • Organization management and connected-service setup remain in the dashboard.

Project widget snippet

Run usertold project snippet [projectRef] to print the Project-owned embed. Install this Project script once across the site. Visibility selects one active Study for the current pathname and widget language; that Study's Invitation defines the launcher. One Project can contain many active Studies.

With --json, the result includes the existing snippet, public_key, and base_url fields plus install_once, study_ref_required, and guidance for automation.

Create/update accept --invitation @file; study get --json returns direct-link recruitment_url. See Widget Integration for placement and revocation.

If setup fails

  • Commands still fail after login: run usertold auth whoami --json and check that every command uses the same environment.
  • A command needs a project: inspect usertold project --help --json, then select or pass the intended project.
  • Output is human-readable: add --json or --format json.
  • The widget selects the wrong Study: run usertold study resolve [projectRef] --path /expected-path --language en --json, then check each active Study's Visibility.

Continue