reachy-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-05-30
+
+### Added
+
+- `daemon` noun group (`start`/`stop`/`status`/`overview`): bring the local `reachy-mini-daemon` process up and down — background spawn + PID/log under `$XDG_STATE_HOME/reachy`, health-poll on `GET /api/daemon/status`, idempotent start, SIGTERM-then-SIGKILL stop.
+- `reachy/daemon.py` — stdlib-only daemon process-lifecycle module (no new runtime dependency).
+- `[daemon]` optional-dependencies extra (`reachy-mini>=1.0`) — the recommended default install, providing the `reachy-mini-daemon` binary.
+
+### Changed
+
+- Inverted the install model: `pip install 'reachy-cli[daemon]'` is now the default (bundles the daemon); the bare `pip install reachy-cli` is the HTTP-only *remote* profile. Base stays zero-runtime-deps.
+- The `http` transport's daemon-unreachable hint now points at `reachy daemon start` and the `[daemon]` install.
+- README + CLAUDE.md document the daemon noun, the install profiles, and the daemon-up wake-up flow.
+
 ## [0.2.0] - 2026-05-30
 
 ### Added

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/CLAUDE.md

@@ -40,7 +40,9 @@ test assertions in one pass.
 
 ```bash
 uv sync                                              # create .venv, install (dev deps incl. teken)
+uv sync --extra daemon                               # + reachy-mini (the reachy-mini-daemon binary)
 uv run reachy whoami                                 # run the CLI (NOT `reachy-mini-cli`)
+uv run reachy daemon start                           # bring the local daemon up (needs [daemon] extra)
 uv run pytest -n auto                                # full suite (parallel)
 uv run pytest tests/test_cli.py::test_whoami_text    # a single test
 uv run pytest --cov=reachy --cov-report=term         # with coverage (CI gate: fail_under=60)
@@ -93,13 +95,29 @@ you touch the CLI.
   line scanner (no YAML library) and walks up from `__file__` to find it.
   `doctor` re-implements the steward invariants (prompt-file-present,
   backend-consistency `claude`→`CLAUDE.md`, skills-present).
+- **`daemon` noun & process module:** `device`/`app`/`move` are *clients* of a
+  running daemon; `reachy/cli/_commands/daemon.py` + `reachy/daemon.py` are the
+  other half — they start/stop/status the local `reachy-mini-daemon` OS process
+  (background spawn + PID/log under `$REACHY_STATE_DIR` / `$XDG_STATE_HOME/reachy`,
+  health-poll via `GET /api/daemon/status`). Pure stdlib (`subprocess`/`signal`/
+  `urllib`); the daemon *binary* comes from the `[daemon]` extra. Its `overview`
+  is hand-built (no `--transport sdk` line) — `daemon` does NOT use a transport,
+  so it does not call `_robot.noun_overview`/`get_transport`. A missing binary
+  raises a clean exit-2 `CliError` pointing at the `[daemon]` install.
 
 ## Hard constraints
 
-- **Zero runtime dependencies.** `pyproject.toml` has `dependencies = []` on
-  purpose; `teken` is dev-only. This is why `whoami` hand-rolls YAML parsing.
-  Do not add a third-party runtime import without an explicit decision to change
-  this — it would break the "self-contained runtime" property the README sells.
+- **Zero *base* runtime dependencies.** `pyproject.toml` keeps base
+  `dependencies = []` on purpose; `teken` is dev-only. This is why `whoami`
+  hand-rolls YAML parsing and `reachy/daemon.py` manages the daemon process with
+  stdlib `subprocess`/`urllib` only. The **recommended default install is `pip
+  install 'reachy-cli[daemon]'`** (pulls `reachy-mini` for the
+  `reachy-mini-daemon` binary); the bare `pip install reachy-cli` is the
+  HTTP-only *remote* profile. Keep the *base* dep-free — anything that needs
+  `reachy-mini` (the `sdk` transport, the daemon binary) goes behind the
+  `[daemon]`/`[sdk]` extras, never into base `dependencies`. Adding a base
+  runtime dep needs an explicit decision; it would break the dependency-free
+  remote profile the README sells.
 - **Python ≥ 3.12** (uses `X | None`, `tomllib`, etc.).
 - **Every PR bumps the version**, even docs/config/CI-only changes — the
   `version-check` CI job blocks the merge otherwise (it compares

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reachy-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Agent and CLI for operating the Reachy Mini expressive robot — device setup, app management, and runtime ops.
 Project-URL: Homepage, https://github.com/agentculture/reachy-mini-cli
 Project-URL: Issues, https://github.com/agentculture/reachy-mini-cli/issues
@@ -13,6 +13,8 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
+Provides-Extra: daemon
+Requires-Dist: reachy-mini>=1.0; extra == 'daemon'
 Provides-Extra: sdk
 Requires-Dist: reachy-mini>=1.0; extra == 'sdk'
 Description-Content-Type: text/markdown
@@ -35,10 +37,11 @@ Agent and CLI for operating the Reachy Mini expressive robot — device setup, a
 ## Quickstart
 
 ```bash
