Command Reference

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`

userintuition-mcp 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_

No backend call is made — list works without an API key.

`describe <tool>`

userintuition-mcp describe ask_humans

Prints:

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.

`call <tool> [flags]`

userintuition-mcp call <tool> [--key value ...]
userintuition-mcp call <tool> --input-json '<json>'
userintuition-mcp call <tool> --input-json @<file>

Runs the tool. Output is the tool’s text response written to stdout — typically JSON, the same payload an MCP client would receive. Errors are also JSON-shaped ({"error": "…"}) so success and failure parse identically.

Argument forms

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
}'

When --input-json is provided, all other --flag arguments are ignored.

Prefix the path with @:

userintuition-mcp call ask_humans --input-json @study.json

Best for inputs that live in source control alongside the script that uses them.

Input validation

Inputs are validated against the tool’s Zod schema before any backend call. Missing required fields, wrong types, and enum mismatches all fail fast:

$ 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'

Backend errors round-trip as JSON on stdout, so a pipeline never silently drops them:

$ 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

All four forms print the same usage summary plus the full tool list. Makes no backend call.

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`.

OAuth / Clerk variables are not used in CLI mode — they only apply to the streamable-HTTP MCP transport.

Tool inventory

The CLI exposes the same 71 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>

Get Started

Reference

Guides

`list`

`describe <tool>`

`call <tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory

​list

​describe <tool>

​call <tool> [flags]

​Argument forms

​Input validation

​Exit codes

​Output and pipes

​help

​Environment

​Tool inventory

`list`

`describe <tool>`

`call <tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory