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`	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>]`	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>`	Print a tool’s title, description, and input schema.
`<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.

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

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.

`<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. 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 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 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`	Authentication, network, or unexpected runtime failure.

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

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

Tool inventory

The CLI exposes the same 33 tools as the MCP server. For full descriptions grouped by capability, browse the MCP tool reference — names, schemas, validation, and responses are identical. The quickest way to see what’s available locally:

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

Get Started

Reference

Guides

Authentication and API keys

`list`

`describe <tool>`

`<tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory

​Authentication and API keys

​list

​describe <tool>

​<tool> [flags]

​Argument forms

​Input validation

​Exit codes

​Output and pipes

​help

​Environment

​Tool inventory

Authentication and API keys

`list`

`describe <tool>`

`<tool> [flags]`

Argument forms

Input validation

Exit codes

Output and pipes

`help`

Environment

Tool inventory