-uv sync
+uv sync --extra daemon                # default: + the local reachy-mini-daemon
+# uv sync                             # remote profile: HTTP-only, no daemon deps
 uv run pytest -n auto                 # run the test suite
-uv run reachy-mini-cli whoami  # identity from culture.yaml
-uv run reachy-mini-cli learn   # self-teaching prompt (add --json)
+uv run reachy whoami                  # identity from culture.yaml
+uv run reachy learn                   # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 
@@ -59,8 +62,44 @@ error, `3+` reserved.
 
 ## Robot operations
 
-The `device`, `app`, and `move` noun groups operate the Reachy Mini. They talk
-to the robot through a selectable **transport flavor**:
+The `daemon`, `device`, `app`, and `move` noun groups operate the Reachy Mini.
+
+### Install profiles
+
+The Reachy daemon (`reachy-mini-daemon`) and the in-process SDK ship in
+`reachy-mini`. Choose your install by where the daemon runs:
+
+- **Default — with the daemon:** `pip install 'reachy-cli[daemon]'`. Bundles
+  `reachy-mini`, so `reachy daemon start` can bring the daemon up locally. This
+  is the profile for a machine with a robot attached.
+- **Remote — without the daemon:** `pip install reachy-cli` (bare). The base
+  install keeps **zero runtime dependencies** (the `http` transport and the
+  `daemon status`/`stop` verbs use only the stdlib). Use it on a control box that
+  only talks to a daemon running elsewhere via `--base-url` / `REACHY_BASE_URL`.
+  `daemon start` here exits `2` with a hint to install the `[daemon]` extra.
+
+`[sdk]` (also `reachy-mini`) adds the in-process `--transport sdk` client.
+
+### Bring the daemon up
+
+`device`/`app`/`move` are clients of a running daemon; `daemon` is the other
+half — it manages the local `reachy-mini-daemon` process.
+
+| Verb | What it does |
+|------|--------------|
+| `daemon start` | Spawn `reachy-mini-daemon` in the background, then poll its health route until ready. Idempotent. |
+| `daemon stop` | Stop the daemon this CLI started (SIGTERM, then SIGKILL). |
+| `daemon status` | Reconcile the tracked process (running/stopped/stale) with the HTTP health check. |
+
+`reachy-mini-daemon` defaults to `--wake-up-on-start`, so `daemon start` already
+wakes the robot. Forward daemon args after `--`, e.g.
+`reachy daemon start -- --sim --no-wake-up-on-start`. State (PID + log) lives
+under `$XDG_STATE_HOME/reachy` (`~/.local/state/reachy`).
+
+### Transports
+
+The `device`, `app`, and `move` verbs talk to a running daemon through a
+selectable **transport flavor**:
 
 - **`http`** (default) — the Reachy daemon's REST API. Uses only the Python
   standard library, so the default install keeps **zero runtime dependencies**.
@@ -89,11 +128,12 @@ with a clean `error:`/`hint:` pair — never a traceback.
 Each noun also exposes `overview` (e.g. `reachy move overview`).
 
 ```bash
-# Start the daemon (from the reachy_mini SDK), then:
-uv run reachy device status
+uv run reachy daemon start            # bring the local daemon up (and wake the robot)
+uv run reachy device status           # now answers instead of exit-2
 uv run reachy app list --json
 uv run reachy move goto --z 10 --pitch -5 --duration 2
 uv run reachy move wake
+uv run reachy daemon stop             # put it back down when you're done
 ```
 
 ## Make it your own

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/README.md

@@ -16,10 +16,11 @@ Agent and CLI for operating the Reachy Mini expressive robot — device setup, a
 ## Quickstart
 
 ```bash
-uv sync
+uv sync --extra daemon                # default: + the local reachy-mini-daemon
+# uv sync                             # remote profile: HTTP-only, no daemon deps
 uv run pytest -n auto                 # run the test suite
-uv run reachy-mini-cli whoami  # identity from culture.yaml
-uv run reachy-mini-cli learn   # self-teaching prompt (add --json)
+uv run reachy whoami                  # identity from culture.yaml
+uv run reachy learn                   # self-teaching prompt (add --json)
 uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs
 ```
 
