> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Journal Commands

> View the Crew Journal event stream from the command line.

# crewship journal

Read the [Crew Journal](/guides/crew-journal) -- the canonical append-only event stream for every observable action in the platform. Filter by crew, agent, mission, entry type, severity, actor, priority, trace, or time window.

```bash theme={null}
crewship journal [flags]
crewship journal get <entry-id>
crewship journal count [flags]
crewship journal priority <entry-id> --mark <marker> [--reason <text>]
```

The top-level command is the list view. `--follow` opens an SSE connection to `/api/v1/journal/stream` and prints entries as they arrive (Ctrl-C to exit). The CLI auto-reconnects on transient failure with bounded exponential backoff (1 s → 30 s) and threads `Last-Event-ID` so a brief disconnect resumes without dropping or duplicating entries. For pretty in-browser viewing, the web UI `/journal` page is also available.

## Flags

| Flag             | Type     | Default | Description                                                                                   |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
| `--lines`        | `int`    | `50`    | Max entries to fetch (1-500).                                                                 |
| `--crew`         | `string` |         | Filter by crew slug or ID.                                                                    |
| `--agent`        | `string` |         | Filter by agent ID.                                                                           |
| `--mission`      | `string` |         | Filter by mission ID.                                                                         |
| `--trace-id`     | `string` |         | Narrow to a single run's spans (`trace_id` == run id).                                        |
| `--type`         | `string` |         | Comma-separated entry types (e.g. `peer.escalation,keeper.decision`).                         |
| `--exclude-type` | `string` |         | Comma-separated entry types to exclude (NOT IN). Useful for hiding `container.metrics` noise. |
| `--severity`     | `string` |         | Comma-separated severities (`info`, `notice`, `warn`, `error`).                               |
| `--actor-type`   | `string` |         | Comma-separated actors (`agent`, `user`, `system`, `keeper`, `sidecar`, `orchestrator`).      |
| `--priority`     | `string` |         | Comma-separated priorities (`normal`, `high`, `pin`, `permanent`).                            |
| `--query` / `-q` | `string` |         | Server-side FTS5 search across `summary` + `payload`. Bounded to 200 chars.                   |
| `--since`        | `string` |         | Time window (`1h`, `24h`, `7d`, or RFC3339).                                                  |
| `--follow`       | `bool`   | `false` | Live tail via SSE — Ctrl-C to exit, reconnects on transient failure.                          |

Global output flags apply: `--format text|json|yaml` (default text). Enum values for `--severity`, `--actor-type`, and `--priority` are validated client-side before the request goes out, so a typo fails fast with a list of allowed values.

## Examples

```bash theme={null}
# Last 50 entries across the workspace
crewship journal

# Last 24h of a specific crew
crewship journal --crew backend-team --since 24h

# Every warn/error
crewship journal --severity warn,error

# Recent escalations and keeper decisions
crewship journal --type peer.escalation,keeper.decision --lines 100

# Mission timeline as JSON for scripting
crewship journal --mission MIS-42 --format json

# Full-text search across summary + payload
crewship journal --query "OOMKilled" --since 24h
crewship journal -q "ratelimit" --severity warn,error

# One run's full trace, including LLM/exec/network spans
crewship journal --trace-id <run-id>

# Hide container.metrics noise from a long timeline
crewship journal --exclude-type container.metrics,exec.output_chunk --lines 200

# Only operator-pinned entries
crewship journal --priority pin,permanent

# Live tail — print entries as they arrive (Ctrl-C to exit)
crewship journal --follow
crewship journal --follow --severity warn,error
crewship journal --follow --crew backend-team
```

For free-text "did we discuss this before?" lookups across the journal, prefer `crewship recall <query>` — same backing endpoint, snippet-card rendering optimised for question-answering.

## `crewship journal get`

Fetch a single entry by ID. Output respects `--format` (`text`, `json`, `yaml`); the text format prints the same single-line summary the list view uses, then indents the entry's `payload` and `refs` underneath so you can see the full structured detail at a glance.

```bash theme={null}
crewship journal get j_a1b2c3d4
crewship journal get j_a1b2c3d4 --format json | jq .payload
```

The endpoint is workspace-scoped — IDs from another workspace come back as `404` with the same shape as "not found" (no cross-tenant existence leak).

## `crewship journal count`

Print the total number of entries that match a filter set. Identical filter flags to the list view (minus `--lines` / `--follow`); `--cursor` and `--limit` are silently ignored — count is always over the full result set.

