Metadata-Version: 2.4
Name: owlcast
Version: 0.1.0
Summary: Standalone CLI for fetching Owlcast data (features, pull requests, feature updates, mini-teams, threads).
Project-URL: Homepage, https://owlcast.fly.dev
Project-URL: Source, https://github.com/codehs/owlcast
Author-email: CodeHS <engineering@codehs.com>
License: Proprietary
Keywords: cli,codehs,owlcast
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# owlcast-cli

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

## Install

```bash
pip install owlcast
```

## Authenticate

```bash
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

```bash
# 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

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