@@ -40,8 +41,44 @@ error, `3+` reserved.
 
 ## Robot operations
 
-The `device`, `app`, and `move` noun groups operate the Reachy Mini. They talk
-to the robot through a selectable **transport flavor**:
+The `daemon`, `device`, `app`, and `move` noun groups operate the Reachy Mini.
+
+### Install profiles
+
+The Reachy daemon (`reachy-mini-daemon`) and the in-process SDK ship in
+`reachy-mini`. Choose your install by where the daemon runs:
+
+- **Default — with the daemon:** `pip install 'reachy-cli[daemon]'`. Bundles
+  `reachy-mini`, so `reachy daemon start` can bring the daemon up locally. This
+  is the profile for a machine with a robot attached.
+- **Remote — without the daemon:** `pip install reachy-cli` (bare). The base
+  install keeps **zero runtime dependencies** (the `http` transport and the
+  `daemon status`/`stop` verbs use only the stdlib). Use it on a control box that
+  only talks to a daemon running elsewhere via `--base-url` / `REACHY_BASE_URL`.
+  `daemon start` here exits `2` with a hint to install the `[daemon]` extra.
+
+`[sdk]` (also `reachy-mini`) adds the in-process `--transport sdk` client.
+
+### Bring the daemon up
+
+`device`/`app`/`move` are clients of a running daemon; `daemon` is the other
+half — it manages the local `reachy-mini-daemon` process.
+
+| Verb | What it does |
+|------|--------------|
+| `daemon start` | Spawn `reachy-mini-daemon` in the background, then poll its health route until ready. Idempotent. |
+| `daemon stop` | Stop the daemon this CLI started (SIGTERM, then SIGKILL). |
+| `daemon status` | Reconcile the tracked process (running/stopped/stale) with the HTTP health check. |
+
+`reachy-mini-daemon` defaults to `--wake-up-on-start`, so `daemon start` already
+wakes the robot. Forward daemon args after `--`, e.g.
+`reachy daemon start -- --sim --no-wake-up-on-start`. State (PID + log) lives
+under `$XDG_STATE_HOME/reachy` (`~/.local/state/reachy`).
+
+### Transports
+
+The `device`, `app`, and `move` verbs talk to a running daemon through a
+selectable **transport flavor**:
 
 - **`http`** (default) — the Reachy daemon's REST API. Uses only the Python
   standard library, so the default install keeps **zero runtime dependencies**.
@@ -70,11 +107,12 @@ with a clean `error:`/`hint:` pair — never a traceback.
 Each noun also exposes `overview` (e.g. `reachy move overview`).
 
 ```bash
-# Start the daemon (from the reachy_mini SDK), then:
-uv run reachy device status
+uv run reachy daemon start            # bring the local daemon up (and wake the robot)
+uv run reachy device status           # now answers instead of exit-2
 uv run reachy app list --json
 uv run reachy move goto --z 10 --pitch -5 --duration 2
 uv run reachy move wake
+uv run reachy daemon stop             # put it back down when you're done
 ```
 
 ## Make it your own

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "reachy-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Agent and CLI for operating the Reachy Mini expressive robot — device setup, app management, and runtime ops."
 readme = "README.md"
 license = "MIT"
@@ -15,12 +15,20 @@ classifiers = [
 ]
 dependencies = []
 
-# Optional "sdk" transport flavor. The default install stays dependency-free
-# (the http transport uses only the stdlib); installing the extra enables
-# `--transport sdk`, which drives the robot through the in-process client.
-# Sanctioned exception to the zero-runtime-dependency rule — see
+# Optional extras. The base install stays dependency-free (the http transport and
+# the `daemon` process verbs use only the stdlib), so the bare `pip install
+# reachy-cli` is the lightweight HTTP-only *remote* profile — for a control box
+# that only talks to a daemon running elsewhere via --base-url / REACHY_BASE_URL.
+#
+# The recommended *default* is `pip install 'reachy-cli[daemon]'`: it pulls in
+# `reachy-mini`, which provides the `reachy-mini-daemon` binary that `reachy
+# daemon start` launches. `[sdk]` enables the in-process `--transport sdk` client.
+# Both resolve to the same `reachy-mini` wheel today (it ships both the daemon
+# binary and the SDK client); they stay separately named for intent clarity.
+# Sanctioned exceptions to the zero-runtime-dependency rule — see
 # docs/adr-0001-sdk-transport-extra.md.
 [project.optional-dependencies]
+daemon = ["reachy-mini>=1.0"]
 sdk = ["reachy-mini>=1.0"]
 
 [project.urls]

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/reachy/cli/__init__.py

