Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt

Use this file to discover all available pages before exploring further.

The User Intuition CLI ships inside the Node MCP server package (userintuition-mcp on npm, 0.2.6+). The same binary that speaks MCP can also be invoked as a plain shell tool — every tool the server exposes is reachable as a subcommand, no MCP client required. Use the CLI when you want to script User Intuition into a pipeline that doesn’t speak MCP: shell automation, CI jobs, cron, Makefiles, ad-hoc debugging, or piping tool output into jq and other Unix tools.
The CLI is available in the Node build only. The Python build (userintuition-mcp via uvx/pip) does not currently expose a CLI surface — use the REST API for shell scripting in Python-first environments.

​
When to use the CLI vs MCP

Use the CLI when…

You’re writing a shell script, CI step, or cron job. You want to pipe tool output into jq, save it to disk, or feed it into another tool. You’re debugging a tool’s behavior without an MCP client in the loop.

Use the MCP server when…

An AI agent (Claude, ChatGPT, Cursor) should choose the tool and fill in arguments. You want natural-language access — “ask 50 SaaS founders which tagline wins” — rather than typed flags.
Both modes hit the same backend, use the same USERINTUITION_API_KEY, and run the same input validation. Only the transport changes.

​
Install

The CLI is the same binary as the MCP server. Install it once via npm, or run it on demand with npx: 
npx -y userintuition-mcp list
Set your API key in the shell environment: 
export USERINTUITION_API_KEY=ui_sk_your_key_here
If you don’t have a key yet, follow the MCP server setup — the same key works for both.

​
Commands

1

List every tool

userintuition-mcp list
Prints every callable tool name on stdout, one per line — useful for piping into other shell commands.
2

Describe a tool

userintuition-mcp describe ask_humans
Prints the tool’s title, full description, and input schema with --flag names and the descriptions attached to each argument.
3

Call a tool

userintuition-mcp call <tool> [--key value ...]
Calls the tool. Flag values are JSON-parsed when possible (so --n 25 becomes the number 25, --dry_run true becomes the boolean true, and --options '["A","B"]' becomes an array), otherwise treated as strings. Output is the tool’s text response written to stdout.

​
Passing input

For tools with a handful of scalar arguments, --key value is the easiest form. For tools with nested objects or long inputs, pass the whole payload as JSON.

​
Inline flags

userintuition-mcp call ask_humans \
    --mode preference \
    --text "Which tagline resonates more with busy parents?" \
    --options '["Save time, save money", "Less stress, more life"]' \
    --audience "parents aged 25-40" \
    --n 25 \
    --dry_run true

​
JSON payload (inline)

userintuition-mcp call ask_humans --input-json '{
  "mode": "preference",
  "text": "Which tagline resonates more with busy parents?",
  "options": ["Save time, save money", "Less stress, more life"],
  "audience": "parents aged 25-40",
  "dry_run": true
}'

​
JSON payload (from a file)

Prefix the path with @: 
userintuition-mcp call ask_humans --input-json @brief.json
When --input-json is provided, all other --flag arguments are ignored.

​
Output

Every call writes the tool’s text response to stdout — typically JSON, the same payload an MCP client would receive. Errors are also JSON-shaped ({"error": "…"}) so success and failure parse identically. Pipe into jq for scripting: 
# Estimate cost, extract the price field, fail the CI step if too high
cost=$(userintuition-mcp call ask_humans \
    --input-json @brief.json | jq -r '.estimated_cost_usd')

if (( $(echo "$cost > 200" | bc -l) )); then
  echo "Study would cost \$$cost — aborting" >&2
  exit 1
fi
Diagnostic messages (e.g. handler error logs) are written to stderr, so they don’t pollute piped output.

​
Examples

Cost preview in CI 
userintuition-mcp call ask_humans --input-json @study.json | jq '.estimated_cost_usd'
Catch up on running studies from a Makefile 
status:
\t@userintuition-mcp call list_studies --status fielding | jq -r '.[] | "\\(.id) \\(.title)"'
Cancel a study by ID 
userintuition-mcp call cancel_study --study_id std_abc123
Generate a report and save the JSON 
userintuition-mcp call get_results --study_id std_abc123 > results.json

​
Exit codes

CodeMeaning
0Tool ran. The response (which may itself be a {"error": …} from the backend) is on stdout.
2CLI usage error — unknown subcommand, unknown tool name, or input failed schema validation.
1Unhandled crash (binary failed to start).

​
Configuration

The CLI honors the same environment variables as the MCP server’s stdio mode:
VariableRequiredDescription
USERINTUITION_API_KEYYesYour API key, prefixed with ui_sk_.
BACKEND_URLNoOverride the backend API URL. Defaults to https://api.userintuition.ai.
OAuth / Clerk variables are not used in CLI mode — they are only relevant to the streamable-HTTP MCP transport.

​
Next steps

MCP server

Use the same binary as an MCP server so AI agents can call these tools through natural language.

API reference

For Python-first scripting, hit the REST API directly — every CLI tool maps to an underlying endpoint.