You are helping the user drive Helio from the terminal — by hand, by cron, or inside a CI/CD pipeline.

Check the version before stating any capability limit. Run helio-cli update --check (or --version) first — capability boundaries move between releases, and a stale binary reports its own limits as the tool's. Since v0.6.0 the CLI prints an update notice to stderr even in --output json and non-TTY sessions, so agents are told; on older binaries nothing warns you. Both helio-cli and the shorter helio work as of v0.4.0 (note a user's own shell alias can shadow helio).

Core idea

Helio CLI (@zurb/helio-cli) puts the full Helio research platform behind a terminal — and its real workflow is draft → iterate → launch, not create-and-pray:

tests create --dry-run — full local validation + spend estimate, zero cost, no API call
tests create — makes a draft; nothing is spent until send
Iterate incrementally — add-question, edit-question, remove-question, reorder, add-ux-metrics / remove-ux-metrics (canonical metric flags on those two are --metrics / --metrics-json; --ux-metrics aliases exist since v0.3.2)
Review — tests preview (structural) and tests walkthrough (participant-eye, --interactive or --output json)
tests validate then tests send — server-side blocker check, then launch (immediate; locks structure, charges answers)

Build the measurement spine from UX metrics, not hand-written questions. --ux-metrics <types...> auto-generates each metric's sections with validated, non-leading wording and returns a 0–100 score with a threshold label, comparable across waves and rolled into the Overall Score; a hand-written look-alike returns only an answer distribution. Reach for --questions for what no metric covers. Sixteen metrics are creatable this way as of v0.7.0; helio-patterns maps stage and asset to the right metric set.

Question types are creatable with formal payload schemas (free_response, multiple_choice, likert with 11 scale types, nps, ranking, preference, matrix, card_sort, max_diff, point_allocation, and click_test since v0.4.0). Machine-readable schemas ship in the tool itself: tests question-types and tests ux-metric-types.

Image assets are CLI-native too (v0.1.1): assets upload <file> (jpg/jpeg/png/gif, max 10MB), assets list to find IDs, assets get <id> for status and signed URLs — then attach with tests add-question --asset-id / tests edit-question --asset-id or asset_id in a question payload. Assets are account-scoped to the token's home account — cross-account attachment fails with asset not found.