owlcast 0.1.0

Standalone CLI for fetching Owlcast data (features, pull requests, feature updates, mini-teams, threads).

owlcast-cli

Standalone CLI for fetching Owlcast data. Pure stdlib — no third-party dependencies.

Install

pip install owlcast

Authenticate

owlcast auth set-api-key

You'll be prompted for your API key (generate one in the Owlcast web UI). It's saved to ~/.config/owlcast/config.json (chmod 0600).

Alternatively, set OWLCAST_API_KEY in your environment, or pass --api-key on each call.

Fetch data

# List resources
owlcast features
owlcast pull-requests --filter state=open --limit 50
owlcast feature-updates --filter feature=<feature_id>
owlcast mini-teams
owlcast threads --filter provider=claude-code

# Short aliases work: prs, teams, updates, repos, orgs
owlcast prs --filter state=open

# Single item by id
owlcast features --id <uuid>

# Features as a hierarchical tree
owlcast features --tree
owlcast features --tree --markdown

Output is JSON on stdout by default — pipe into jq for ad-hoc queries.

Target a different server

owlcast features --local                 # http://localhost:9000
owlcast features --api-url https://...   # custom

Or set OWLCAST_API_URL.

Supported resources

Resource	Aliases	Allowed filters
features	feature	—
feature-updates	feature-update, updates	feature
pull-requests	pull-request, prs, pr	repository, state, author
mini-teams	mini-team, teams	repository
threads	thread	provider, session_id
repositories	repos	—
organizations	orgs	—
members	—	—

All data is scoped to the organization your API key belongs to.

Exit codes

• 0 — success
• 1 — error (missing key, invalid filter, HTTP failure, network error)

Relationship to the Owlcast desktop app

The Owlcast desktop app (codehs/owlcast-app) bundles its own copy of a larger CLI (threads/desktop_sync/cli.py from the main Owlcast repo) that handles thread-sync, background agent, and local-state commands in addition to get / auth. The desktop app's "Install CLI" button installs that bundled CLI to ~/.config/owlcast/cli/ and auto-updates it when the app starts a sync.

This standalone package (pip install owlcast) ships only get and auth — the pure API-client surface that doesn't need local sync infrastructure. It reads and writes the same ~/.config/owlcast/config.json, so an API key saved by either CLI works in both.

If you have the desktop app installed, you already have a working owlcast binary — no need to pip install owlcast unless you're scripting on a headless machine.