asher-cli 1.0.2__tar.gz → 1.1.0__tar.gz

asher_cli-1.1.0/.claude/hooks/block-env.py

@@ -0,0 +1,14 @@
+import json
+import sys
+
+try:
+    payload = json.load(sys.stdin)
+    file_path = payload.get("file_path", "")
+except (json.JSONDecodeError, ValueError):
+    sys.exit(0)
+
+if file_path.endswith(".env"):
+    print("Blocked: .env contains real credentials — edit it manually if needed")
+    sys.exit(2)
+
+sys.exit(0)

{asher_cli-1.0.2 → asher_cli-1.1.0}/.claude/settings.json

@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "powershell -NonInteractive -ExecutionPolicy Bypass -File .claude/hooks/block-env.ps1"
+            "command": "uv run python .claude/hooks/block-env.py"
           }
         ]
       }

asher_cli-1.1.0/.claude/skills/mcp-bridge/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: mcp-bridge
+description: How asher-cli's /mcp command and the asher-mcp-launch credential bridge work. Load before changing asher/mcp_config.py, asher/mcp_bridge.py, or the /mcp slash command.
+user-invocable: false
+---
+
+# MCP bridge (`/mcp`)
+
+pylitterbot ships an optional MCP server (`pip install pylitterbot[mcp]`, run via `python -m pylitterbot.mcp`) that lets an MCP client like Claude Desktop monitor/control the robot directly. Its own docs configure it with plaintext credentials in the client's JSON config — asher-cli avoids that:
+
+- `/mcp on|off|status` (in `asher/commands/__init__.py`, logic in `asher/mcp_config.py`) adds/removes an entry (named by `mcp_config._SERVER_NAME`) in every `claude_desktop_config.json` this OS's Claude Desktop might read (`mcp_config.config_paths()` — on Windows this includes both the standard installer path and any MSIX/Microsoft Store virtualized path). The entry's `command` is `sys.executable -m asher.mcp_bridge` — never the credentials themselves.
+- `/mcp on` also auto-installs pylitterbot's `mcp` extra via `sys.executable -m pip install "pylitterbot[mcp]==<installed version>"` if the `mcp` package isn't importable yet.
+- `asher/mcp_bridge.py` (console script `asher-mcp-launch`) is what Claude Desktop actually spawns. It reads email/password from the OS keyring at process start, sets them as `LITTER_ROBOT_USERNAME`/`LITTER_ROBOT_PASSWORD` (pylitterbot's expected names — note these differ from asher-cli's own `.env` var `LITTER_ROBOT_USER`) in that process's environment only, then execs `python -m pylitterbot.mcp`. No credentials ever touch the on-disk MCP config.
+- `/mcp on` requires keyring credentials. If none are found but `.env` fallback credentials are set, it copies them into the keyring automatically (since the bridge process can't reliably discover a project-relative `.env` — Claude Desktop controls its working directory, not asher-cli).
+- Requires the `mcp` extra: `uv sync --extra mcp` / `pip install asher-cli[mcp]`. Restart Claude Desktop after toggling for the change to take effect.

asher_cli-1.1.0/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [karanshukla]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

{asher_cli-1.0.2 → asher_cli-1.1.0}/.github/workflows/release.yml

@@ -44,26 +44,29 @@ jobs:
     needs: [build, publish]
     runs-on: ubuntu-latest
     steps:
-      # Full history (fetch-depth: 0) so git-cliff can walk commits/tags.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          fetch-depth: 0
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
         with:
           name: dist
           path: dist/
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
-      - name: Install git-cliff
-        run: uv tool install git-cliff
-      - name: Generate release notes with git-cliff
+      - name: Extract release notes from CHANGELOG.md
         env:
           VERSION: ${{ needs.build.outputs.version }}
         run: |
-          # Explicit -c cliff.toml avoids auto-discovering pyproject.toml.
-          # Pin the just-released version so git-cliff groups its commits under
-          # the right heading even before the tag is fetched, then emit only
-          # that section (--latest) with the header stripped.
-          git cliff -c cliff.toml --tag "v${VERSION}" --latest --strip header -o RELEASE_NOTES.md
+          # CHANGELOG.md is the single source of release prose: it is generated
+          # by git-cliff (see `poe changelog-release`) but may be hand-refined
+          # before the release is cut, and re-deriving the notes from commits
+          # here would silently discard those edits.
+          awk -v hdr="## [${VERSION}]" '
+            index($0, hdr) == 1              { found = 1; next }
+            found && index($0, "## [") == 1  { exit }
+            found                            { print }
+          ' CHANGELOG.md > RELEASE_NOTES.md
+          if [ ! -s RELEASE_NOTES.md ]; then
+            echo "::error::CHANGELOG.md has no '## [${VERSION}]' section." \
+                 "Run 'uv run poe changelog-release ${VERSION}' and commit it before releasing."
+            exit 1
+          fi
       - name: Create release
         env:
           GH_TOKEN: ${{ github.token }}

{asher_cli-1.0.2 → asher_cli-1.1.0}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
+## [1.1.0] - 2026-08-09
+
+### 🚀 Features
+
+- *(headless)* Every robot command now runs without the TUI as `asher <command>`, with `--json` output and `--robot` selection; `--export` stays as a deprecated alias
+- *(theme)* Catppuccin Mocha throughout — one palette in `asher/theme.py` drives the TUI stylesheet and every Rich style, replacing ad-hoc hexes across eleven modules
+
+### 📚 Documentation
+
+- Point CLAUDE.md at the release process
+
+### 👷 CI/CD
+
+- *(release)* Build release notes from CHANGELOG.md
+
+### 🔧 Miscellaneous
+
+- Trim CLAUDE.md, split MCP bridge docs into a skill, fix env-guard hook
+
 ## [1.0.2] - 2026-08-05
 
 ### 🐛 Bug Fixes
@@ -23,10 +42,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 - *(history)* Copy-to-clipboard + discoverable footer hints
 
-### 📚 Documentation
-
-- *(changelog)* Cut v1.0.1
-
 ## [1.0.0] - 2026-08-02
 
 ### 🚀 Features
@@ -38,7 +53,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 ### 📚 Documentation
 
-- *(changelog)* Regenerate for next release, trim duplicate README list
 - *(roadmap)* Archive completed sections to docs/roadmap-archive/
 
 ### 🔧 Miscellaneous
@@ -57,7 +71,6 @@ Generated by [git-cliff](https://git-cliff.org) from conventional commits.
 
 ### 📚 Documentation
 
-- *(changelog)* Cut v0.2.0
 - *(commands)* Sync stale command lists in CLAUDE.md and slash-commands docstring
 - *(readme)* Sync command tables with code, add changelog
 

{asher_cli-1.0.2 → asher_cli-1.1.0}/CLAUDE.md

@@ -4,21 +4,9 @@ Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API.
 
 ## Stack
 
-- **Python 3.10+**
-- **Textual** — async TUI framework (`textual>=0.47`)
-- **pylitterbot** — unofficial Whisker API wrapper (`pylitterbot>=3.0`)
-- **python-dotenv** — credential loading (`.env` fallback)
-- **keyring>=24** — OS credential store (Windows Credential Manager / macOS Keychain / Linux Secret Service)
-
-## Tooling
-
-- **uv** — dependency management and task runner (`uv sync`, `uv run`)
-- **poethepoet** — task aliases via `uv run poe <task>`
-- **ruff** — linter and formatter
-- **mypy** — static type checking
-- **pytest + pytest-asyncio + pytest-cov** — tests
-- **textual-dev** — CSS hot reload devtools
-- **watchfiles** — Python auto-restart on file change
+- **keyring** resolves to the OS-native credential store: Windows Credential Manager / macOS Keychain / Linux Secret Service.
+
+See `pyproject.toml` for the full dependency and dev-tooling list (`[project].dependencies`, `[dependency-groups].dev`, `[tool.poe.tasks]`).
 
 ## Entry points
 
@@ -37,6 +25,7 @@ asher/
   auth.py           LoginScreen modal (ModalScreen[tuple[str,str]]) — available, not primary flow
   helpers.py        fmt_ago(), drawer_bar(), ts(), robot_model()  (pure, testable)
   constants.py      STATUS_COLORS, ROBOT_MODELS
+  theme.py          Catppuccin Mocha palette + semantic roles (BACKGROUND, MUTED, DANGER, …) + CSS_VARIABLES/apply() — the only place a hex literal belongs
   config.py         runtime settings persistence — load()/save()/update() over ~/.asher-cli/config.json; holds poll interval, cat-panel visibility/colour, active pet index, notification settings (non-secret UI prefs only; credentials stay in keyring)
   notifications.py  desktop toast + audible alert façade over plyer (fire/beep, always-safe no-op on failure/headless)
   cats.py           CATS dict (ASCII art)
@@ -47,9 +36,10 @@ asher/
   mcp_bridge.py     asher-mcp-launch console script — keyring-backed pylitterbot MCP launcher
   faults.py         check_faults(robot) — model-scoped safety/component fault detection (status enum + per-model attr allowlist incl. LR4 USB power fault; hopper never a fault)
   history_view.py   HistoryScreen (ModalScreen) + format_history_rows()/format_history_text() — scrollable activity-history pager pushed by the `history` command; `c` copies the full history (plain text) to the clipboard via action_copy_all()
-  export.py         shared activity-history CSV core + headless export path: build_history_csv(), resolve_dest(), resolve_robot(), _run_headless_export(), ExportError — no Textual imports; both the TUI `export` command and `asher --export` call build_history_csv()
+  export.py         shared activity-history CSV core + exit-code contract: build_history_csv(), resolve_dest(), resolve_robot(), parse_days(), EXIT_*, ExportError — no Textual imports; the TUI `export` command and `asher export` both call build_history_csv()
+  headless.py       headless command surface for `asher <command>` — Session/Result/CommandError, the COMMANDS registry, and run(); plain strings only, no Textual, routes model differences through RobotAdapter
   completion.py     pure helpers for command completion: slash popup (slash_matches, enter_completes, render_completion) + inline ghost text (CommandSuggester) — fed by _registry, no Textual imports except the Suggester base class
-  __main__.py       main() entry point
+  __main__.py       main() entry point — argparse subcommands (headless) vs no-args (TUI); `--export` kept as a deprecated alias
   commands/
     base.py         Command ABC, SlashCommand, CommandRegistry
     __init__.py     CommandsMixin — all command classes + registry + dispatch
@@ -76,7 +66,8 @@ tests/
   test_mcp_command.py     /mcp slash command dispatch
   test_faults.py          check_faults() — safety statuses, attribute faults, graceful degradation
   test_history_view.py    format_history_rows()/format_history_text() + HistoryScreen structure, copy-all + Pilot push/dismiss
-  test_export.py          build_history_csv/resolve_dest/resolve_robot/parse_days (pure) + headless _run_headless_export (no Pilot, mocks _connect_headless)
+  test_export.py          build_history_csv/resolve_dest/resolve_robot/parse_days (pure) + the legacy `--export` flag path (no Pilot, mocks _connect_headless)
+  test_headless.py        headless registry/rendering (pure) + every command handler against mock robots + run() exit codes + the argparse subcommand surface
   test_completion.py      slash_matches/enter_completes/render_completion (pure) + Pilot overlay visibility/navigation/accept
 
 .github/workflows/
@@ -101,32 +92,22 @@ LITTER_ROBOT_PASSWORD=...
 Keyring service name: `asher-cli`, keys `email` and `password`.
 Helper functions in `asher/connection/__init__.py`: `_keyring_load()`, `_keyring_save()`, `_keyring_delete()`.
 
-## MCP bridge (`/mcp`)
-
-pylitterbot ships an optional MCP server (`pip install pylitterbot[mcp]`, run via `python -m pylitterbot.mcp`) that lets an MCP client like Claude Desktop monitor/control the robot directly. Its own docs configure it with plaintext credentials in the client's JSON config — asher-cli avoids that:
-
-- `/mcp on|off|status` (in `asher/commands/__init__.py`, logic in `asher/mcp_config.py`) adds/removes an entry (named by `mcp_config._SERVER_NAME`) in every `claude_desktop_config.json` this OS's Claude Desktop might read (`mcp_config.config_paths()` — on Windows this includes both the standard installer path and any MSIX/Microsoft Store virtualized path). The entry's `command` is `sys.executable -m asher.mcp_bridge` — never the credentials themselves.
-- `/mcp on` also auto-installs pylitterbot's `mcp` extra via `sys.executable -m pip install "pylitterbot[mcp]==<installed version>"` if the `mcp` package isn't importable yet.
-- `asher/mcp_bridge.py` (console script `asher-mcp-launch`) is what Claude Desktop actually spawns. It reads email/password from the OS keyring at process start, sets them as `LITTER_ROBOT_USERNAME`/`LITTER_ROBOT_PASSWORD` (pylitterbot's expected names — note these differ from asher-cli's own `.env` var `LITTER_ROBOT_USER`) in that process's environment only, then execs `python -m pylitterbot.mcp`. No credentials ever touch the on-disk MCP config.
-- `/mcp on` requires keyring credentials. If none are found but `.env` fallback credentials are set, it copies them into the keyring automatically (since the bridge process can't reliably discover a project-relative `.env` — Claude Desktop controls its working directory, not asher-cli).
-- Requires the `mcp` extra: `uv sync --extra mcp` / `pip install asher-cli[mcp]`. Restart Claude Desktop after toggling for the change to take effect.
-
 ## Command convention
 
-**Normal commands** (no prefix) — robot actions only:
-`clean`, `status`, `info`, `lock`, `unlock`, `sleep`, `wake`, `night-light on|off|auto`, `night-light-brightness <level>`, `panel-brightness <low|medium|high>`, `wait-time <minutes>`, `power on|off`, `rename <name>`, `insight [days|month]`, `sleep-schedule`, `privacy on|off`, `volume <0-100>`, `camera-audio on|off`, `drawer-reset`, `history [count|all]`, `export [days|month]`, `clear`, `help`, `quit`
+Command names, slash-command names, and their args are not listed here — see the `_registry` in `asher/commands/__init__.py`, which is authoritative; `/help` renders it at runtime. `/mcp`'s credential-bridging design is documented in the `mcp-bridge` skill.
 
-**Slash commands** (`/` prefix) — app management only:
-`/login`, `/logout`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|colour <hex>`, `/refresh [seconds|off]`, `/config`, `/notify on|off|sound on|off|test`, `/version`, `/mcp on|off|status`, `/exit`
+**Normal commands** (no prefix) are robot actions only; **slash commands** (`/` prefix) are app management only.
 
 `/refresh`, `/cat`, `/pet`, and `/notify` persist their settings to `~/.asher-cli/config.json` (via `asher.config.update()`), so they survive restarts. Credentials and the preferred-robot serial stay in the OS keyring; the config file holds only non-secret UI preferences.
 
-> The authoritative list is the `_registry` in `asher/commands/__init__.py`; `/help` renders it at runtime. If you add a command, update the tables in `README.md` and the list in `asher/slash-commands/__init__.py`.
+Do not add robot-control commands as slash commands, and do not add app-management commands as bare commands.
 
 **Special cases** (accepted both with and without `/`):
 `exit`, `quit`, `q` — exit the app
 
-Do not add robot-control commands as slash commands, and do not add app-management commands as bare commands.
+**Headless commands** (`asher <command>`) are a parallel registry in `asher/headless.py`: same robot actions, no Textual, plain-string + JSON output. Slash commands have no headless equivalent — they configure the TUI, which isn't running. A robot command worth scripting should exist in both registries; the shared logic lives in `RobotAdapter`, not in either command class.
+
+> If you add a command, update the tables in `README.md` and the list in `asher/slash-commands/__init__.py`. If it's a robot command, consider adding it to `COMMANDS` in `asher/headless.py` too.
 
 ## Architecture
 
@@ -175,17 +156,15 @@ LoginScreen (ModalScreen) — available in auth.py but not the primary auth path
 
 ## Robot compatibility
 
-pylitterbot auto-detects robot type. Commands that differ per model are handled by `RobotAdapter` subclasses in `robot_adapters.py` — `make_adapter(robot)` returns the right one based on `type(robot).__name__`. Status-bar reads use `getattr(..., default)` for graceful degradation on older models. Tested API surface:
+pylitterbot auto-detects robot type. Commands that differ per model are handled by `RobotAdapter` subclasses in `robot_adapters.py` — `make_adapter(robot)` returns the right one based on `type(robot).__name__`. Status-bar reads use `getattr(..., default)` for graceful degradation on older models. See the `pylitterbot-ref` skill for the confirmed API surface.
 
-- `robot.name`, `robot.serial`, `robot.is_online`
-- `robot.status` (LitterBoxStatus enum)
-- `robot.waste_drawer_level` (0–100)
-- `robot.sleep_mode_enabled`, `robot.panel_lock_enabled`, `robot.night_light_mode_enabled`
-- `robot.last_seen` (datetime)
-- `robot.refresh()`, `robot.start_cleaning()`
-- `robot.set_sleep_mode(bool)`, `robot.set_panel_lockout(bool)`
-- `robot.set_night_light_brightness(int)` or `robot.set_night_light_mode(NightLightMode)`
-- `robot.get_activity_history(limit=int)` → list of `Activity` objects with `.timestamp` and `.action` (`LitterBoxStatus` enum)
+## Colour
+
+Every colour comes from `asher/theme.py` (Catppuccin Mocha). Reference the **semantic roles** (`theme.MUTED`, `theme.DANGER`, …), not the raw swatches (`theme.OVERLAY0`) and never a hex literal — a re-flavour then only repoints the roles.
+
+- **Rich styles:** `style=theme.ACCENT`, or `style=f"bold {theme.ACCENT}"`. Prefer building `Text` objects with explicit styles over `Text.from_markup` with inline colours.
+- **`ui/style.tcss`:** use the `$asher-*` variables; `AsherApp.get_css_variables()` supplies them.
+- **Inline `CSS`/`DEFAULT_CSS` on a Screen or Widget:** wrap the block in `theme.apply(...)`, which bakes the `$asher-*` values in at class-definition time. A screen mounted on a host app that isn't `AsherApp` (as the Pilot tests do) would otherwise fail to parse.
 
 ## Code comments
 
@@ -213,6 +192,8 @@ Commands that need a confirmed cloud state before showing a result (e.g. sleep/w
 
 **Add a slash command:** create a class inheriting `SlashCommand` (sets `prefix = "/"`), implement `async def run(self, app, args)`, register it, and document in `asher/slash-commands/__init__.py`.
 
+**Add a headless command:** write `async def _my_command(session, args) -> Result` in `asher/headless.py` and add a `HeadlessCommand(...)` entry to `COMMANDS`. The argparse subparser is generated from the registry — nothing to add in `__main__.py`. Build the `Result` with `_rows()` (read commands) or `_outcome()` (actions) so text and JSON stay in step, and raise `CommandError` rather than printing.
+
 **Change poll interval:** `self.set_interval(300, ...)` in `on_mount`.
 
 **Add a new cat state:** add entry to `CATS` dict in `asher/cats.py` (str for static, list[str] for animated), then call `_set_cat("name", "label")`.
@@ -221,18 +202,16 @@ Commands that need a confirmed cloud state before showing a result (e.g. sleep/w
 
 ## Dev workflow
 
-```bash
-uv sync                  # install all deps (including dev group)
-uv run poe dev           # run with CSS hot reload (textual --dev)
-uv run poe watch         # run with Python auto-restart on file change (watchfiles)
-uv run poe test          # run test suite
-uv run poe check         # ruff + mypy + pytest (same as CI)
-uv run poe fix           # auto-fix ruff issues
-uv run poe security      # bandit scan (same config the Bandit workflow uses)
-```
+See `[tool.poe.tasks]` in `pyproject.toml` for the full task list (`uv run poe <task>`).
 
 Pre-push hook (`.githooks/pre-push`) runs: ruff check → ruff format --check → mypy. Tests are not in the hook — run them manually.
 
+## Releasing
+
+Follow [README § Releasing](README.md#releasing) exactly, in order: `uv run poe changelog-release X.Y.Z` and commit the result → `uv run bump-my-version bump <part>` (this commits **and tags**) → `git push && git push --tags` → only then cut and push `release/X.Y.Z`.
+
+Regenerate with `changelog-release X.Y.Z`, never plain `changelog` — the workflow lifts the `## [X.Y.Z]` section out of the committed `CHANGELOG.md` verbatim for the GitHub Release body, and a file still saying `## [Unreleased]` fails the release job. That extraction is also why hand-refinements to a section survive into the release notes, and why re-running either changelog task afterwards silently discards them: regeneration always re-derives from commits. Refine last.
+
 ## Testing notes
 
 - Pilot-based integration tests use `app.run_test()` with `await pilot.pause()` before querying widgets

{asher_cli-1.0.2 → asher_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asher-cli
-Version: 1.0.2
+Version: 1.1.0
 Summary: Terminal dashboard for Litter Robot (LR3/LR4/LR5) via the Whisker cloud API
 Project-URL: Homepage, https://github.com/karanshukla/asher-cli
 Project-URL: Repository, https://github.com/karanshukla/asher-cli
@@ -75,7 +75,8 @@ A Claude Code-style terminal dashboard for monitoring and controlling Litter Rob
 - Slash commands for app management: `/login`, `/logout`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|colour <hex>`, `/refresh [seconds|off]`, `/config`, `/notify on|off|sound on|off|test`, `/version`, `/mcp on|off|status`, `/exit`
 - Slash-command tab completion — type `/` and a Claude Code-style overlay lists matching commands; `↑`/`↓` to move, `Tab` or `Enter` to accept, `Esc` to dismiss
 - Inline ghost-text completion for bare commands — type a prefix (`cle`) and the rest (`an`) appears greyed; `Tab` or `→` to accept → `clean`
-- Headless export — `asher --export 7` writes activity history to CSV from cron / Task Scheduler / SSH without launching the TUI
+- Headless mode — every robot command also runs without the TUI (`asher status`, `asher clean`, `asher night-light auto`, `asher export 7`), with `--json` output and documented exit codes for cron / Task Scheduler / SSH
+- Catppuccin Mocha throughout — one palette in `asher/theme.py` drives the TUI stylesheet and every Rich style
 - Cat animation panel that reacts to robot state
 - Command history (↑/↓ arrows)
 - Real-time updates via WebSocket; 5-minute poll fallback
@@ -177,38 +178,61 @@ LITTER_ROBOT_PASSWORD=yourpassword
 
 **Keyboard shortcuts:** `Ctrl+L` clears the log, `Ctrl+C` quits. While typing a `/` slash command, `↑`/`↓` move through completions, `Tab` or `Enter` accepts, `Esc` dismisses. While typing a bare command, a greyed ghost suggestion appears — `Tab` or `→` accepts it.
 
-### Headless export (cron / Task Scheduler / SSH)
+### Headless commands (cron / Task Scheduler / SSH)
 
-`--export` writes the same CSV as the `export` command **without launching the TUI** — so you can script activity-history exports from cron, Windows Task Scheduler, or a server over SSH. No flags launches the interactive dashboard as before.
+Every robot action the dashboard offers is also a subcommand that runs **without launching the TUI** — `asher` with no arguments still opens the interactive dashboard.
 
 ```bash
-asher --export 7                         export last 7 days to ~/Downloads
-asher --export 7 --output ~/hist.csv     explicit output path
-asher --export month --robot "Asher 2"   30 days (Whisker ceiling) for a specific robot
+asher status                             at-a-glance state
+asher info                               model, serial, firmware, settings
+asher clean                              start a clean cycle
+asher night-light auto                   set night light mode
+asher wait-time 7                        set the clean-cycle wait time
+asher history 20                         recent activity, newest first
+asher insight 7                          cycle-usage statistics
+asher export 7 --output ~/hist.csv       activity history to CSV
 ```
 
-`--robot` accepts an index or a partial, case-insensitive name (defaults to your saved preferred robot, else the first). Credentials use the same keyring → `.env` priority as the TUI, but with **no interactive login prompt** — a scheduled task can't type a password, so sign in once with `/login` first.
+`asher --help` lists every command; `asher <command> --help` shows its arguments. The full set: `status`, `info`, `robots`, `pets`, `history`, `insight`, `sleep-schedule`, `clean`, `lock`, `unlock`, `sleep`, `wake`, `night-light`, `night-light-brightness`, `panel-brightness`, `wait-time`, `power`, `rename`, `privacy`, `volume`, `camera-audio`, `drawer-reset`, `export`.
+
+Two flags apply to all of them:
+
+- `--robot <index|name>` — an index or a partial, case-insensitive name (defaults to your saved preferred robot, else the first)
+- `--json` — machine-readable output instead of aligned text, for piping into `jq`
+
+```bash
+asher status --json | jq -r '.drawer'
+asher history 50 --json | jq '[.events[] | select(.event | startswith("Cat"))] | length'
+```
+
+Credentials use the same keyring → `.env` priority as the TUI, but with **no interactive login prompt** — a scheduled task can't type a password, so sign in once with `/login` first.
 
 Exit codes for scripting:
 
 | Code | Meaning |
 |---|---|
-| `0` | export succeeded |
+| `0` | command succeeded |
 | `1` | no credentials found (keyring or `.env`) |
 | `2` | connection or API failure |
 | `3` | failed to write the CSV (permissions, disk full) |
 | `4` | `--robot` matched no robot on the account |
+| `5` | bad argument, or the robot/cloud rejected the command |
 
 ```bash
 # crontab — nightly export at 03:00
-0 3 * * * /usr/bin/env asher --export 7 --output /home/me/litter-history.csv >> /var/log/asher-export.log 2>&1
+0 3 * * * /usr/bin/env asher export 7 --output /home/me/litter-history.csv >> /var/log/asher-export.log 2>&1
+
+# alert when the drawer passes 85%
+0 * * * * [ "$(asher status --json | jq -r '.drawer' | tr -d %)" -gt 85 ] && notify-send "Litter drawer full"
 ```
 
 ```powershell
 # Windows Task Scheduler action
-asher.exe --export 7 --output C:\Users\me\litter-history.csv
+asher.exe export 7 --output C:\Users\me\litter-history.csv
 ```
 
+`asher --export [days]` remains as a deprecated alias for `asher export [days]`, so existing cron entries keep working.
+
 ## Configuration
 
 Runtime settings persist across restarts in `~/.asher-cli/config.json`, so you don't have to re-apply `/refresh 60`, `/cat colour #ff79c6`, or `/pet 1` every launch. The file is auto-created on first change and holds six non-secret UI preferences:
@@ -227,10 +251,11 @@ Credentials and the preferred-robot serial stay in the OS keyring; `.env` vars s
 ## Releasing
 
 ```bash
-# 1. regenerate CHANGELOG.md from conventional commits (idempotent), then commit it
-uv run poe changelog
+# 1. file the pending commits under the version you're about to cut, refine the
+#    prose if a squashed commit needs unpacking, then commit it
+uv run poe changelog-release X.Y.Z
 git add CHANGELOG.md
-git commit -m "docs(changelog): update for next release"
+git commit -m "docs(changelog): cut vX.Y.Z"
 
 # 2. bump version, commit, and tag in one step, then push with tags
 uv run bump-my-version bump patch    # 0.2.0 → 0.2.1
@@ -240,7 +265,7 @@ uv run bump-my-version bump major    # 0.2.0 → 1.0.0
 git push && git push --tags
 
 # 3. push the release branch to trigger PyPI publish (OIDC) + GitHub Release
-#    (release notes auto-generated by git-cliff from the same cliff.toml)
+#    (release notes = the `## [X.Y.Z]` section of CHANGELOG.md, verbatim)
 git checkout -b release/X.Y.Z
 git push origin release/X.Y.Z
 ```
@@ -250,6 +275,17 @@ conventional commits — see [`cliff.toml`](cliff.toml). Commit messages must us
 `feat:`/`fix:`/`docs:`/etc. prefixes (optionally scoped, e.g. `feat(robot):`)
 to appear in the changelog.
 
+Use `poe changelog-release X.Y.Z` — not plain `poe changelog` — when cutting a
+release. Both regenerate the whole file, but only the former files the pending
+commits under `## [X.Y.Z]` instead of `## [Unreleased]`, and the release
+workflow extracts exactly that section for the GitHub Release body. It fails
+loudly if the section is missing, so the notes can never come out stale.
+
+Because the workflow reads the committed file rather than re-deriving from
+commits, any hand-refinement you make to a section survives into the release
+notes — but re-running either task afterwards regenerates from commits and
+discards it. Refine last, right before committing.
+
 ## Troubleshooting
 
 **`asher` not found after `pip install asher-cli`**

{asher_cli-1.0.2 → asher_cli-1.1.0}/README.md

@@ -24,7 +24,8 @@ A Claude Code-style terminal dashboard for monitoring and controlling Litter Rob
 - Slash commands for app management: `/login`, `/logout`, `/robots`, `/robot <index|name>`, `/pets`, `/pet <index|name>`, `/cat on|off|colour <hex>`, `/refresh [seconds|off]`, `/config`, `/notify on|off|sound on|off|test`, `/version`, `/mcp on|off|status`, `/exit`
 - Slash-command tab completion — type `/` and a Claude Code-style overlay lists matching commands; `↑`/`↓` to move, `Tab` or `Enter` to accept, `Esc` to dismiss
 - Inline ghost-text completion for bare commands — type a prefix (`cle`) and the rest (`an`) appears greyed; `Tab` or `→` to accept → `clean`
-- Headless export — `asher --export 7` writes activity history to CSV from cron / Task Scheduler / SSH without launching the TUI
+- Headless mode — every robot command also runs without the TUI (`asher status`, `asher clean`, `asher night-light auto`, `asher export 7`), with `--json` output and documented exit codes for cron / Task Scheduler / SSH
+- Catppuccin Mocha throughout — one palette in `asher/theme.py` drives the TUI stylesheet and every Rich style
 - Cat animation panel that reacts to robot state
 - Command history (↑/↓ arrows)
 - Real-time updates via WebSocket; 5-minute poll fallback
@@ -126,38 +127,61 @@ LITTER_ROBOT_PASSWORD=yourpassword
 
 **Keyboard shortcuts:** `Ctrl+L` clears the log, `Ctrl+C` quits. While typing a `/` slash command, `↑`/`↓` move through completions, `Tab` or `Enter` accepts, `Esc` dismisses. While typing a bare command, a greyed ghost suggestion appears — `Tab` or `→` accepts it.
 
-### Headless export (cron / Task Scheduler / SSH)
+### Headless commands (cron / Task Scheduler / SSH)
 
-`--export` writes the same CSV as the `export` command **without launching the TUI** — so you can script activity-history exports from cron, Windows Task Scheduler, or a server over SSH. No flags launches the interactive dashboard as before.
+Every robot action the dashboard offers is also a subcommand that runs **without launching the TUI** — `asher` with no arguments still opens the interactive dashboard.
 
 ```bash
-asher --export 7                         export last 7 days to ~/Downloads
-asher --export 7 --output ~/hist.csv     explicit output path
-asher --export month --robot "Asher 2"   30 days (Whisker ceiling) for a specific robot
+asher status                             at-a-glance state
+asher info                               model, serial, firmware, settings
+asher clean                              start a clean cycle
+asher night-light auto                   set night light mode
+asher wait-time 7                        set the clean-cycle wait time
+asher history 20                         recent activity, newest first
+asher insight 7                          cycle-usage statistics
+asher export 7 --output ~/hist.csv       activity history to CSV
 ```
 
-`--robot` accepts an index or a partial, case-insensitive name (defaults to your saved preferred robot, else the first). Credentials use the same keyring → `.env` priority as the TUI, but with **no interactive login prompt** — a scheduled task can't type a password, so sign in once with `/login` first.
+`asher --help` lists every command; `asher <command> --help` shows its arguments. The full set: `status`, `info`, `robots`, `pets`, `history`, `insight`, `sleep-schedule`, `clean`, `lock`, `unlock`, `sleep`, `wake`, `night-light`, `night-light-brightness`, `panel-brightness`, `wait-time`, `power`, `rename`, `privacy`, `volume`, `camera-audio`, `drawer-reset`, `export`.
+
+Two flags apply to all of them:
+
+- `--robot <index|name>` — an index or a partial, case-insensitive name (defaults to your saved preferred robot, else the first)
+- `--json` — machine-readable output instead of aligned text, for piping into `jq`
+
+```bash
+asher status --json | jq -r '.drawer'
+asher history 50 --json | jq '[.events[] | select(.event | startswith("Cat"))] | length'
+```
+
+Credentials use the same keyring → `.env` priority as the TUI, but with **no interactive login prompt** — a scheduled task can't type a password, so sign in once with `/login` first.
 
 Exit codes for scripting:
 
 | Code | Meaning |
 |---|---|
-| `0` | export succeeded |
+| `0` | command succeeded |
 | `1` | no credentials found (keyring or `.env`) |
 | `2` | connection or API failure |
 | `3` | failed to write the CSV (permissions, disk full) |
 | `4` | `--robot` matched no robot on the account |
+| `5` | bad argument, or the robot/cloud rejected the command |
 
 ```bash
 # crontab — nightly export at 03:00
-0 3 * * * /usr/bin/env asher --export 7 --output /home/me/litter-history.csv >> /var/log/asher-export.log 2>&1
+0 3 * * * /usr/bin/env asher export 7 --output /home/me/litter-history.csv >> /var/log/asher-export.log 2>&1
+
+# alert when the drawer passes 85%
+0 * * * * [ "$(asher status --json | jq -r '.drawer' | tr -d %)" -gt 85 ] && notify-send "Litter drawer full"
 ```
 
 ```powershell
 # Windows Task Scheduler action
-asher.exe --export 7 --output C:\Users\me\litter-history.csv
+asher.exe export 7 --output C:\Users\me\litter-history.csv
 ```
 
+`asher --export [days]` remains as a deprecated alias for `asher export [days]`, so existing cron entries keep working.
+
 ## Configuration
 
 Runtime settings persist across restarts in `~/.asher-cli/config.json`, so you don't have to re-apply `/refresh 60`, `/cat colour #ff79c6`, or `/pet 1` every launch. The file is auto-created on first change and holds six non-secret UI preferences:
@@ -176,10 +200,11 @@ Credentials and the preferred-robot serial stay in the OS keyring; `.env` vars s
 ## Releasing
 
 ```bash
-# 1. regenerate CHANGELOG.md from conventional commits (idempotent), then commit it
-uv run poe changelog
+# 1. file the pending commits under the version you're about to cut, refine the
+#    prose if a squashed commit needs unpacking, then commit it
+uv run poe changelog-release X.Y.Z
 git add CHANGELOG.md
-git commit -m "docs(changelog): update for next release"
+git commit -m "docs(changelog): cut vX.Y.Z"
 
 # 2. bump version, commit, and tag in one step, then push with tags
 uv run bump-my-version bump patch    # 0.2.0 → 0.2.1
@@ -189,7 +214,7 @@ uv run bump-my-version bump major    # 0.2.0 → 1.0.0
 git push && git push --tags
 
 # 3. push the release branch to trigger PyPI publish (OIDC) + GitHub Release
-#    (release notes auto-generated by git-cliff from the same cliff.toml)
+#    (release notes = the `## [X.Y.Z]` section of CHANGELOG.md, verbatim)
 git checkout -b release/X.Y.Z
 git push origin release/X.Y.Z
 ```
@@ -199,6 +224,17 @@ conventional commits — see [`cliff.toml`](cliff.toml). Commit messages must us
 `feat:`/`fix:`/`docs:`/etc. prefixes (optionally scoped, e.g. `feat(robot):`)
 to appear in the changelog.
 
+Use `poe changelog-release X.Y.Z` — not plain `poe changelog` — when cutting a
+release. Both regenerate the whole file, but only the former files the pending
+commits under `## [X.Y.Z]` instead of `## [Unreleased]`, and the release
+workflow extracts exactly that section for the GitHub Release body. It fails
+loudly if the section is missing, so the notes can never come out stale.
+
+Because the workflow reads the committed file rather than re-deriving from
+commits, any hand-refinement you make to a section survives into the release
+notes — but re-running either task afterwards regenerates from commits and
+discards it. Refine last, right before committing.
+
 ## Troubleshooting
 
 **`asher` not found after `pip install asher-cli`**