Study Manager commands

​

How to read a study

​

Commands

​

uj studies — List Studies

uj studies [--project <project>] [--status <active|paused|all>] [--limit <n>] [--starting-after <study_id>]
uj studies list [--project <project>] [--status <active|paused|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

• The CLI shows all studies (active and paused) by default; they are listed newest first.
• Narrow with --status active or --status paused.
• The public API (GET /api/v1/studies) defaults to active; pass ?status=all or ?status=paused there.

​

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 of the last seven days (since is the window start), 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

# 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 (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.
• 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.
• 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 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.
• Each ledger_version is one save by the Study Manager.

​

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

​

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] [--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, unless --json is used (then 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."

​

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: the pages above, offline.