> ## Documentation Index > Fetch the complete documentation index at: https://docs.userjourneys.ai/llms.txt > Use this file to discover all available pages before exploring further. # Study Manager commands > Triage studies, read a study and its ledger, list what changed, and message the study's agent from the terminal. Every study has a Study Manager, an agent that reads each quality interview in full and keeps the study's [ledger](/api/study-ledger). `uj studies` is how you read that ledger from a terminal and talk to the agent that keeps it. Install and sign in first: [CLI overview](/cli). Each command prints its JSON payload on stdout and a short guide on stderr, so `uj studies get | jq` works and a person or an agent reading the terminal still learns what the fields mean and what to run next. ## How to read a study A study and its 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. [Grades and counts](/api/study-ledger#grades-and-counts) 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. Every quote of every active item is here; merged and retired items appear in events with their reasons. Check a quote in its transcript: `uj interviews get `. What changed and when: `uj studies events `. The agent answers questions and takes steers: `uj studies message "…"`, for example to ask why an item was graded as it was, to split or retire an item, to add a question it should track, or to set a preference that binds its later turns. The full configuration: `uj studies config get `. ## Commands ### `uj studies` — List Studies Triage your studies: one entry per study with its Study Manager state, as JSON. ```bash Usage theme={null} uj studies [--project ] [--status ] [--limit ] [--starting-after ] uj studies list [--project ] [--status ] [--limit ] [--starting-after ] ``` #### 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: ()`) 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 `; see what changed with `uj studies events `; steer its agent with `uj studies message `. #### Guide One entry per study, newest first. ledger\_summary is the study's Study Manager state: the agent reads every quality interview and records what each one supports; null means it has not saved yet. ledger\_summary.recent counts the major changes of the last seven days; all zero means quiet. Commands: `uj studies get ` reads a study, its questions and its ledger. `uj studies events ` lists what changed. `uj studies message "…"` sends the study's agent a question or a steer; it answers and, if it changed its view, saves. `uj interviews get ` opens a transcript. `uj studies config get ` shows the full configuration. ```bash Examples theme={null} # 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 Read a study, the configuration its agent read, and its ledger, as JSON. ```bash Usage theme={null} uj studies get [--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 `. * What changed and when: `uj studies events `. * 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 "…"`. * The full configuration, including voices, rewards and welcome settings: `uj studies config get `. #### Guide The Study Manager has not saved a ledger for this study. It runs when a quality interview completes; `uj studies message "…"` reaches it now. ```bash Examples theme={null} # 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 List what changed in a study's ledger, newest first, major changes only by default. ```bash Usage theme={null} uj studies events [--since ] [--limit ] [--starting-after ] [--debug] [--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 ` returns events created at or after that timestamp (Z or an offset); an event's created\_at can be passed back as is. * `--limit ` is the page size, default 50, max 100. The payload's has\_more says whether there is another page. * `--starting-after ` (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 `. Ask the agent about a change or steer it: `uj studies message "…"`. #### Guide What changed in this study's ledger, newest first. Each ledger\_version is one save by the Study Manager. Major kinds only: phase\_changed (with the reason), answer\_created and theme\_created (with supporters and reviewed at that version), question\_status\_changed (no pattern, emerging, answered). `--debug` adds the bookkeeping kinds: interviews reviewed and excluded, items strengthened, merged or retired, regrades, retitles, stance changes, must-reads, notes, questions created. `--since ` narrows; `--limit ` and `--starting-after ` page. Read an item in context: `uj studies get `. Ask the agent about a change or steer it: `uj studies message "…"`. ```bash Examples theme={null} # 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 Send a study's Study Manager a question or a steer and read its reply. ```bash Usage theme={null} uj studies message "" [--project ] [--max-wait-seconds ] [--detach] [--json] [--output ] ``` #### 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 `. * 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 "" thread=… session=…` line, a short guide, then sparse execution status while it works. * `--output ` 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 `. #### Guide The Study Manager keeps this study's ledger and saves a new version when it changes its view; check with `uj studies events `. It reads your message as a person steering it: a preference you state binds every later turn. Waiting… ```bash Examples theme={null} # 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](/api/study-ledger): the ledger object, the grade table and every event kind. * [Studies API](/api/studies): 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.