Skip to main content

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.

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: 
#!/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: 
#!/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: 
#!/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_: 
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
Destructive. Sanity-check the jq filter against list_assistants output first. There is no undo.

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

A small dispatcher that turns a single CLI call into a workflow: 
#!/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: 
# 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.

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