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

# Quickstart

> Install the User Intuition CLI and make your first call in under two minutes.

## 1. Install

<Tabs>
  <Tab title="One-shot (npx)">
    No install — runs the latest published version on demand:

    ```bash theme={null}
    npx -y @userintuition-ai/mcp list
    ```

    Slower per-invocation (npm fetches metadata). Best for occasional use.
  </Tab>

  <Tab title="Global">
    ```bash theme={null}
    npm install -g @userintuition-ai/mcp
    userintuition-mcp list
    ```

    Installs once, then `userintuition-mcp` is on your `PATH`. Best for daily use.
  </Tab>

  <Tab title="Project-local">
    ```bash theme={null}
    npm install --save-dev @userintuition-ai/mcp
    npx userintuition-mcp list
    ```

    Pinned to your project's `package.json` and lockfile. Best for CI and reproducible scripts.
  </Tab>
</Tabs>

## 2. Sign in

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

The CLI opens your browser, completes OAuth with PKCE on a temporary loopback callback, and saves the refreshable login in a private local credentials file.

```bash theme={null}
userintuition-mcp auth status
```

<Note>
  Browser OAuth is best for interactive use. Existing `USERINTUITION_API_KEY` environments continue to work and take precedence over saved credentials.
</Note>

## 3. Verify the connection

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

A JSON object with a `studies` array (possibly empty) confirms the CLI, your login, and network egress to `api.userintuition.ai` are all working.

## 4. Create an API key for stdio or CI

After OAuth login, the CLI can create and save an organization-scoped key:

```bash theme={null}
userintuition-mcp api-key create --name "My laptop"
```

The raw `ui_sk_...` key is returned once and saved locally with file mode `0600`. Subsequent CLI calls and local stdio MCP sessions use it automatically. For CI, copy it into the `USERINTUITION_API_KEY` secret in your CI provider rather than copying the local credentials file.

This key has read access. Add `--scopes read,write` when the agent needs to create or change research. Paid actions require their own scopes and a `--spend-cap-usd` value.

## 5. First real call

Estimate the cost of fielding a panel for one of your studies without spending anything:

```bash theme={null}
userintuition-mcp estimate_panel \
  --study_id <your_study_id> \
  --target 25 \
  --incident_rate 50 \
  --country_code US
```

You should see the cost and timeline estimate on stdout — no panel is provisioned and nothing is charged. Review and explicitly approve the complete study plan and estimate before changing `--dry_run` to `false`.

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="/cli/commands">
    Full reference for `list`, `describe`, `call`, and every flag.
  </Card>

  <Card title="Recipes" icon="book" href="/cli/recipes">
    CI cost gates, lifecycle scripts, batch operations.
  </Card>
</CardGroup>


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