Asher CLI

A Claude Code-style terminal dashboard for monitoring and controlling Litter Robot via the Whisker cloud API.

Features

• Live status bar — unit name, online/offline, drawer fill level, last activity, cat weight
• Human-readable robot status — translates raw API states into plain English (Ready, Cleaning, Cat Detected, Drawer Full, etc.)
• Real-time cycling indicator with elapsed time (⟳ Cycling M:SS)
• Fault & safety monitoring — model-scoped in-panel alerts for cat detected, pinch, motor/position/gas faults (LR5: bonnet/laser/drawer); press d to dismiss
• Cat panel with mode label + status badges (status chip, lock, night light, sleep, wait time) under the art
• Scrollable activity-history pager — history [count|all] opens a full-screen, paginated view (arrow keys, Page Up/Page Down, Home/End); c copies the whole history to the clipboard; q/Esc/Enter to close
• Commands: clean, status, info, lock, unlock, sleep, wake, night-light on|off|auto, night-light-brightness, panel-brightness <low|medium|high> (LR4/LR5), wait-time, power on|off, rename, insight, sleep-schedule, plus LR5 extras (privacy, volume, camera-audio, drawer-reset), history [count|all], export [days|month], help, quit
• 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
• Cat animation panel that reacts to robot state
• Command history (↑/↓ arrows)
• Real-time updates via WebSocket; 5-minute poll fallback

Install

With pipx (recommended)

pipx install asher-cli
asher

pipx installs the CLI into an isolated environment and puts asher on your PATH automatically. Install pipx with pip install pipx if you don't have it.

With pip

pip install asher-cli
asher

With uv

uv tool install asher-cli
asher

Run from source

git clone https://github.com/karanshukla/asher-cli
cd asher-cli
uv sync
uv run asher

Credentials

On first run, type /login at the command prompt. Your credentials are saved to the OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service) and reused automatically on subsequent runs.

To sign out: /logout

.env fallback (for CI or existing users):

LITTER_ROBOT_USER=your@email.com
LITTER_ROBOT_PASSWORD=yourpassword

Commands

Robot commands

Slash commands

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)

--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.

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

--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.

Exit codes for scripting:

# 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

# Windows Task Scheduler action
asher.exe --export 7 --output C:\Users\me\litter-history.csv

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:

Credentials and the preferred-robot serial stay in the OS keyring; .env vars stay as env vars. You generally don't need to edit the file by hand — just use the slash commands — but it's plain JSON and safe to inspect or delete (deleting it restores defaults).

Releasing

# 1. regenerate CHANGELOG.md from conventional commits (idempotent), then commit it
uv run poe changelog
git add CHANGELOG.md
git commit -m "docs(changelog): update for next release"

# 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
uv run bump-my-version bump minor    # 0.2.0 → 0.3.0
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)
git checkout -b release/X.Y.Z
git push origin release/X.Y.Z

CHANGELOG.md is generated by git-cliff from conventional commits — see cliff.toml. Commit messages must use feat:/fix:/docs:/etc. prefixes (optionally scoped, e.g. feat(robot):) to appear in the changelog.

Troubleshooting

asher not found after pip install asher-cli

Python's Scripts folder isn't on your PATH. Use pipx instead — it handles this automatically:

pip install pipx
pipx install asher-cli
asher

If you're in a virtualenv, deactivate it first:

deactivate
pip install pipx
pipx install asher-cli

pipx: command not found

Run it as a module instead:

python -m pip install pipx
python -m pipx install asher-cli

Dev Setup

1. Clone and install

git clone https://github.com/karanshukla/asher-cli
cd asher-cli
uv sync                                        # installs all deps including the dev group
git config core.hooksPath .githooks            # lint + type checks run before every push

2. Configure environment (optional)

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

LITTER_ROBOT_USER=your@email.com
LITTER_ROBOT_PASSWORD=yourpassword
ASHER_CLI_DEV_MODE=true    # sets version to "dev" instead of the installed package version

3. Run with hot reload

CSS hot reload — Textual's devtools watch inline CSS strings and .tcss files and reload them in-place without restarting:

uv run poe dev
# equivalent to: textual run --dev asher/__main__.py

Python auto-restart — true in-process reload isn't possible with Textual's event loop, but watchfiles will kill and relaunch the app whenever a .py file changes in asher/:

uv run poe watch
# equivalent to: watchfiles --filter python 'python -m asher' asher

You can combine both — run poe watch for Python changes and it will naturally pick up CSS changes too on restart.

4. Run tests

uv run poe test                  # run all tests
uv run pytest tests/ --cov=asher # with coverage report

5. Lint, format, type-check

uv run poe fix     # auto-fix ruff issues
uv run poe lint    # check only (no fixes)
uv run poe fmt     # check formatting
uv run poe types   # mypy
uv run poe check   # run all of the above + tests (same as CI)

6. Security scan

uv run poe security # bandit, same config the Bandit workflow uses

Scan settings live in [tool.bandit] in pyproject.toml, so local runs and the Bandit workflow report identical findings. Results from main and pull requests are published to the repository's Security → Code scanning tab.

CI runs on Python 3.10 / 3.11 / 3.12 across Ubuntu, Windows, and macOS on every push.

Changelog

The full, maintained release history lives in CHANGELOG.md, auto-generated from conventional commits by git-cliff.

Notes

• Uses the unofficial pylitterbot library — supports LR3, LR4, LR5, and other Whisker robots
• The Whisker API is reverse-engineered and may change without notice
• Auth errors and network failures are shown in the UI with friendly messages