Metadata-Version: 2.5
Name: vagary-cli
Version: 0.1.0
Summary: Command-line client for Vagary — search and browse your saved X.com posts.
Project-URL: Homepage, https://vagary.app
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Vagary CLI

Command-line client for [Vagary](https://vagary.app) — search and browse your saved X.com posts
(likes, bookmarks, your own posts) from the terminal.

```bash
uv tool install vagary-cli   # or: pipx install vagary-cli
vagary login                 # opens (or prints) a sign-in link you can use from ANY device — works over SSH
                             # tokens land in ~/.config/vagary/ (mode 0600)
vagary search "gpu shortage" --author @dylan522p --from 2026-01-01
vagary search "book covers" --images --media-type photo
vagary browse --source bookmark --pages 2
vagary stats
vagary whoami
```

Every command takes `--json` for the raw API response, so it composes with `jq`:

```bash
vagary browse --json | jq -r '.posts[].link_to_post'
```

For scripts and CI, set `VAGARY_TOKEN` to an access token instead of logging in.

## Notes on the data

- **Dates are when a post was written**, not when you liked or bookmarked it — filters, sorting
  and the `created_at` field all use the post's date.
- **Filters are hard constraints.** `--source` takes `like`, `bookmark`, `authored`, `retweet`;
  `--media-type` takes `photo`, `gif`, `video` (comma-separate for several). `--author` is one
  @handle.
- **Search** returns the most relevant `--limit` results (max 200) from a ranked pool capped at
  200; `total_found` in `--json` is that pool's size, not a count of every matching post. A post's
  `media_list` is ordered most-relevant-to-the-query first.
- **Browse** pages by post with no depth limit; `--pages N` follows the cursor. In `--images`
  mode every media item on the page's posts is returned.
- **Media URLs.** `meta.url` (photos) and `meta.preview_image_url` (video/GIF stills) are X's own
  media URLs; `meta.variants` holds a video's mp4/HLS renditions. `cached_gif_url` is our cached
  copy of a GIF's mp4 (X's GIF URLs have expired in the past) and `video_frame_url` a frame we
  extracted from a video (the query-winning frame in media search); both are null when not
  applicable.
- `--json` is the exact API response, unmodified — pipe it to `jq`.
