Skip to main content
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...]
SubcommandPurpose
listPrint 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.
helpPrint 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.
--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.

​
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

CodeMeaning
0Tool ran. The response (which may itself be a {"error": …} payload from the backend) is on stdout.
2CLI usage error — unknown subcommand, unknown tool, or input failed schema validation.
1Unhandled 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

VariableRequiredDescription
USERINTUITION_API_KEYFor call onlyYour API key, prefixed with ui_sk_. Not needed for list, describe, or help.
BACKEND_URLNoOverride 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 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>