Study Manager commands

​

How to read a study

​

Commands

​

uj studies — List Studies

uj studies [--project <project>] [--status <active|paused|concluded|all>] [--limit <n>] [--starting-after <study_id>]
uj studies list [--project <project>] [--status <active|paused|concluded|all>] [--limit <n>] [--starting-after <study_id>]

​

Output

• uj studies with no action is uj studies list.
• stdout is the public list payload (GET /api/v1/studies), pretty-printed and untouched; no CLI-only fields are added, so jq always works.
• stderr carries the project (Project: <name> (<id>)) and a short guide to the fields and the next commands.
• --json is accepted and changes nothing: the payload is always JSON.

​

Status and state

• The CLI shows all studies (active, paused and concluded) by default; they are listed newest first.
• Narrow with --status active, --status paused or --status concluded. The filter is on the stored status; a stale or limit-reached study is active.
• The public API (GET /api/v1/studies) defaults to active; pass ?status=all, ?status=paused or ?status=concluded there.
• Each study carries state, its one displayed state: value is concluded, paused, limit_reached, stale or active (in that precedence), reason is one line to print as is, since is when the state began, resets_at is when a reached limit’s window rolls over and stale_at is when an active study goes stale if nothing happens.
• accepting_responses is true exactly when state.value is active or stale.
• Each study carries interview_quality: its completed, non-test, non-deleted interviews by grade (insightful, successful, unsuccessful, unscored) and ratio, the share of graded interviews that were usable; a low ratio points at the study’s setup, not at a finding.
• Move a study with uj studies pause|resume|conclude|reopen <study_id>.

​

Ledger summary

• Each study carries ledger_summary, the Study Manager’s state: version, updated_at, phase, reviewed, excluded, and recent.
• recent counts the major ledger events since you last looked at that study when you are signed in (since is your checkpoint), else the last seven days; one integer per kind; all zero means quiet.
• ledger_summary is null for a study whose Study Manager has not saved yet: a study with no ledger, never a quiet one.
• Read a study with uj studies get <study_id>; see what changed with uj studies events <study_id>; steer its agent with uj studies message <study_id>.

​

Guide

# Triage all studies
uj studies

# List only paused studies
uj studies list --status paused

# Name and displayed state of every study
uj studies | jq -r '.data[] | [.name, .state.value, .state.reason] | @tsv'

# Studies whose agent has saved, with their phase
uj studies | jq '.data[] | select(.ledger_summary != null) | {id, name, phase: .ledger_summary.phase}'

​

uj studies get — Get Study

uj studies get <study_id> [--project <project>] [--json]

​

What you get

• stdout is the public study payload (GET /api/v1/studies/{id}?expand=ledger), pretty-printed and untouched; --json changes nothing.
• The study: research_goal, product_name, product_context, respondent_type, respondent_notes, and the questions with their notes.
• ledger: the Study Manager’s current ledger (overview, phase, questions with answers, themes, must_reads, excluded, notes, preferences), every quote of every active item included.
• ledger is null before the Study Manager’s first save; the command still exits 0 and says so on stderr.
• A short guide to the fields prints on stderr before the payload.

​

Reading the ledger

• The ledger is kept by the Study Manager, an agent that reads every quality interview in full and records what each one supports.
• overview says what the study is about (what it sets out to learn, from whom); it never says how it is going.
• An item’s supporters is the number of reviewed, non-excluded interviews with a quote graded A to C; weak counts D and E; both are out of reviewed, so compare supporters with reviewed.
• A: raised it unprompted and concretely. B: a direct answer to the interviewer’s question. C: hedged or partial. D and E never count. Titles never say how many.
• Every quote is the respondent’s exact words, checked against the transcript; start and end are seconds into the interview, and app_url opens that moment in the app.
• Merged and retired items are not in the ledger; they appear in uj studies events with their reasons.

​

Next

• Check a quote in its transcript: uj interviews get <interview_id>.
• What changed and when: uj studies events <study_id>.
• Ask the agent why an item was graded as it was, split or retire an item, add a question, or set a preference: uj studies message <study_id> "…".
• The full configuration, including the screener, voices, rewards and welcome settings: uj studies config get <study_id>.

​

Guide

# Read a study and its ledger
uj studies get 00000000-0000-4000-8000-000000000000

# Supporters and quote count of the first answer
uj studies get 00000000-0000-4000-8000-000000000000 | jq '.ledger.questions[0].answers[0] | {title, supporters, weak, reviewed, quotes: (.evidence | length)}'

​

uj studies events — Study Events

uj studies events <study_id> [--since <ISO>] [--limit <n>] [--starting-after <event_id>] [--debug] [--project <project>] [--json]

​

Major kinds (default)

• phase_changed: the agent’s call on where the study stands changed, with its reason.
• answer_created and theme_created: a new item, with supporters and reviewed at that version.
• question_status_changed: a question moved between no pattern, emerging and answered.
• status_changed: a person paused, resumed, concluded or reopened the study (or restored it from the trash); detail has from, to and the actor.
• Each ledger_version is one save by the Study Manager; a status_changed event is not born from a save and carries the version the study was at, or null.

​

Bookkeeping kinds (—debug)

• --debug drops the kind filter: interviews reviewed and excluded, items strengthened, merged or retired, regrades and stance changes, retitles (item_redefined), must-reads, notes, questions created.

