CLI Reference

Install the usertold npm package for:

Study → Interview → Evidence → Finding → delivery

usertold --help --json and the CLI source own command details.

Authenticate and select a Project

npm install -g usertold
usertold auth login
usertold project list --json
usertold project use acme/checkout

Select its canonical org/project ref. New Projects have an active First user interview Study; web signup makes it a draft you publish from the console.

Before editing the starter, ask for a grounded, non-mutating setup proposal:

usertold api POST /api/setup-advice \
  --data '{"request":"We are building a team inbox and need to understand why trial users abandon assignment rules."}' \
  --json

The response includes a research question, participant moment, first Study approach, next steps, and source links.

Reuse or create the Study

Inspect the starter before adding another Study:

usertold study list --json
usertold study validate-script first-user-interview --json

validate-script requires a Study. With no --script, it checks the stored script; --script @study-script.json checks a proposed replacement.

Reuse the starter, or pause it before creating and validating a separate draft:

usertold study update first-user-interview --status paused --json
usertold study create --title "Checkout feedback" --script @study-script.json --json
usertold study validate-script checkout-feedback --json

Its auto-managed Intake follows the Study; direct Intake lifecycle changes are rejected.

Install, activate, and verify

usertold project snippet --json
usertold project verify-widget-installation --url https://example.com/checkout --json
usertold study update checkout-feedback --status active --json
usertold study resolve --path /checkout --language en --json

project snippet --json returns install_once, study_ref_required, and guidance. 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. Review placement before activation; study resolve does not preview a draft.

Inspect the Interview and Evidence

usertold interview list --json
usertold interview status int_123 --json
usertold interview get int_123 --json
usertold interview transcript int_123 --json
usertold evidence list --interview int_123 --json
usertold evidence get evd_123 --json

The Interview is the source record; Evidence is source-linked analysis.

Review and deliver a Finding

Review suggested Findings and linked Evidence. Optional grouping:

usertold findings list --interview int_123 --json
usertold findings get fnd_123 --json
usertold findings create-from-evidence --title "Checkout confirmation is unclear" --evidence evd_123,evd_456 --json

After source review, mark it ready. Delivery is separate:

usertold findings update fnd_123 --status ready --json
usertold findings push fnd_123 --json
usertold findings push-status fnd_123 --json

Omit --provider to use dashboard configuration; provider flags override it.