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

# Command Reference

> OAuth login, API-key management, discovery, and direct tool invocation from the userintuition-mcp CLI.

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

```bash theme={null}
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`

```bash theme={null}
userintuition-mcp list
```

Writes one tool name per line to stdout. Sorted alphabetically. Pipe into other shell tools:

```bash theme={null}
# 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]`

```bash theme={null}
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:

```bash theme={null}
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]`

```bash theme={null}
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.

<Tabs>
  <Tab title="Inline flags">
    `--key value` pairs. Values are JSON-parsed when possible, so the right type lands in the schema:

    ```bash theme={null}
    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`.
  </Tab>

  <Tab title="Inline JSON">
    For deeply nested inputs:

    <Warning>
      `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:

      ```bash theme={null}
      userintuition-mcp get_study --study_id ast_123
      ```
    </Warning>

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="JSON file">
    Prefix the path with `@`:

    ```bash theme={null}
    userintuition-mcp create_study --input-json @study.json
    ```

    Best for inputs that live in source control alongside the script that uses them.
  </Tab>
</Tabs>

### 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:

```bash theme={null}
$ 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:

```bash theme={null}
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:

```bash theme={null}
$ 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:

```json theme={null}
{
  "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`

```bash theme={null}
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](/mcp-server/tools/studies) — shared names, schemas, validation, and responses are identical.

The quickest way to see what's available locally:

```bash theme={null}
userintuition-mcp list | less
userintuition-mcp describe <name> --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.