​

Window and paging

• --since <ISO> returns events created at or after that timestamp (Z or an offset); an event’s created_at can be passed back as is.
• Signed in and no --since: the window starts where you last looked at this study and the read marks it as looked at now; stderr says Since you last looked: <time> or No checkpoint yet; all events., then Marked as seen.. A project API key has no checkpoint: no window, nothing marked.
• --limit <n> is the page size, default 50, max 100. The payload’s has_more says whether there is another page.
• --starting-after <event_id> (the last id of the previous page) reads the next page.
• --starting-after neither uses nor moves the checkpoint; pass the --since shown on the first page to keep the same window.

​

Output

• stdout is the public events payload (GET /api/v1/studies/{id}/events), pretty-printed and untouched; --json changes nothing.
• No events yet is an empty list and exit 0.
• Read an item in context: uj studies get <study_id>. Ask the agent about a change or steer it: uj studies message <study_id> "…".

​

Guide

# Major changes, newest first
uj studies events 00000000-0000-4000-8000-000000000000

# Everything since a timestamp, bookkeeping included
uj studies events 00000000-0000-4000-8000-000000000000 --since 2026-09-12T00:00:00Z --debug

# Kinds and item ids only
uj studies events 00000000-0000-4000-8000-000000000000 | jq -r '.data[] | [.kind, .item_id // .interview_id] | @tsv'

​

uj studies message — Message the Study Manager

uj studies message <study-id> "<text>" [--project <project>] [--max-wait-seconds <n>] [--detach] [--history] [--json] [--output <file>]

​

What happens

• The message lands in the study’s own thread as the Study Manager, the same agent the results page talks to; a study without a thread gets one, bound before the first turn.
• The Study Manager keeps the study’s ledger and saves a new version when it changes its view; check with uj studies events <study-id>.
• It reads your message as a person steering it: ask why an item was graded as it was, split or retire an item, add a question it should track, or state a preference, which binds every later turn.

​

Output contract

• stdout: the agent’s reply only. --history prints the thread read instead (its first 20 messages, oldest first); --json prints the tool result.
• stderr: a Sent to the Study Manager of "<study>" thread=… session=… line, a short guide, then sparse execution status while it works.
• --output <file> writes the reply to the file and keeps status out of it.

​

Busy and recovery

• While a turn is running the study refuses a second message (nothing is queued): the CLI says so and exits 1; try again in a minute.
• --detach starts the turn and returns the thread and session ids without waiting.
• When the wait is exceeded or the reply cannot be read, the thread id is on stderr: read it with uj thread get <thread-id>.

​

Guide

# Ask the agent to split a theme if the evidence says two things
uj studies message 00000000-0000-4000-8000-000000000000 "Is the placement theme about the corner itself, or about covering Generate? Split it if the evidence says two things."

# Set a preference that binds later turns, without waiting
uj studies message 00000000-0000-4000-8000-000000000000 --detach "Grade hedged answers about pricing as C, never B."

​

uj studies pause — Set Study Status

uj studies pause <study_id> [--project <project>] [--json]
uj studies resume <study_id> [--project <project>] [--json]
uj studies conclude <study_id> [--project <project>] [--notes "<text>"] [--json]
uj studies reopen <study_id> [--project <project>] [--json]

​

The moves

• A study is active, paused or concluded. pause moves an active study to paused; conclude moves an active or paused study to concluded; resume moves a paused study back to active; reopen moves a concluded study back to active.
• resume and reopen are the same move (to active), so either reopens a concluded study or resumes a paused one. A concluded study cannot be paused: reopen it first.
• A move to the status the study is already in is refused with the reason, so a script that fires twice learns it: study_status_transition_not_allowed: paused -> paused.
• Paused and concluded studies admit nobody at the interview link. Interviews already in progress finish, and the Study Manager still reviews them.
• The move lands on the study’s timeline as a status_changed event naming you; uj studies events <study_id> lists it.

​

Conclusion notes

• conclude takes --notes "<text>": what the study settled and what is left open, in your words. The notes open the study’s results page while it is concluded, come back as conclusion_notes from uj studies get, and are on the status_changed event.
• Concluding writes whatever was given: omit --notes, or leave it blank, and the study has none, including notes from an earlier conclusion. Reopening keeps the notes until the study is concluded again.

​

Output

• stdout is one line, Paused <name>: paused, the verb then the study’s displayed state; --json prints the payload instead: study_id, name, status (the stored value) and state (value, since, resets_at, stale_at, reason).
• A refused move exits 1 with the reason on stderr.

​

Guide

# Pause a study
uj studies pause 00000000-0000-4000-8000-000000000000

# Conclude a study, with what it settled
uj studies conclude 00000000-0000-4000-8000-000000000000 --notes "Placement is the answer: seven of nine wanted the button in the corner. Pricing is still open."

# Reopen a concluded study
uj studies reopen 00000000-0000-4000-8000-000000000000

# The new state, as JSON
uj studies resume 00000000-0000-4000-8000-000000000000 --json | jq .state

​

See also

• Study ledger and events: the ledger object, the grade table and every event kind.
• Studies API: the same payloads over REST, including ledger_summary on the list and expand=ledger on the detail.
• uj help studies, uj help studies get, uj help studies events, uj help studies message, uj help studies pause: the pages above, offline.