CLI Reference

Use the usertold CLI when your agent has terminal access. The CLI describes its current command surface and returns machine-readable output.

Fast path: let your agent set it up

Help me install the UserTold CLI with `npm install -g usertold`, complete `usertold auth login`, and inspect my current workspace using JSON output.

If the workspace is empty, ask what product I am researching and what I want to learn. Then use the CLI to create my first project and prepare a draft interview study. Show me the study for review before activating it. After I approve it, activate the study and return the widget embed from `usertold project snippet --json` plus the next step for testing it. If setup already exists, summarize it and help me continue from the current state.

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 turning a review packet into delivery work.
  • Organization management and connected-service setup remain in the dashboard.

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 embed is incomplete: confirm the study and linked intake are active before testing it.

Continue