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

# Recipes

> Practical patterns for using the User Intuition CLI in scripts, CI, and day-to-day automation.

Concrete patterns you can copy and adapt. Each one assumes `userintuition-mcp` is on your `PATH` and you have either run `userintuition-mcp login` or set `USERINTUITION_API_KEY`.

***

## Cost gate in CI

Refuse to merge a PR if its planned panel recruit would exceed a budget. `estimate_panel` returns the current cost and heuristic timeline without launching or charging anything:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

estimate=$(userintuition-mcp estimate_panel \
  --study_id "$STUDY_ID" \
  --target 25 \
  --incident_rate 50 \
  --country_code US)

cost_usd=$(jq -r '.estimated_total_cost_usd' <<<"$estimate")

budget_usd=750

if (( $(echo "$cost_usd > $budget_usd" | bc -l) )); then
  echo "::error::Panel would cost \$$cost_usd — exceeds \$$budget_usd cap" >&2
  exit 1
fi

echo "Panel estimate: \$$cost_usd ✓"
```

***

## Panel lifecycle script

Field a panel for an existing Panel study, poll until the target number of interviews lands (or 24 hours elapse), then generate and export the report:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

study_id="$1"
target=25

# 1. Launch (dry-run first if you haven't previewed the cost — see the CI gate above)
userintuition-mcp launch_panel \
  --study_id "$study_id" \
  --target "$target" \
  --incident_rate 50 \
  --country_code US \
  --dry_run false
echo "Panel launched for $study_id"

# 2. Poll — list_interviews returns a total_count envelope, so page_size 1 is
#    enough. Filter to completed interviews: the unfiltered total also counts
#    in-progress and failed sessions.
deadline=$(( $(date +%s) + 86400 ))
while (( $(date +%s) < deadline )); do
  n=$(userintuition-mcp list_interviews \
      --study_id "$study_id" --status completed --page_size 1 \
      | jq -r '.total_count // 0')
  echo "  completed=$n/$target"
  (( n >= target )) && break
  sleep 600
done

# 3. Analyze and export
userintuition-mcp generate_report --study_id "$study_id" > /dev/null
userintuition-mcp get_study_report --study_id "$study_id" \
  > "report-$study_id.json"
echo "Saved: report-$study_id.json"
```

***

## Daily standup digest

A cron job that writes per-study interview counts into a Slack-ready text file every morning. `list_interviews` with `page_size: 1` is the cheap way to count — the envelope's `total_count` covers the whole study, not just the page:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

userintuition-mcp list_studies --page_size 50 \
  | jq -r '.studies[] | "\(.id)\t\(.name)"' \
  | while IFS=$'\t' read -r id name; do
      n=$(userintuition-mcp list_interviews \
          --study_id "$id" --status completed --page_size 1 \
          | jq -r '.total_count // 0')
      echo "  • $name — $n completed interviews"
    done > /tmp/studies-digest.txt

# Then post via your Slack tool of choice
cat /tmp/studies-digest.txt
```

Schedule with cron:

```
0 9 * * 1-5 USERINTUITION_API_KEY=ui_sk_... /usr/local/bin/digest.sh
```

***

## Bulk cleanup of test studies

Delete every study whose name starts with `test_`:

```bash theme={null}
userintuition-mcp list_studies --page_size 100 \
  | jq -r '.studies[] | select(.name | startswith("test_")) | .id' \
  | while read -r id; do
      echo "Deleting $id"
      userintuition-mcp delete_study --study_id "$id"
    done
```

<Warning>
  `delete_study` is destructive. Sanity-check the `jq` filter against `list_studies` output before running the loop.
</Warning>

***

## Review low-quality interviews

List interviews classified as `Poor`, then fetch each full record for review:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

study_id="$1"

userintuition-mcp list_interviews \
  --study_id "$study_id" --quality '["Poor"]' --page_size 100 \
  | jq -r '.interviews[].id' \
  | while read -r id; do
      userintuition-mcp get_interview --interview_id "$id" > "interview-$id.json"
      echo "Saved interview-$id.json"
    done
```

<Warning>
  `delete_interview --interview_id <id>` is available after review, but deletion is destructive. The public API does not expose a reversible hide operation.
</Warning>

***

## Discovering tools by capability

The CLI ships every tool the MCP server has. To find one for a job:

```bash theme={null}
# Anything that creates something
userintuition-mcp list | grep ^create_

# Anything related to interviews
userintuition-mcp list | grep interview

# Inspect a candidate
userintuition-mcp describe create_participants
```

This is often faster than scrolling the [tool reference](/mcp-server/tools/studies).

***

## Patterns to avoid

* **Don't hard-code IDs.** Always derive them from a fresh `list_*` call. IDs from a teammate's account won't resolve.
* **Don't omit `--dry_run true` when iterating on a panel launch.** Real recruiting starts the moment you flip it to `false`.
* **Don't count by page.** Read `list_interviews.total_count` instead of counting one page's `interviews` array.
* **Don't parse stdout in shell with `grep`/`sed`.** Use `jq` — responses are JSON and may add fields between versions.
* **Don't share your `USERINTUITION_API_KEY` in CI logs.** Mask it as a secret. Anyone with the key can spend panel budget on your account.


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