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 CLI has four top-level subcommands. Every tool call goes through call; the others help you discover what’s available.
userintuition-mcp <command> [args...]
| Subcommand | Purpose |
|---|
list | Print every tool name on stdout, one per line. |
describe <tool> | Print a tool’s title, description, and input schema. |
call <tool> [flags] | Run a tool and write its response to stdout. |
help | Print usage. Also matched by --help, -h, or no args. |
list
Writes one tool name per line to stdout. Sorted alphabetically. Pipe into other shell tools:
# Count tools
userintuition-mcp list | wc -l
# Grep for a capability
userintuition-mcp list | grep ^create_
list works without an API key.
userintuition-mcp describe ask_humans
- The tool’s title (one line)
- Its full description (the same text MCP clients see)
- Every input flag (
--name, optional flag suffix, and the description attached to each argument)
Use this to discover argument names and types without leaving the terminal. Like list, it makes no backend call.
If the tool name is unknown, prints Unknown tool: <name> to stderr and exits with code 2.
userintuition-mcp call <tool> [--key value ...]
userintuition-mcp call <tool> --input-json '<json>'
userintuition-mcp call <tool> --input-json @<file>
{"error": "…"}) so success and failure parse identically.
You can pass inputs three ways. They behave identically once parsed.
Inline flags
Inline JSON
JSON file
--key value pairs. Values are JSON-parsed when possible, so the right type lands in the schema:userintuition-mcp call ask_humans \
--mode preference \
--text "Which tagline wins?" \
--options '["A","B"]' \
--n 25 \
--dry_run true
--n 25 → number 25--dry_run true → boolean true--options '["A","B"]' → array--text "Which tagline wins?" → string (JSON parse fails, falls back to string)
Flags with no value (e.g. --verbose) are treated as boolean true.For deeply nested inputs:userintuition-mcp call ask_humans --input-json '{
"mode": "preference",
"text": "Which tagline wins?",
"options": ["A","B"],
"screeners": [{
"question": "What is your role?",
"choices": ["PM","Engineer","Other"],
"pass_logic": {"include": ["PM"]}
}],
"dry_run": true
}'
--input-json is provided, all other --flag arguments are ignored. Prefix the path with @:userintuition-mcp call ask_humans --input-json @study.json
$ userintuition-mcp call ask_humans --mode bogus --text x
Invalid input for ask_humans: Invalid enum value. Expected 'preference' | 'claim' | 'message', received 'bogus'
$ echo $?
2
Exit codes
| Code | Meaning |
|---|
0 | Tool ran. The response (which may itself be a {"error": …} payload from the backend) is on stdout. |
2 | CLI usage error — unknown subcommand, unknown tool, or input failed schema validation. |
1 | Unhandled crash (binary failed to start). |
Output and pipes
Tool responses go to stdout. Diagnostic logs (handler errors, stack traces) go to stderr. This separation means you can safely pipe into jq without log noise:
userintuition-mcp call list_studies | jq 'map(select(.status == "fielding")) | length'
$ userintuition-mcp call get_assistant --assistant_id bogus | jq .
{"error": "Assistant not found"}
help
userintuition-mcp help
userintuition-mcp --help
userintuition-mcp -h
userintuition-mcp # no args
Environment
| Variable | Required | Description |
|---|
USERINTUITION_API_KEY | For call only | Your API key, prefixed with ui_sk_. Not needed for list, describe, or help. |
BACKEND_URL | No | Override the backend API URL. Defaults to https://api.userintuition.ai. |
The CLI exposes the same 72 tools as the MCP server. For full descriptions of each tool grouped by capability, browse the MCP tool reference — the schemas are identical, only the invocation differs.
The quickest way to see what’s available locally:
userintuition-mcp list | less
userintuition-mcp describe <name>
