Runs
Trigger runs and inspect, tail, and cancel them from the terminal.
A run is one unit of agent work — a ticket (or a plain-text description) taken through your pipeline to a pull request. The root run fans out to child runs (one per repo/task); most commands here show both.
Statuses
Terminal statuses are done, completed, merged, failed, and cancelled.
failed and cancelled count as failure for exit codes and --wait. See
Status lifecycle for the full state machine.
premia run
Trigger a run from a plain-text description — no ticket required.
premia run "<description>" [--project <id>] [--title <t>] [--wait] [--json]Arguments
| Argument | Required | Description |
|---|---|---|
description | yes | What you want done, in plain English. |
Flags
| Flag | Description |
|---|---|
--project <id> | Project public id. Overrides .premia.json (see premia init). |
--title <t> | Optional human title for the run. |
--wait | Block until the run and all its children finish; exit non-zero on failure. |
--json | Machine-readable output. |
Examples
premia run "add pagination to the users table"
premia run "fix the login bug" --wait
premia run "apply the billing migration" --project acme-web --jsonFire-and-forget returns the id immediately:
✓ Run created: 3f9a2c1b-7d4e-4a02-9f11-2c6b8e0a5d33With --wait, the command polls until every run is terminal and reflects the
aggregate in its exit code:
→ Run 3f9a2c1b — waiting for completion…
✓ merged{ "run_id": "3f9a2c1b-7d4e-4a02-9f11-2c6b8e0a5d33", "status": "merged" }--wait polls every 5s and aggregates children: if any run ends in failed
or cancelled, the command exits 1. This is what makes premia run … --wait
safe to gate a CI job on — see CI integration.
premia runs list
List recent runs, newest first.
premia runs list [--status <s>] [--limit <n>] [--json]Flags
| Flag | Default | Description |
|---|---|---|
--status <s> | — | Filter by status (queued, running, failed, merged, …). |
--limit <n> | 20 | Maximum rows. |
--json | — | Output JSON. |
Example
premia runs list --status failed --limit 50ID STATUS REF TITLE WHEN
3f9a2c1b merged PREM-142 Add pagination to the users table 2h ago
7c1e88a0 running PREM-143 Fix flaky auth test 5m ago
a2b3c4d5 failed #412 Migrate billing webhooks 1d agoREF is the Linear identifier when present, otherwise the PR number.
premia runs view
Show a single run's detail, including its child tasks.
premia runs view <id> [--json]Arguments
| Argument | Required | Description |
|---|---|---|
id | yes | Run id (full or the 8-char prefix shown in runs list). |
Example
Add pagination to the users table
id 3f9a2c1b-7d4e-4a02-9f11-2c6b8e0a5d33
status merged
step plan
ticket PREM-142
pr https://github.com/acme/app/pull/318
Tasks
5a1b2c3d merged execute #318
6e7f8a9b done reviewPass --json for the full object (root run plus a children array) — handy
for scripting.
premia runs logs
Print a run's logs (across all its child steps). Add --follow to stream.
premia runs logs <id> [--follow] [--level <lvl>] [--json]Flags
| Flag | Alias | Description |
|---|---|---|
--follow | -f | Stream new logs until the run reaches a terminal state (Ctrl+C to stop). |
--level <lvl> | Filter by level: info, warning, or error. | |
--json | NDJSON output (one JSON object per line). |
Examples
premia runs logs 3f9a2c1b
premia runs logs 3f9a2c1b --follow
premia runs logs 3f9a2c1b --level error10:32:01 AM Planning across 1 repo…
10:32:14 AM Opened PR #318
10:33:02 AM Review passedWarnings render yellow and errors red in a TTY. In --follow mode the CLI polls
every 3s and does a final flush when the run finishes.
premia runs cancel
Cancel a queued or running run (and its children).
premia runs cancel <id>✓ Cancelled 3f9a2c1b-7d4e-4a02-9f11-2c6b8e0a5d33Already-terminal runs are unaffected.
Recipes
Trigger, capture the id, and tail it:
RUN_ID=$(premia run "refactor the auth module" --json | jq -r '.run_id')
premia runs logs "$RUN_ID" --followFail a shell script if the run didn't merge cleanly:
premia run "apply migration for PREM-142" --wait || {
echo "Premia run failed"; exit 1;
}