Command Reference

The CLI supports authentication, API-key management, tool discovery, and direct tool invocation. The older call <tool> form remains an alias for compatibility.

userintuition-mcp <command> [args...]

Subcommand	Purpose
`login [--scopes read,write,...]`	Sign in through browser OAuth with PKCE.
`auth status`	Show whether OAuth and a saved API key are configured.
`auth logout`	Remove locally saved OAuth and API-key credentials.
`api-key create [--name <name>] [--scopes read,write,...] [--spend-cap-usd <amount>]`	Create an organization API key and save it locally.
`api-key list`	List active organization API keys (never raw secrets).
`api-key revoke <id>`	Revoke an organization API key.
`list`	Print every tool name on stdout, one per line.
`describe <tool> [--json]`	Print a tool’s metadata and schemas for humans or automation.
`<tool> [flags]`	Run a tool and write its response to stdout.
`call <tool> [flags]`	Compatibility alias for direct tool invocation.
`help`	Print usage. Also matched by `--help` or `-h`. With no arguments, the binary starts its stdio MCP transport.

Authentication and API keys

userintuition-mcp login
userintuition-mcp auth status
userintuition-mcp api-key create --name "My laptop"
userintuition-mcp api-key list
userintuition-mcp api-key revoke <key_id>
userintuition-mcp auth logout

login uses the hosted MCP OAuth service and opens a temporary callback only on 127.0.0.1. api-key create requires that OAuth login, prints the raw key once, and saves it for subsequent CLI and stdio MCP calls. Login requests read,write by default. To authorize paid hosted tools, run login --scopes read,write,panel:launch,rewards:send and approve the requested access in the browser. You can grant only the paid scope you need. The CLI creates a read-only key by default. For a research agent that also writes, use --scopes read,write. Paid scopes require write and a positive lifetime cap, for example --scopes read,write,panel:launch --spend-cap-usd 100.

`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> [--json]`

userintuition-mcp describe launch_panel

The human-readable form prints:

The tool’s title (one line)
Its full description (the same text MCP clients see)
Every input flag (--name, optional flag suffix, type, enum choices, default, and description)

Use this to discover argument names and types without leaving the terminal. Like list, it makes no backend call. Use --json before or after the tool name for a stable machine-readable object:

userintuition-mcp describe launch_panel --json | jq .inputSchema
userintuition-mcp describe --json launch_panel

The object includes name, title, description, inputSchema, outputSchema, and annotations. Schemas are JSON Schema, so agents and scripts can inspect types, enum values, defaults, and required fields without parsing terminal prose. If the tool name is unknown, prints Unknown tool: <name> to stderr and exits with code 2.

`<tool> [flags]`

userintuition-mcp <tool> [--key value ...]
userintuition-mcp <tool> --input-json '<json>'
userintuition-mcp <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. Tool errors remain JSON on stdout, but return a non-zero status so shells and agents cannot mistake them for success.

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 launch_panel \
  --study_id ast_123 \
  --target 25 \
  --incident_rate 50 \
  --country_code US \
  --dry_run true

--target 25 → number 25
--dry_run true → boolean true
--quality '["Excellent"]' (on list_interviews) → array
--country_code US → string (JSON parse fails, falls back to string)

Flags with no value (e.g. --verbose) are treated as boolean true.

For deeply nested inputs:

screener_questions REPLACES the entire list, and the study may already carry panel and custom questions you can’t see. Read first, then send the complete merged list — existing questions plus your additions:

userintuition-mcp get_study --study_id ast_123

userintuition-mcp create_participants --input-json '{
  "study_id": "ast_123",
  "participants": [
    {"email": "participant@example.com", "silent": true}
  ]
}'

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

Prefix the path with @:

userintuition-mcp create_study --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 launch_panel --study_id x --target notanumber
Invalid input for launch_panel: [
  {
    "code": "invalid_type",
    "expected": "number",
    "received": "string",
    "path": ["target"],
    ...
$ echo $?
2

Exit codes

Code	Meaning
`0`	Tool completed successfully and its response is on stdout.
`2`	CLI usage error — unknown subcommand, unknown tool, or input failed schema validation.
`1`	The tool returned an error, or authentication, network, or an unexpected runtime failure occurred. Tool error JSON remains on stdout.

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 list_interviews --study_id ast_123 --page_size 1 | jq .

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

$ userintuition-mcp get_study --study_id bogus | jq .
{"error": "Study not found"}
$ echo ${PIPESTATUS[0]}
1

Recoverable API failures may include typed fields in addition to the backward-compatible error string:

{
  "error": "Service unavailable",
  "code": "service_unavailable",
  "http_status": 503,
  "request_id": "req_123",
  "retry_after": "30",
  "outcome": "unknown",
  "recovery_action": "retrieve_current_state_before_retry"
}

For consequential writes such as a paid Panel launch, a timeout or server failure means the outcome is unknown. Retrieve the current study state before deciding whether another write is safe; a request ID is diagnostic context, not an idempotency guarantee.

`help`

userintuition-mcp help
userintuition-mcp --help
userintuition-mcp -h

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

Environment

Variable	Required	Description
`USERINTUITION_API_KEY`	No	API key override, prefixed with `ui_sk_`. Takes precedence over saved credentials.
`USERINTUITION_CONFIG_DIR`	No	Override the directory containing `credentials.json`.
`USERINTUITION_OAUTH_ISSUER_URL`	No	Override the hosted OAuth issuer. Defaults to `https://mcp.userintuition.ai`.
`BACKEND_URL`	No	Override the backend API URL. Defaults to `https://api.userintuition.ai`.
`REQUEST_TIMEOUT_MS`	No	Timeout for ordinary API operations. Defaults to 30,000 ms.
`LONG_OPERATION_TIMEOUT_MS`	No	Timeout for long-running operations such as customization and report generation. Defaults to 120,000 ms.

Tool inventory

The CLI exposes 49 direct tool commands. The MCP-only review_study app is available in supported hosts. For full descriptions grouped by capability, browse the MCP tool reference — shared names, schemas, validation, and responses are identical. The quickest way to see what’s available locally:

userintuition-mcp list | less
userintuition-mcp describe <name> --json

Get Started

Reference

Guides

Authentication and API keys

`list`

`describe <tool> [--json]`

`<tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory

​Authentication and API keys

​list

​describe <tool> [--json]

​<tool> [flags]

​Argument forms

​Input validation

​Exit codes

​Output and pipes

​help

​Environment

​Tool inventory

Authentication and API keys

`list`

`describe <tool> [--json]`

`<tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory