> ## 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_API_KEY` is set in your environment and `userintuition-mcp` is on your `PATH`.

***

## Cost gate in CI

Refuse to merge a PR if its planned Panel study would exceed a budget. Drop this into a workflow step that runs `ask_humans` with `dry_run: true`:

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

cost=$(userintuition-mcp call ask_humans --input-json @study-brief.json \
       | jq -r '.estimated_cost_usd')

budget=200
if (( $(echo "$cost > $budget" | bc -l) )); then
  echo "::error::Study would cost \$$cost — exceeds \$$budget cap" >&2
  exit 1
fi

echo "Study cost: \$$cost (under \$$budget cap) ✓"
```

***

## Study lifecycle script

Create a small study, poll until it completes (or 30 minutes elapse), then export the report:

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

# 1. Launch
study_id=$(userintuition-mcp call ask_humans \
  --mode preference \
  --text "Which onboarding email wins?" \
  --options '["Variant A","Variant B"]' \
  --n 30 \
  --dry_run false | jq -r .study_id)

echo "Study launched: $study_id"

# 2. Poll
deadline=$(( $(date +%s) + 1800 ))
while (( $(date +%s) < deadline )); do
  status=$(userintuition-mcp call get_results --study_id "$study_id" | jq -r .status)
  echo "  status=$status"
  case "$status" in
    complete|partial) break ;;
    failed|cancelled) echo "Study ended in $status" >&2; exit 1 ;;
  esac
  sleep 60
done

# 3. Export
userintuition-mcp call get_results --study_id "$study_id" > "results-$study_id.json"
echo "Saved: results-$study_id.json"
```

***

## Daily standup digest

A cron job that posts running studies into a Slack-ready text file every morning:

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

userintuition-mcp call list_studies \
  | jq -r '[.[] | select(.status == "fielding")] |
           "\(length) studies fielding:\n" +
           ([.[] | "  • \(.title) (\(.responses_received)/\(.target_n))"] | join("\n"))' \
  > /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 assistants

Delete every assistant whose name starts with `test_`:

```bash theme={null}
userintuition-mcp call list_assistants \
  | jq -r '.[] | select(.name | startswith("test_")) | .id' \
  | while read -r id; do
      echo "Deleting $id"
      userintuition-mcp call delete_assistant --assistant_id "$id"
    done
```

<Warning>
  Destructive. Sanity-check the `jq` filter against `list_assistants` output first. There is no undo.
</Warning>

***

## Validate a claim, then route to the right next step

A small dispatcher that turns a single CLI call into a workflow:

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

claim="$1"
result=$(userintuition-mcp call ask_humans \
  --mode claim --text "$claim" --n 30 --dry_run false)

study_id=$(echo "$result" | jq -r .study_id)

# Wait for results (omitted — same polling as above)
final=$(userintuition-mcp call get_results --study_id "$study_id")
believability=$(echo "$final" | jq -r .believability_score)

if (( $(echo "$believability >= 0.7" | bc -l) )); then
  echo "✓ Claim believable ($believability). Greenlight."
else
  echo "✗ Claim not believable ($believability). Rework before launch."
  exit 1
fi
```

***

## 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 invites
userintuition-mcp list | grep invite

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

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

***

## 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 study brief.** Real fielding starts the moment you flip it to `false`.
* **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.