@@ -64,6 +64,7 @@ def _argv_has_json(argv: list[str] | None) -> bool:
 def _build_parser() -> argparse.ArgumentParser:
     from reachy.cli._commands import app as _app_group
     from reachy.cli._commands import cli as _cli_group
+    from reachy.cli._commands import daemon as _daemon_group
     from reachy.cli._commands import device as _device_group
     from reachy.cli._commands import doctor as _doctor_cmd
     from reachy.cli._commands import explain as _explain_cmd
@@ -91,7 +92,8 @@ def _build_parser() -> argparse.ArgumentParser:
     _overview_cmd.register(sub)
     _doctor_cmd.register(sub)
     _cli_group.register(sub)
-    # Robot noun groups (device setup, app management, runtime ops).
+    # Robot noun groups (daemon lifecycle, device setup, app mgmt, runtime ops).
+    _daemon_group.register(sub)
     _device_group.register(sub)
     _app_group.register(sub)
     _move_group.register(sub)

reachy_cli-0.3.0/reachy/cli/_commands/daemon.py

@@ -0,0 +1,165 @@
+"""``reachy-mini-cli daemon`` — local daemon process lifecycle.
+
+The robot verbs (``device`` / ``app`` / ``move``) talk *to* a running daemon;
+this noun is the other half — it brings the local ``reachy-mini-daemon`` process
+up and down. ``start`` spawns it in the background and waits for its health
+route, ``stop`` terminates it, ``status`` reconciles the tracked process with the
+HTTP health check. The daemon binary ships in the ``[daemon]`` extra; a missing
+binary yields a clean exit-2 hint pointing at the install.
+
+Note: ``reachy-mini-daemon`` defaults to ``--wake-up-on-start``, so ``daemon
+start`` already wakes the robot. Forward ``-- --no-wake-up-on-start`` to skip it.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+from reachy import daemon as _daemon
+from reachy.cli._commands._robot import emit_payload
+from reachy.cli._commands.overview import emit_overview
+from reachy.robot.transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+
+_JSON_HELP = "Emit structured JSON."
+
+_VERBS = [
+    "daemon start — start the local reachy-mini-daemon in the background",
+    "daemon stop — stop the daemon this CLI started",
+    "daemon status — process + HTTP-health state of the daemon",
+    "daemon overview — this summary",
+]
+
+
+def _add_health_args(parser: argparse.ArgumentParser) -> None:
+    """Flags shared by verbs that talk to the daemon's health route."""
+    parser.add_argument("--json", action="store_true", help=_JSON_HELP)
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("REACHY_BASE_URL", DEFAULT_BASE_URL),
+        help="Daemon base URL for the health check (env REACHY_BASE_URL).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT,
+        help=f"Health-check request timeout in seconds (default: {DEFAULT_TIMEOUT}).",
+    )
+
+
+def cmd_daemon_overview(args: argparse.Namespace) -> int:
+    sections: list[dict[str, object]] = [
+        {"title": "Verbs", "items": list(_VERBS)},
+        {
+            "title": "State",
+            "items": [
+                f"pid file: {_daemon.pid_file()}",
+                f"log file: {_daemon.log_file()}",
+                f"health route: {DEFAULT_BASE_URL}{_daemon.HEALTH_PATH}",
+            ],
+        },
+        {
+            "title": "Conventions",
+            "items": [
+                "every command supports --json",
+                "start spawns reachy-mini-daemon detached, then polls the health route",
+                "the daemon ships in the [daemon] extra: pip install 'reachy-cli[daemon]'",
+                "override the binary with --daemon-cmd or REACHY_DAEMON_CMD",
+                "forward daemon args after '--' (e.g. -- --sim --fastapi-port 9000)",
+                "exit codes: 0 ok, 1 user error, 2 environment (binary/daemon missing)",
+            ],
+        },
+    ]
+    emit_overview(
+        "reachy-mini-cli daemon",
+        sections,
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def cmd_daemon_start(args: argparse.Namespace) -> int:
+    data = _daemon.start(
+        base_url=args.base_url,
+        wait=not args.no_wait,
+        wait_timeout=args.wait_timeout,
+        poll_timeout=args.timeout,
+        daemon_cmd=args.daemon_cmd,
+        extra_args=list(args.daemon_args or []),
+    )
+    emit_payload(data, json_mode=bool(getattr(args, "json", False)))
+    return 0
+
+
+def cmd_daemon_stop(args: argparse.Namespace) -> int:
+    data = _daemon.stop(timeout=args.timeout)
+    emit_payload(data, json_mode=bool(getattr(args, "json", False)))
+    return 0
+
+
+def cmd_daemon_status(args: argparse.Namespace) -> int:
+    data = _daemon.status(base_url=args.base_url, timeout=args.timeout)
+    emit_payload(data, json_mode=bool(getattr(args, "json", False)))
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    return cmd_daemon_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "daemon",
+        help="Local daemon process lifecycle (see 'reachy-mini-cli daemon overview').",
+    )
+    p.add_argument("--json", action="store_true", help=_JSON_HELP)
+    p.set_defaults(func=_no_verb, json=False)
+    noun_sub = p.add_subparsers(dest="daemon_command", parser_class=type(p))
+
+    ov = noun_sub.add_parser("overview", help="Describe the daemon noun group.")
+    ov.add_argument("--json", action="store_true", help=_JSON_HELP)
+    ov.set_defaults(func=cmd_daemon_overview)
+
+    start = noun_sub.add_parser("start", help="Start the local reachy-mini-daemon.")
+    _add_health_args(start)
+    start.add_argument(
+        "--daemon-cmd",
+        default=None,
+        help="Override the daemon launch command (env REACHY_DAEMON_CMD).",
+    )
+    start.add_argument(
+        "--no-wait",
+        action="store_true",
+        help="Return immediately after spawning, without polling the health route.",
+    )
+    start.add_argument(
+        "--wait-timeout",
+        type=float,
+        default=_daemon.DEFAULT_WAIT_TIMEOUT,
+        help="Seconds to wait for the daemon to become healthy "
+        f"(default: {_daemon.DEFAULT_WAIT_TIMEOUT:g}).",
+    )
+    start.add_argument(
+        "daemon_args",
+        nargs="*",
+        default=[],
+        metavar="-- ARGS",
+        help="Args after '--' are forwarded to reachy-mini-daemon "
+        "(e.g. -- --sim --fastapi-port 9000).",
+    )
+    start.set_defaults(func=cmd_daemon_start)
+
+    stop = noun_sub.add_parser("stop", help="Stop the daemon this CLI started.")
+    stop.add_argument("--json", action="store_true", help=_JSON_HELP)
+    stop.add_argument(
+        "--timeout",
+        type=float,
+        default=_daemon.DEFAULT_STOP_TIMEOUT,
+        help="Seconds to wait after SIGTERM before SIGKILL "
+        f"(default: {_daemon.DEFAULT_STOP_TIMEOUT:g}).",
+    )
+    stop.set_defaults(func=cmd_daemon_stop)
+
+    st = noun_sub.add_parser("status", help="Report daemon process + HTTP-health state.")
+    _add_health_args(st)
+    st.set_defaults(func=cmd_daemon_status)

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/reachy/cli/_commands/learn.py