```bash theme={null}
crewship journal count
crewship journal count --severity error --since 24h
crewship journal count --type budget.exceeded
crewship journal count --query "OOMKilled" --format json
```

Default text output is the bare integer for shell scripting:

```bash theme={null}
if [ "$(crewship journal count --type budget.exceeded --since 1h)" -gt 0 ]; then
  pagerduty-trigger "Budget exceeded in last hour"
fi
```

## `crewship journal priority`

Annotate one entry with a priority marker (`normal`, `high`, `pin`, `permanent`). Requires OWNER or ADMIN on the workspace. Marker affects compaction and recall — see the [Crew Journal guide](/guides/crew-journal#priority-markers) for the semantics.

```bash theme={null}
crewship journal priority j_abc --mark permanent --reason "FX compliance rule"
crewship journal priority j_abc --mark pin --reason "team playbook entry"
crewship journal priority j_abc --mark normal
```

The `--mark` value is validated client-side before the request goes out. Each invocation also writes a `memory.priority_changed` audit entry to the journal carrying the previous and new priority plus the supplied reason — so the curation history is itself queryable.

## `crewship journal lookup`

Fetch the workspace reference table the web timeline uses to render journal cards with human-readable crew/agent/mission names. Useful for joining `crewship journal --format json` output against names in shell pipelines.

```bash theme={null}
crewship journal lookup
crewship journal lookup --format json
crewship journal lookup --format json | jq '.crews[] | {id, slug, name}'
```

Backed by `GET /api/v1/journal/lookup`. The endpoint is workspace-scoped — no filter arguments. The response groups three reference lists:

| Section    | Fields                                |
| ---------- | ------------------------------------- |
| `crews`    | `id`, `name`, `slug`, `icon`, `color` |
| `agents`   | `id`, `name`, `slug`, `crew_id`       |
| `missions` | `id`, `title`, `status`               |

Text mode renders each section as a short table and caps each at **50 rows** so the output stays scannable; pass `--format json` (or `yaml`) to get the full unbounded snapshot.

To narrow the timeline to a single run rather than a reference table, use [`crewship journal --trace-id <run-id>`](#flags) on the list command — the two surfaces serve different jobs.

## Sample output

```
2026-04-17 10:23:41  [info    ]  peer.conversation       agent       viktor → eva: "pushing hotfix"
2026-04-17 10:24:02  [warn    ]  keeper.decision         keeper      denied production SSH (risk=8)
2026-04-17 10:24:15  [error   ]  budget.exceeded         system      crew/day at 103.2% ($51.62 / $50.00)
```

Columns: timestamp, severity chip (color-coded — gray=info/default, cyan=notice, yellow=warn, red=error), entry type (bold), actor type, summary.

## Entry type catalog

See the [Crew Journal guide](/guides/crew-journal#entry-type-catalog) for the full list. Common filters:

| `--type` value                                                         | When to use                                                           |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `keeper.decision`                                                      | Every credential access decision.                                     |
| `peer.escalation`                                                      | Cross-agent handoffs (often tied to `approval.requested`).            |
| `budget.exceeded,budget.warning`                                       | Cost oversight.                                                       |
| `approval.requested,approval.granted,approval.denied,approval.timeout` | HITL audit.                                                           |
| `hook.fired,hook.blocked`                                              | Lifecycle hook activity.                                              |
| `eval.regression_detected`                                             | Eval surfaced regression.                                             |
| `run.started,run.completed,run.failed,run.cancelled,run.timeout`       | Run lifecycle (`/runs` page is folded into `/journal` since PR #234). |

## Parsing `--since` / `--until`

Accepted formats:

* Duration suffixes: `30m`, `1h`, `24h`, `7d` (the `d` suffix is handled locally; Go's `time.ParseDuration` doesn't support it).
* RFC3339: `2026-04-17T00:00:00Z`.

`--until` is supported on `journal count` (lower bound is `--since`, upper bound is `--until`); the list view doesn't currently expose `--until` because the default ordering is "newest first" and pagination uses a cursor.

## Notes

* Output is scoped to the caller's workspace automatically -- there is no way to query another workspace from the CLI.
* Pagination is keyset-based on the server; the list view doesn't expose the cursor (it fetches `--lines` rows and stops). For paged programmatic access, prefer the JSON output of the [`/api/v1/journal`](/api-reference/journal#list-entries) endpoint.
* For structured programmatic access prefer `--format json`.

## Related

* [Crew Journal guide](/guides/crew-journal).
* [Journal API](/api-reference/journal).