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

> Every subcommand the userintuition-mcp CLI exposes — list, describe, call, help — with full flag semantics and examples.

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`

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

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

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

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

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

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

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

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

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

```bash theme={null}
$ userintuition-mcp call get_assistant --assistant_id bogus | jq .
{"error": "Assistant not found"}
```

***

## `help`

```bash theme={null}
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](/mcp-server/tools/human-signal) — the schemas are identical, only the invocation differs.

The quickest way to see what's available locally:

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