@@ -31,6 +31,7 @@ Commands
   reachy-mini-cli cli overview       Describe the CLI surface itself.
 
 Robot commands (talk to the Reachy daemon; --transport http|sdk)
+  reachy-mini-cli daemon start       Start the local daemon; also: stop/status.
   reachy-mini-cli device status      Daemon status / device info.
   reachy-mini-cli device state       Live robot state (pose, antennas).
   reachy-mini-cli app list           Available apps; also: status/start/stop.
@@ -66,6 +67,9 @@ def _as_json_payload() -> dict[str, object]:
             {"path": ["overview"], "summary": "Descriptive snapshot of the agent."},
             {"path": ["doctor"], "summary": "Check the agent-identity invariants."},
             {"path": ["cli", "overview"], "summary": "Describe the CLI surface."},
+            {"path": ["daemon", "start"], "summary": "Start the local reachy-mini-daemon."},
+            {"path": ["daemon", "stop"], "summary": "Stop the daemon this CLI started."},
+            {"path": ["daemon", "status"], "summary": "Daemon process + HTTP-health state."},
             {"path": ["device", "status"], "summary": "Daemon status / device info."},
             {"path": ["device", "state"], "summary": "Live robot state."},
             {"path": ["app", "list"], "summary": "List/start/stop Reachy Mini apps."},

{reachy_cli-0.2.0 → reachy_cli-0.3.0}/reachy/cli/_commands/overview.py

@@ -30,6 +30,7 @@ _VERBS = [
     "explain <path> — markdown docs for a topic",
     "overview — this descriptive snapshot",
     "doctor — check the agent-identity invariants",
+    "daemon <verb> — start/stop/check the local reachy-mini-daemon process",
     "device <verb> — daemon/robot status and live state",
     "app <verb> — list/start/stop Reachy Mini apps",
     "move <verb> — runtime motion (goto, wake, sleep)",