honcho-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/.gitignore

@@ -6,8 +6,8 @@ api/docker-compose.yml
 *.db
 data
 redis-data
-docker-compose.yml
-compose.yml
+/docker-compose.yml
+/compose.yml
 
 
 
@@ -195,4 +195,4 @@ lancedb_data/
 grafana-data/
 
 # Claude Code addon stuff
-.omc
+.omc

honcho_cli-0.1.4/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+
+## [0.1.4] - 2026-08-26
+
+### Added
+
+- A TTY notice when a newer `honcho-cli` is on PyPI (`uv tool upgrade honcho-cli`). Skipped in JSON mode; disable with `HONCHO_NO_UPDATE_CHECK`
+
+### Fixed
+
+- `--setup` for openai-compatible writes `EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URL` into the profile `.env` alongside `LLM_OPENAI_BASE_URL` (#1068)
+- `--setup` API key prompts echo `*` per character so a paste is visibly received instead of a blank getpass field
+
+## [0.1.3] - 2026-08-25
+
+### Added
+
+- `honcho start`, `honcho stop`, and `honcho status` — run a personal Honcho stack in Docker (API, deriver, Postgres, Redis). Profiles live under `~/.honcho/profiles/`. First start pins `ghcr.io/plastic-labs/honcho:latest` by digest and copies the image `config.toml`. Optional `--setup basic` / `--setup advanced` wizard writes LLM overrides to `.env` (#1029)
+- `honcho session view` — session transcript table (`--last N`, `--page N --size M`, `--all`, `--reverse`, `--ids`, peer filter via `-p`). Content is shown verbatim, timestamps are normalized to UTC, and the command is read-only: unlike the other session commands it never get-or-creates the session (#1006)
+
+### Fixed
+
+- `honcho message list --last N` no longer stops at the first page of 50 — it walks pages to fill the requested window (#1006)
+
+## [0.1.2] - 2026-07-20
+
+### Added
+
+- Device-code OAuth login for managed Honcho servers. `honcho init` now offers browser-based login (RFC 8628 device authorization grant) when the host advertises the device grant in its OAuth authorization-server metadata; tokens are persisted to `~/.honcho/config.json` and auto-refreshed (#891)
+- `HONCHO_CONFIG_DIR` environment variable for pointing the CLI at an alternate config directory (#891)
+
+### Changed
+
+- An OAuth grant now records the host it was minted against and is ignored — neither used nor refreshed — when `base_url` points elsewhere, so a staging grant is never sent to production. A live OAuth token takes precedence over a stored `apiKey`, and a dead grant degrades to the saved key with a warning instead of aborting. Device login no longer deletes the shared `apiKey`, which sibling tools read from the same config file (#891)
+
+## [0.1.1] - 2026-06-15
+
+### Fixed
+
+- Declare `click` as an explicit dependency. The CLI imported `click` directly but relied on it being pulled in transitively, so installs without it on the path could fail at runtime (#787)
+
+## [0.1.0] - 2026-04-20
+
+### Added
+
+- Initial release of `honcho-cli` — a terminal for inspecting and managing a Honcho deployment (#424)
+- `workspace`, `peer`, `session`, `message`, `conclusion`, and `config` command groups for managing resources against any Honcho server
+- `init` onboarding flow that prompts for and persists connection settings, with flag/env-var pre-seeding for non-interactive use
+- Per-command flags, environment variables, and a config file for pointing the CLI at different servers (local, self-hosted, or hosted)
+- Rich terminal output and an agent-usage mode for scripting against the CLI
+- Documentation and an agent skill for the CLI (#589)

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: honcho-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: A terminal for Honcho — memory that reasons.
 Project-URL: Homepage, https://github.com/plastic-labs/honcho
 Project-URL: Repository, https://github.com/plastic-labs/honcho
@@ -47,22 +47,50 @@ uv tool install honcho-cli
 ## Quick Start
 
 ```bash
-honcho init        # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
-honcho doctor      # verify your config + connectivity
-honcho             # show banner + command list
+honcho init                 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
+honcho start --setup basic  # local stack: LLM provider key + Docker
+honcho doctor               # verify config + connectivity
+honcho                      # show banner + command list
 ```
 
-`honcho init` reads `apiKey` and `environmentUrl` from the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share). If both are present, it confirms them with you; if either is missing (or you decline), it prompts for the missing value(s) and writes them back. Host-specific entries under `hosts` are left untouched.
+`honcho init` writes `apiKey` and `environmentUrl` to the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share) so the CLI can call a Honcho server. If both are present, it confirms them with you; if either is missing (or you decline), it prompts and writes them back. Host-specific entries under `hosts` are left untouched. It does **not** set the LLM provider key the local deriver needs — that is `honcho start --setup` (or `LLM_*_API_KEY` in the environment).
 
 Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars — not persisted as CLI defaults.
 
+### Local stack
+
+`honcho start --setup basic` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. The wizard writes the LLM provider key into the profile `.env` — `honcho init` cannot do this; its `apiKey` is for calling a Honcho server, not for deriver/dialectic inference. You can also pass `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` in the environment and skip `--setup`. Stack files live under `~/.honcho/profiles/local/` and are not committed to a project.
+
+On first start, the CLI pulls `ghcr.io/plastic-labs/honcho:latest` and **pins that digest** in `profile.json`, then copies the image's `config.toml.example` to `config.toml` in the same directory. `honcho start` never overwrites `config.toml` after that — including when you re-pin the image. Delete the file yourself if you want a fresh copy from a new image.
+
+Pass `--setup basic` or `--setup advanced` for an interactive wizard that writes curated LLM/feature overrides into the profile `.env` (env wins over `config.toml`). TTY only; re-runnable. `basic` asks provider + chat model; `advanced` also covers embeddings, deriver/dialectic models, dreams, and snappy deriver flush. Everything else stays in `config.toml`.
+
+`honcho start` does **not** change `environmentUrl` in `~/.honcho/config.json` (that file is shared with plugins). To talk to the local stack for one command:
+
+```bash
+HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list
+```
+
+To make local the default, run `honcho init --base-url http://127.0.0.1:8000`.
+
+```bash
+honcho start --setup basic
+honcho start --setup advanced
+honcho status
+honcho stop            # keep data
+honcho stop --wipe     # also delete volumes
+```
+
 ## Commands
 
 ### Onboarding
 
 | Command | Description |
 |---------|-------------|
-| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json` |
+| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json`. |
+| `honcho start` | Start a local Honcho stack (API, deriver, Postgres, Redis). Requires Docker and a cloud LLM key. `--setup basic` / `--setup advanced` runs an interactive config wizard (TTY only). Does not change `environmentUrl`. |
+| `honcho stop` | Stop the local stack. `--wipe` also deletes volumes. |
+| `honcho status` | Show every local stack (or `--profile` for one). |
 | `honcho doctor` | Health check: config, connectivity, workspace, peer, queue |
 
 ### Workspaces
@@ -96,6 +124,7 @@ Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-
 | `honcho session list` | List sessions in the workspace (filter with `--peer/-p`) |
 | `honcho session create <id>` | Create or get a session (optionally `--peers` to add peers, `--metadata`) |
 | `honcho session inspect <id>` | Peers, message count, summaries, config |
+| `honcho session view <id>` | Transcript table (`--last N`, `--page N --size M`, `--all`, `--reverse`, `--ids`, `-p`) |
 | `honcho session context <id>` | What an agent would see |
 | `honcho session summaries <id>` | Short + long summaries |
 | `honcho session peers <id>` / `add-peers` / `remove-peers` | Peer management |
@@ -181,6 +210,9 @@ Precedence (highest first): **flag → env var → config file → default**.
 | `HONCHO_PEER_ID` | `-p` / `--peer` | Peer scope |
 | `HONCHO_SESSION_ID` | `-s` / `--session` | Session scope |
 | `HONCHO_JSON` | `--json` | Force JSON output (`1` / `true`) |
+| `HONCHO_NO_UPDATE_CHECK` | — | Disable the once-a-day upgrade notice (`1` / `true`) |
+| `HONCHO_PROFILE` | `--profile` (start/stop/status) | Local stack profile (default: `local`) |
+| `LLM_OPENAI_API_KEY` | — | Provider key for `honcho start` (also `LLM_ANTHROPIC_API_KEY`, `LLM_GEMINI_API_KEY`) |
 
 ```bash
 # Per-command flags

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/README.md

@@ -22,22 +22,50 @@ uv tool install honcho-cli
 ## Quick Start
 
 ```bash
-honcho init        # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
-honcho doctor      # verify your config + connectivity
-honcho             # show banner + command list
+honcho init                 # confirm/set apiKey + Honcho URL in ~/.honcho/config.json
+honcho start --setup basic  # local stack: LLM provider key + Docker
+honcho doctor               # verify config + connectivity
+honcho                      # show banner + command list
 ```
 
-`honcho init` reads `apiKey` and `environmentUrl` from the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share). If both are present, it confirms them with you; if either is missing (or you decline), it prompts for the missing value(s) and writes them back. Host-specific entries under `hosts` are left untouched.
+`honcho init` writes `apiKey` and `environmentUrl` to the top-level of `~/.honcho/config.json` (the same file other Honcho tools — plugins, host integrations — share) so the CLI can call a Honcho server. If both are present, it confirms them with you; if either is missing (or you decline), it prompts and writes them back. Host-specific entries under `hosts` are left untouched. It does **not** set the LLM provider key the local deriver needs — that is `honcho start --setup` (or `LLM_*_API_KEY` in the environment).
 
 Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars — not persisted as CLI defaults.
 
+### Local stack
+
+`honcho start --setup basic` runs a personal Honcho server on your machine (API, deriver, Postgres, Redis) via Docker. The wizard writes the LLM provider key into the profile `.env` — `honcho init` cannot do this; its `apiKey` is for calling a Honcho server, not for deriver/dialectic inference. You can also pass `LLM_OPENAI_API_KEY`, `LLM_ANTHROPIC_API_KEY`, or `LLM_GEMINI_API_KEY` in the environment and skip `--setup`. Stack files live under `~/.honcho/profiles/local/` and are not committed to a project.
+
+On first start, the CLI pulls `ghcr.io/plastic-labs/honcho:latest` and **pins that digest** in `profile.json`, then copies the image's `config.toml.example` to `config.toml` in the same directory. `honcho start` never overwrites `config.toml` after that — including when you re-pin the image. Delete the file yourself if you want a fresh copy from a new image.
+
+Pass `--setup basic` or `--setup advanced` for an interactive wizard that writes curated LLM/feature overrides into the profile `.env` (env wins over `config.toml`). TTY only; re-runnable. `basic` asks provider + chat model; `advanced` also covers embeddings, deriver/dialectic models, dreams, and snappy deriver flush. Everything else stays in `config.toml`.
+
+`honcho start` does **not** change `environmentUrl` in `~/.honcho/config.json` (that file is shared with plugins). To talk to the local stack for one command:
+
+```bash
+HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list
+```
+
+To make local the default, run `honcho init --base-url http://127.0.0.1:8000`.
+
+```bash
+honcho start --setup basic
+honcho start --setup advanced
+honcho status
+honcho stop            # keep data
+honcho stop --wipe     # also delete volumes
+```
+
 ## Commands
 
 ### Onboarding
 
 | Command | Description |
 |---------|-------------|
-| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json` |
+| `honcho init` | Confirm/set `apiKey` + `environmentUrl` in `~/.honcho/config.json`. |
+| `honcho start` | Start a local Honcho stack (API, deriver, Postgres, Redis). Requires Docker and a cloud LLM key. `--setup basic` / `--setup advanced` runs an interactive config wizard (TTY only). Does not change `environmentUrl`. |
+| `honcho stop` | Stop the local stack. `--wipe` also deletes volumes. |
+| `honcho status` | Show every local stack (or `--profile` for one). |
 | `honcho doctor` | Health check: config, connectivity, workspace, peer, queue |
 
 ### Workspaces
@@ -71,6 +99,7 @@ Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-
 | `honcho session list` | List sessions in the workspace (filter with `--peer/-p`) |
 | `honcho session create <id>` | Create or get a session (optionally `--peers` to add peers, `--metadata`) |
 | `honcho session inspect <id>` | Peers, message count, summaries, config |
+| `honcho session view <id>` | Transcript table (`--last N`, `--page N --size M`, `--all`, `--reverse`, `--ids`, `-p`) |
 | `honcho session context <id>` | What an agent would see |
 | `honcho session summaries <id>` | Short + long summaries |
 | `honcho session peers <id>` / `add-peers` / `remove-peers` | Peer management |
@@ -156,6 +185,9 @@ Precedence (highest first): **flag → env var → config file → default**.
 | `HONCHO_PEER_ID` | `-p` / `--peer` | Peer scope |
 | `HONCHO_SESSION_ID` | `-s` / `--session` | Session scope |
 | `HONCHO_JSON` | `--json` | Force JSON output (`1` / `true`) |
+| `HONCHO_NO_UPDATE_CHECK` | — | Disable the once-a-day upgrade notice (`1` / `true`) |
+| `HONCHO_PROFILE` | `--profile` (start/stop/status) | Local stack profile (default: `local`) |
+| `LLM_OPENAI_API_KEY` | — | Provider key for `honcho start` (also `LLM_ANTHROPIC_API_KEY`, `LLM_GEMINI_API_KEY`) |
 
 ```bash
 # Per-command flags

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "honcho-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "A terminal for Honcho — memory that reasons."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -38,6 +38,10 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/honcho_cli"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"src/honcho_cli/local/templates/docker-compose.yml" = "honcho_cli/local/templates/docker-compose.yml"
+"src/honcho_cli/local/templates/init.sql" = "honcho_cli/local/templates/init.sql"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/scripts/generate_cli_docs.py

@@ -230,7 +230,7 @@ def build() -> str:
     body: list[str] = []
     for name in sorted(root.commands):
         body.extend(_render_top(root.commands[name], ["honcho", name]))
-    return HEADER + "\n".join(body) + "\n"
+    return HEADER + "\n".join(body).rstrip("\n") + "\n"
 
 
 def main() -> int:

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/src/honcho_cli/__init__.py

@@ -1,3 +1,3 @@
 """Honcho CLI — a terminal for Honcho."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/src/honcho_cli/_help.py

@@ -24,6 +24,7 @@ from typer.core import TyperGroup
 from honcho_cli import __version__
 from honcho_cli.branding import BANNER, BRAND
 from honcho_cli.output import use_json
+from honcho_cli.update_check import maybe_print_update_nag
 
 
 # Theme Typer's rich help renderer. Module-level side effect limited to
@@ -59,15 +60,21 @@ def _welcome_panel(title: str, rows: list[tuple[str, str]]) -> Panel:
 
 
 def print_welcome(console: Console) -> None:
-    """Render the curated 3-panel welcome (banner + getting started / memory / commands)."""
+    """Render the curated welcome (banner + getting started / local stack / commands / memory)."""
     if use_json():
         return
     console.print(f"[bold {BRAND}]{BANNER}[/bold {BRAND}]")
     console.print(f"  [dim]v{__version__}[/dim]\n", highlight=False)
 
     start_rows = [
-        ("honcho init",   "configure API key and server URL"),
-        ("honcho doctor", "verify connection and workspace health"),
+        ("honcho init",                  "configure API key and server URL"),
+        ("honcho start [--setup basic]", "run a local Honcho stack (Docker)"),
+        ("honcho doctor",                "verify connection and workspace health"),
+    ]
+    stack_rows = [
+        ("honcho start / status / stop",          "lifecycle for the local Docker stack"),
+        ("honcho start --setup basic",            "interactive LLM + feature wizard"),
+        ("HONCHO_BASE_URL=http://127.0.0.1:8000", "prefix any command — CLI stays on api.honcho.dev until you set this"),
     ]
     cmd_rows = [
         ("[dim]pattern[/dim]", r"[dim]honcho <command> \[args] \[-w workspace] \[-p peer] \[-s session][/dim]"),
@@ -76,7 +83,7 @@ def print_welcome(console: Console) -> None:
         ("workspace",  "list · create · search · delete · inspect · queue-status"),
         ("peer",       "list · create · search · inspect · card · chat"),
         ("",           "get-metadata · set-metadata · representation"),
-        ("session",    "list · create · search · delete · inspect · add-peers"),
+        ("session",    "list · create · search · delete · inspect · view · add-peers"),
         ("",           "context · get-metadata · set-metadata · peers"),
         ("",           "remove-peers · representation · summaries"),
         ("message",    "list · create · get"),
@@ -84,14 +91,15 @@ def print_welcome(console: Console) -> None:
         ("config",     "inspect current configuration"),
     ]
     memory_rows = [
-        ("honcho peer chat \"...\" -p <peer> -w <workspace>","query the Dialectic about a peer"),
-        ("honcho peer inspect -p <peer> -w <workspace>","dashboard: peer card + recent conclusions + configuration"),
+        ("honcho peer chat \"...\" -p <peer> -w <workspace>", "query the Dialectic about a peer"),
+        ("honcho peer inspect -p <peer> -w <workspace>", "dashboard: peer card + recent conclusions + configuration"),
         ("honcho peer representation -p <peer> -w <workspace>", "global peer representation"),
         ("honcho peer representation -p <peer> -w <workspace> -s <session>", "session-scoped peer representation"),
         ("honcho peer card -p <peer> -w <workspace>", "synthesized identity: traits, preferences, instructions"),
-        ("honcho conclusion list -p <peer> -w <workspace>",  "browse peer conclusions"),
+        ("honcho conclusion list -p <peer> -w <workspace>", "browse peer conclusions"),
+        ("honcho session view / context -s <session>", "transcript, or what an agent would see"),
+        ("honcho workspace queue-status", "is the deriver processing?"),
     ]
-
     option_rows = [
         ("-w / --workspace", "scope to a workspace"),
         ("-p / --peer",      "scope to a peer"),
@@ -101,10 +109,12 @@ def print_welcome(console: Console) -> None:
     ]
 
     console.print(_welcome_panel("getting started", start_rows))
+    console.print(_welcome_panel("local stack", stack_rows))
     console.print(_welcome_panel("commands", cmd_rows))
     console.print(_welcome_panel("memory", memory_rows))
     console.print(_welcome_panel("options", option_rows))
     console.print()
+    maybe_print_update_nag()
 
 
 class HonchoTyperGroup(TyperGroup):

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/src/honcho_cli/commands/message.py

@@ -10,7 +10,7 @@ import typer
 
 from honcho.api_types import MessageCreateParams
 
-from honcho_cli.commands.session import _get_session_id
+from honcho_cli.commands.session import _fetch_recent_messages, _get_session_id
 from honcho_cli.commands.workspace import _handle_error
 from honcho_cli.output import print_error, print_result, status
 from honcho_cli.validation import validate_resource_id
@@ -37,15 +37,18 @@ def list_messages(
 
     handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer, session=session)
     sid = _get_session_id(session_id)
+    if last < 1:
+        print_error("INVALID_FLAGS", "--last must be >= 1", {"last": last})
+        raise typer.Exit(1)
     client, config = get_client()
     sess = client.session(sid)
 
     try:
         filters = {"peer_id": config.peer_id} if config.peer_id else None
-        # Fetch newest-first so [:last] always gives the most recent N messages,
-        # then flip to oldest-at-top / newest-at-bottom for readable display.
+        # Fetch newest-first so we always get the most recent N messages, then
+        # flip to oldest-at-top / newest-at-bottom for readable display.
         # --reverse keeps the raw server order (oldest first, descending in table).
-        msgs = sess.messages(filters=filters, reverse=True).items[:last]
+        msgs, _ = _fetch_recent_messages(sess, filters, last)
         if not reverse:
             msgs = list(reversed(msgs))
 

{honcho_cli-0.1.2 → honcho_cli-0.1.4}/src/honcho_cli/commands/session.py

@@ -1,22 +1,29 @@
-"""Session commands: list, inspect, context, summaries, peers, search, representation, metadata."""
+"""Session commands: list, inspect, view, context, summaries, peers, search, representation, metadata."""
 
 from __future__ import annotations
 
 import json
+import shlex
 from typing import List, Optional
 
 import typer
 
-from honcho import HonchoError
+from honcho import HonchoError, Session
 
 from honcho_cli.commands.workspace import _config_to_dict, _handle_error, _raw_list
-from honcho_cli.output import print_error, print_result, status, use_json
+from honcho_cli.output import print_error, print_result, print_transcript, status, use_json
 from honcho_cli.validation import validate_resource_id
 
 from honcho_cli._help import HonchoTyperGroup
-from honcho_cli.common import add_common_options, get_client, get_resolved_config, handle_cmd_flags
-
-app = typer.Typer(cls=HonchoTyperGroup, help="List, inspect, create, delete, and manage conversation sessions and their peers.")
+from honcho_cli.common import (
+    add_common_options,
+    get_client,
+    get_flag_overrides,
+    get_resolved_config,
+    handle_cmd_flags,
+)
+
+app = typer.Typer(cls=HonchoTyperGroup, help="List, inspect, view, create, delete, and manage conversation sessions and their peers.")
 add_common_options(app)
 
 
@@ -135,6 +142,240 @@ def inspect(
         _handle_error(e, "session", sid)
 
 
+# Server-side ceiling on page size (fastapi-pagination's default ``Params``
+# declares ``size`` as ``Query(50, ge=1, le=100)``).
+MAX_PAGE_SIZE = 100
+DEFAULT_PAGE_SIZE = 50
+
+
+def _fetch_recent_messages(sess, filters: dict | None, last: int) -> tuple[list, int | None]:
+    """Fetch the ``last`` most recent messages, newest first.
+
+    Walks as many newest-first server pages as it takes to fill the window.
+    Returns the messages plus the session's total message count (if reported).
+    """
+    page = sess.messages(
+        filters=filters,
+        reverse=True,
+        size=min(max(last, 1), MAX_PAGE_SIZE),
+    )
+    total = page.total
+    msgs = list(page.items)
+    while len(msgs) < last and page.has_next_page():
+        page = page.get_next_page()
+        if page is None:
+            break
+        msgs.extend(page.items)
+    return msgs[:last], total
+
+
+def _next_page_command(
+    session_id: str,
+    next_page: int,
+    size: int,
+    *,
+    reverse: bool,
+    show_ids: bool,
+    workspace: str | None,
+    peer: str | None,
+) -> str:
+    """Continuation command for the next page, carrying this invocation's scope.
+
+    Scoping flags are echoed only when passed as flags; anything resolved from
+    the environment or config file resolves the same way on the next run. IDs
+    are shell-quoted — they may contain spaces and metacharacters, and this
+    string is meant to be pasted into a shell.
+    """
+    parts = [
+        "honcho",
+        "session",
+        "view",
+        session_id,
+        "--page",
+        str(next_page),
+        "--size",
+        str(size),
+    ]
+    if reverse:
+        parts.append("--reverse")
+    if show_ids:
+        parts.append("--ids")
+    if workspace:
+        parts += ["-w", workspace]
+    if peer:
+        parts += ["-p", peer]
+    return shlex.join(parts)
+
+
+def _fetch_all_messages(sess, filters: dict | None) -> tuple[list, int | None]:
+    """Fetch every message in the session, oldest first."""
+    page = sess.messages(filters=filters, reverse=False, size=MAX_PAGE_SIZE)
+    total = page.total
+    msgs = list(page.items)
+    while page.has_next_page():
+        page = page.get_next_page()
+        if page is None:
+            break
+        msgs.extend(page.items)
+    return msgs, total
+
+
+@app.command()
+def view(
+    session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),
+    last: Optional[int] = typer.Option(
+        None,
+        "--last",
+        help=f"Show only the N most recent messages (default when no --page/--all: {DEFAULT_PAGE_SIZE})",
+    ),
+    page_number: Optional[int] = typer.Option(
+        None,
+        "--page",
+        help="1-indexed page of the full transcript. Use for page 2+.",
+    ),
+    size: Optional[int] = typer.Option(
+        None,
+        "--size",
+        help=f"Messages per page; requires --page (1-{MAX_PAGE_SIZE}, default: {DEFAULT_PAGE_SIZE})",
+    ),
+    all_messages: bool = typer.Option(False, "--all", help="Show the full transcript (every page)"),
+    reverse: bool = typer.Option(
+        False,
+        "--reverse",
+        help="Newest first (default is chronological: oldest at top)",
+    ),
+    show_ids: bool = typer.Option(False, "--ids", help="Include message IDs in the transcript"),
+    workspace: Optional[str] = typer.Option(None, "--workspace", "-w", help="Override workspace ID"),
+    peer: Optional[str] = typer.Option(None, "--peer", "-p", help="Filter by peer ID"),
+    session: Optional[str] = typer.Option(None, "--session", "-s", help="Override session ID"),
+    json_output: bool = typer.Option(False, "--json", help="Force JSON output"),
+) -> None:
+    """View a session transcript as a chat log.
+
+    Modes (pick one):
+
+    - default / --last N: tail of the conversation (most recent N)
+    - --page N [--size M]: page through the full transcript
+    - --all: every message
+
+    Paging follows the requested order: --page 1 starts at the oldest message,
+    or the newest with --reverse.
+
+    Human mode prints a row-delimited table. JSON mode emits the message list
+    (same shape as message list).
+    """
+    handle_cmd_flags(json_output=json_output, workspace=workspace, peer=peer, session=session)
+    sid = _get_session_id(session_id)
+
+    # Validate every flag before touching the network.
+    modes = sum([
+        last is not None,
+        page_number is not None,
+        all_messages,
+    ])
+    if modes > 1:
+        print_error(
+            "INVALID_FLAGS",
+            "--last, --page, and --all are mutually exclusive",
+            {"last": last, "page": page_number, "all": all_messages},
+        )
+        raise typer.Exit(1)
+
+    if page_number is not None and page_number < 1:
+        print_error("INVALID_FLAGS", "--page must be >= 1", {"page": page_number})
+        raise typer.Exit(1)
+    if size is not None and page_number is None:
+        print_error("INVALID_FLAGS", "--size only applies with --page", {"size": size})
+        raise typer.Exit(1)
+    if size is not None and not 1 <= size <= MAX_PAGE_SIZE:
+        print_error(
+            "INVALID_FLAGS",
+            f"--size must be between 1 and {MAX_PAGE_SIZE}",
+            {"size": size},
+        )
+        raise typer.Exit(1)
+    if last is not None and last < 1:
+        print_error("INVALID_FLAGS", "--last must be >= 1", {"last": last})
+        raise typer.Exit(1)
+
+    # Default: tail of conversation (most recent 50).
+    mode = "page" if page_number is not None else ("all" if all_messages else "last")
+    tail = last if last is not None else DEFAULT_PAGE_SIZE
+    page_size = size if size is not None else DEFAULT_PAGE_SIZE
+
+    client, config = get_client()
+    # Read-only: client.session() is a get-or-create POST, so build the Session directly.
+    sess = Session(sid, client)
+
+    try:
+        filters = {"peer_id": config.peer_id} if config.peer_id else None
+        page_meta: int | None = None
+        pages_meta: int | None = None
+
+        if mode == "page":
+            # Page in the order the caller asked for.
+            result_page = sess.messages(
+                filters=filters,
+                page=page_number,
+                size=page_size,
+                reverse=reverse,
+            )
+            msgs = list(result_page.items)
+            total = result_page.total
+            page_meta = result_page.page if result_page.page is not None else page_number
+            pages_meta = result_page.pages
+        elif mode == "all":
+            msgs, total = _fetch_all_messages(sess, filters)
+            if reverse:
+                msgs = list(reversed(msgs))
+        else:
+            # Tail window: fetched newest-first, flipped to chronological unless --reverse.
+            msgs, total = _fetch_recent_messages(sess, filters, tail)
+            if not reverse:
+                msgs = list(reversed(msgs))
+
+        items = [
+            {
+                "id": m.id,
+                "peer_id": m.peer_id,
+                "content": m.content,
+                "token_count": m.token_count,
+                "metadata": m.metadata,
+                "created_at": str(m.created_at),
+            }
+            for m in msgs
+        ]
+    except Exception as e:
+        _handle_error(e, "session", sid)
+        raise  # unreachable: _handle_error always exits
+
+    next_page_hint = None
+    if page_meta is not None and pages_meta is not None and page_meta < pages_meta:
+        # Effective overrides, not the command-level params: -w/-p also parse at
+        # group and top level.
+        overrides = get_flag_overrides()
+        next_page_hint = _next_page_command(
+            sid,
+            page_meta + 1,
+            page_size,
+            reverse=reverse,
+            show_ids=show_ids,
+            workspace=overrides["workspace"],
+            peer=overrides["peer"],
+        )
+
+    # Rendered outside the try: output failures aren't session API errors.
+    print_transcript(
+        items,
+        session_id=sid,
+        total=total,
+        page=page_meta,
+        pages=pages_meta,
+        show_ids=show_ids,
+        next_page_hint=next_page_hint,
+    )
+
+
 @app.command()
 def context(
     session_id: Optional[str] = typer.Argument(None, help="Session ID (uses default if omitted)"),