Installation

roost is a Python 3.10+ CLI published to PyPI as roost. There’s no Homebrew tap, no go install, no curl | sh script — install it the way you install any Python tool.

Install

uvx (recommended)

No install step at all. uv downloads roost into an ephemeral environment and runs it, caching it for next time:

uvx roost search "kyoto" --nights 3 --json

This is the right default for an agent invoking roost as a subprocess — nothing to provision ahead of time.

uv tool install

If you want roost on your PATH as a persistent command:

uv tool install roost
roost version

This is also the upgrade command — see Upgrading below.

pipx

pipx install roost
roost version

pip

pip install roost
roost version

Works, but prefer one of the isolated options above so roost’s dependencies (click, curl_cffi, selectolax, keyring) don’t land in a project environment you care about.

Note

Python 3.10 or newer is required. Any of the four methods above will refuse to install on an older interpreter.

Verify the install

Two commands confirm roost is installed and working:

roost version

{"version": "0.1.0"}

roost doctor

doctor checks backend reachability, throttle/circuit-breaker state, and auth — useful right after install because it also reports whether an OS keyring is available:

{
  "ok": true,
  "checks": [
    {"name": "backend:google", "ok": true, "detail": "google backend ready (keyless)"},
    {"name": "throttle", "ok": true, "detail": "closed; 0 request(s) in the last 10 min"},
    {"name": "auth", "ok": true, "detail": "default backend is keyless; serpapi key absent (optional)"},
    {"name": "keyring", "ok": true, "detail": "OS keyring available"}
  ]
}

If no OS keyring backend is present, doctor still reports ok: true for that check — it’s informational. roost falls back to a 0600 credentials file, and the default google backend needs no credentials at all.

What gets installed where

roost keeps two kinds of state, both under the XDG base directories, and touches nothing else on disk:

Path	Contents	Override
$XDG_STATE_HOME/roost/ratelimit.json	Politeness throttle state — last request time, recent-request window, circuit-breaker cooldown, per backend	ROOST_STATE_DIR
$XDG_STATE_HOME/roost/places.json	Cached location → Google place id, 30-day TTL	ROOST_STATE_DIR
$XDG_CONFIG_HOME/roost/credentials	Fallback store for the optional serpapi API key, 0600 permissions	XDG_CONFIG_HOME

XDG_STATE_HOME defaults to ~/.local/state and XDG_CONFIG_HOME defaults to ~/.config if unset, so on a stock Linux box that’s ~/.local/state/roost/ and ~/.config/roost/.

The serpapi credential itself prefers the OS keyring (service roost, username serpapi-key) over the file — the file is only written when no keyring backend is available. See Configuration for the full env var and precedence list.

Note

The state directory persisting across processes is deliberate, not incidental: an agent spawns a fresh roost process per call, so the throttle has to live on disk to mean anything. See Politeness.

Upgrading

roost version --check reports whether a newer release exists — it never installs it:

roost version --check

{
  "current": "0.1.0",
  "latest": "0.1.0",
  "updateAvailable": false,
  "upgrade": "uv tool install --upgrade roost"
}

The upgrade field is always the command to actually run — copy it and run it yourself, or have your agent run it. If the version check can’t reach the network (or the request times out), roost fails silently on the check itself and adds a note explaining that, rather than erroring the whole command.

To upgrade for real, run the command the tool matching how you installed it:

uv tool install --upgrade roost   # if installed with uv tool install
pipx upgrade roost                # if installed with pipx
pip install --upgrade roost       # if installed with pip

If you’re running via uvx roost ..., there’s nothing to upgrade explicitly — uvx resolves the latest published version on each cold run (subject to its own cache).

Uninstalling

Removing the package doesn’t remove roost’s on-disk state or credentials — clean those up separately if you want a full removal.

# remove the package (pick the one matching your install method)
uv tool uninstall roost
pipx uninstall roost
pip uninstall roost

# remove any stored serpapi credential — the local copy, not an upstream revocation
roost auth logout

# remove state and config directories
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/roost"
rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/roost"

roost auth logout only deletes the locally stored key (keyring entry and/or credentials file); it does not revoke the key with SerpApi. If you want it dead, revoke it from your SerpApi account too.

Next

• Quickstart — run your first search.
• For agents — wiring roost into an agent loop.
• Configuration — every env var and its precedence.