xr-cli 0.1.0__tar.gz

xr_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.db

xr_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,94 @@
+# xr — Development Guide
+
+## What this is
+
+`xr` is a CLI tool for researching people and topics on X (Twitter) via the v2 API. Python package, pip-installable as `xr-cli`.
+
+## Project structure
+
+```
+src/xr/
+  __init__.py          # version
+  cli.py               # click entry point, wires all commands
+  auth.py              # credential loading (TOML, env, legacy) + bearer token
+  config.py            # TOML config with XDG paths + env overrides
+  api.py               # HTTP client with rate limit retry
+  cache.py             # SQLite cache with TTL per resource type
+  models.py            # dataclasses: Tweet, User, SearchResult, CountResult
+  commands/
+    tweet.py           # single tweet fetch + URL parsing
+    thread.py          # conversation reconstruction via search
+    search.py          # recent tweet search with caching
+    user.py            # profile lookup
+    timeline.py        # user timeline with filters
+    mentions.py        # user mentions
+    followers.py       # followers/following lists
+    counts.py          # tweet volume over time
+  formatters/
+    markdown.py        # markdown with YAML frontmatter
+    json_fmt.py        # JSON output
+tests/
+  conftest.py          # shared fixtures (sample API responses)
+  test_models.py
+  test_config.py
+  test_auth.py
+  test_api.py
+  test_cache.py
+  test_formatters.py
+  test_commands.py
+  test_cli.py
+```
+
+## Key patterns
+
+- **Commands expose `fetch_*` functions** — business logic separated from CLI wiring. `cli.py` imports and calls them.
+- **Cache-first**: every fetch function checks cache before hitting the API. Cache writes happen even with `--no-cache` (only reads are bypassed).
+- **Models parse API responses** via `from_api()` classmethods. Raw JSON stored in cache, models built at read time.
+- **Formatters are pure functions** — take model objects, return strings. No side effects.
+- **Rate limit retry** in `api.py` — auto-waits on 429, up to 3 attempts.
+
+## Running tests
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+All tests use mocks for API calls. No live API access needed for tests.
+
+## Auth
+
+Three credential sources, checked in order:
+1. Environment: `XR_CONSUMER_KEY` / `XR_CONSUMER_SECRET`
+2. TOML: `~/.config/xr/credentials.toml`
+3. Legacy: `~/charlie/.env.x-api` (Charlie-specific, backward compat)
+
+Bearer token is generated fresh each session via OAuth 2.0 client_credentials flow.
+
+## X API constraints
+
+- **Basic tier**: ~15,000 reads/month, 450 requests/15min per endpoint
+- **Search window**: 7 days only (recent search, not full archive)
+- **max_results**: minimum 10, maximum 100 per request
+- **Liked tweets endpoint**: requires User Context OAuth (not supported, app-only auth only)
+
+## Adding a new command
+
+1. Create `src/xr/commands/newcmd.py` with a `fetch_*` function
+2. Add click command in `cli.py` that calls it
+3. Add formatter function in `formatters/markdown.py` if needed
+4. Add cache methods in `cache.py` if caching a new resource type
+5. Write tests in `tests/test_commands.py`
+
+## Dependencies
+
+Minimal on purpose: `click`, `requests`, and stdlib (`tomllib`, `sqlite3`, `json`). No async, no ORM, no heavy frameworks.
+
+## Build and publish
+
+```bash
+pip install build twine
+python3 -m build
+twine upload dist/*
+```
+
+PyPI package name: `xr-cli`

xr_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hernan Carlos Caravario
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xr_cli-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: xr-cli
+Version: 0.1.0
+Summary: X (Twitter) research CLI — search, profile, timeline, cache
+Project-URL: Repository, https://github.com/hernan-cc/xr
+Author-email: Hernan Carlos Caravario <hernan@hernancc.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,cli,research,twitter,x
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# xr — X Research CLI
+
+Research people and topics on X (Twitter) from the command line.
+
+`xr` uses the X API v2 to search tweets, look up profiles, pull timelines, and track volume — all with SQLite caching so you don't burn through your API quota.
+
+## Install
+
+```bash
+pip install xr-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/hernan-cc/xr.git
+cd xr
+pip install -e .
+```
+
+## Setup
+
+You need X API credentials (Basic tier or higher). Get them at [developer.x.com](https://developer.x.com/en/portal/dashboard).
+
+```bash
+xr auth setup
+```
+
+This saves your Consumer Key and Secret to `~/.config/xr/credentials.toml` (mode 600).
+
+You can also use environment variables:
+
+```bash
+export XR_CONSUMER_KEY="your-key"
+export XR_CONSUMER_SECRET="your-secret"
+```
+
+## Commands
+
+### Search tweets
+
+```bash
+xr search "AI regulation" --top --max 20
+xr search "from:elonmusk has:links" --max 50
+xr search "startup funding" --lang en --no-rt --top
+```
+
+Supports all 47 X search operators. `--top` sorts by relevancy, default is recency. Search window is 7 days (API limitation).
+
+### User profile
+
+```bash
+xr user elonmusk
+xr user @naval
+```
+
+### Timeline
+
+```bash
+xr timeline paulg --top --no-rt --no-replies --max 20
+```
+
+`--top` sorts by likes. `--no-rt` excludes retweets. `--no-replies` excludes replies.
+
+### Single tweet
+
+```bash
+xr tweet https://x.com/user/status/1234567890
+xr tweet 1234567890
+```
+
+Accepts URLs or bare IDs.
+
+### Thread
+
+```bash
+xr thread https://x.com/user/status/1234567890
+xr thread 1234567890 --author-only
+```
+
+Reconstructs the full conversation. `--author-only` filters to just the thread author's tweets.
+
+### Mentions
+
+```bash
+xr mentions paulg --max 20
+```
+
+### Followers / Following
+
+```bash
+xr followers naval --max 100
+xr following naval --max 100
+```
+
+### Tweet volume
+
+```bash
+xr counts "bitcoin" --granularity day
+xr counts "AI agents" --granularity hour
+```
+
+Shows tweet volume over time. Useful for spotting trends.
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--pretty` | Output raw JSON instead of markdown |
+| `--save` | Save output to `~/.local/share/xr/` (or `XR_SAVE_DIR`) |
+| `--no-cache` | Bypass SQLite cache, force fresh API call |
+
+## Output
+
+Default output is markdown with YAML frontmatter:
+
+```
+---
+type: x-user
+username: naval
+user_id: "745273"
+date: 2026-02-21
+source: xr v0.1.0
+---
+
+# @naval (Naval)
+
+**Bio**: Angel investor, podcaster, ...
+**Joined**: 2007-02-05
+**Followers**: 2,100,000 | **Following**: 1,200
+**Tweets**: 15,000 | **Likes**: 24,000
+**URL**: https://x.com/naval
+```
+
+Use `--pretty` for JSON output (useful for piping to `jq`).
+
+## Cache
+
+API responses are cached in SQLite at `~/.cache/xr/cache.db` with sensible TTLs:
+
+| Resource | TTL |
+|----------|-----|
+| Tweets | 7 days |
+| Users | 24 hours |
+| Searches | 1 hour |
+| Counts | 1 hour |
+
+Use `--no-cache` to force a fresh API call (still writes to cache).
+
+## Configuration
+
+Optional config at `~/.config/xr/config.toml`:
+
+```toml
+[output]
+save_dir = "~/.local/share/xr"
+default_format = "markdown"
+
+[cache]
+enabled = true
+ttl_tweets = 604800
+ttl_users = 86400
+ttl_searches = 3600
+ttl_counts = 3600
+max_size_mb = 50
+
+[search]
+default_lang = ""
+default_max = 20
+```
+
+## API tier
+
+`xr` works with the X API v2 Basic tier ($200/month, ~15,000 reads/month). The cache helps you stay well under budget for research workflows.
+
+Rate limits are handled automatically — on HTTP 429, `xr` waits for the reset window and retries (up to 3 times).
+
+## Dependencies
+
+- `click` — CLI framework
+- `requests` — HTTP client
+- Python 3.11+ (uses `tomllib` from stdlib)
+
+No heavy dependencies. Fast install.
+
+## License
+
+MIT

xr_cli-0.1.0/README.md

@@ -0,0 +1,188 @@
+# xr — X Research CLI
+
+Research people and topics on X (Twitter) from the command line.
+
+`xr` uses the X API v2 to search tweets, look up profiles, pull timelines, and track volume — all with SQLite caching so you don't burn through your API quota.
+
+## Install
+
+```bash
+pip install xr-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/hernan-cc/xr.git
+cd xr
+pip install -e .
+```
+
+## Setup
+
+You need X API credentials (Basic tier or higher). Get them at [developer.x.com](https://developer.x.com/en/portal/dashboard).
+
+```bash
+xr auth setup
+```
+
+This saves your Consumer Key and Secret to `~/.config/xr/credentials.toml` (mode 600).
+
+You can also use environment variables:
+
+```bash
+export XR_CONSUMER_KEY="your-key"
+export XR_CONSUMER_SECRET="your-secret"
+```
+
+## Commands
+
+### Search tweets
+
+```bash
+xr search "AI regulation" --top --max 20
+xr search "from:elonmusk has:links" --max 50
+xr search "startup funding" --lang en --no-rt --top
+```
+
+Supports all 47 X search operators. `--top` sorts by relevancy, default is recency. Search window is 7 days (API limitation).
+
+### User profile
+
+```bash
+xr user elonmusk
+xr user @naval
+```
+
+### Timeline
+
+```bash
+xr timeline paulg --top --no-rt --no-replies --max 20
+```
+
+`--top` sorts by likes. `--no-rt` excludes retweets. `--no-replies` excludes replies.
+
+### Single tweet
+
+```bash
+xr tweet https://x.com/user/status/1234567890
+xr tweet 1234567890
+```
+
+Accepts URLs or bare IDs.
+
+### Thread
+
+```bash
+xr thread https://x.com/user/status/1234567890
+xr thread 1234567890 --author-only
+```
+
+Reconstructs the full conversation. `--author-only` filters to just the thread author's tweets.
+
+### Mentions
+
+```bash
+xr mentions paulg --max 20
+```
+
+### Followers / Following
+
+```bash
+xr followers naval --max 100
+xr following naval --max 100
+```
+
+### Tweet volume
+
+```bash
+xr counts "bitcoin" --granularity day
+xr counts "AI agents" --granularity hour
+```
+
+Shows tweet volume over time. Useful for spotting trends.
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--pretty` | Output raw JSON instead of markdown |
+| `--save` | Save output to `~/.local/share/xr/` (or `XR_SAVE_DIR`) |
+| `--no-cache` | Bypass SQLite cache, force fresh API call |
+
+## Output
+
+Default output is markdown with YAML frontmatter:
+
+```
+---
+type: x-user
+username: naval
+user_id: "745273"
+date: 2026-02-21
+source: xr v0.1.0
+---
+
+# @naval (Naval)
+
+**Bio**: Angel investor, podcaster, ...
+**Joined**: 2007-02-05
+**Followers**: 2,100,000 | **Following**: 1,200
+**Tweets**: 15,000 | **Likes**: 24,000
+**URL**: https://x.com/naval
+```
+
+Use `--pretty` for JSON output (useful for piping to `jq`).
+
+## Cache
+
+API responses are cached in SQLite at `~/.cache/xr/cache.db` with sensible TTLs:
+
+| Resource | TTL |
+|----------|-----|
+| Tweets | 7 days |
+| Users | 24 hours |
+| Searches | 1 hour |
+| Counts | 1 hour |
+
+Use `--no-cache` to force a fresh API call (still writes to cache).
+
+## Configuration
+
+Optional config at `~/.config/xr/config.toml`:
+
+```toml
+[output]
+save_dir = "~/.local/share/xr"
+default_format = "markdown"
+
+[cache]
+enabled = true
+ttl_tweets = 604800
+ttl_users = 86400
+ttl_searches = 3600
+ttl_counts = 3600
+max_size_mb = 50
+
+[search]
+default_lang = ""
+default_max = 20
+```
+
+## API tier
+
+`xr` works with the X API v2 Basic tier ($200/month, ~15,000 reads/month). The cache helps you stay well under budget for research workflows.
+
+Rate limits are handled automatically — on HTTP 429, `xr` waits for the reset window and retries (up to 3 times).
+
+## Dependencies
+
+- `click` — CLI framework
+- `requests` — HTTP client
+- Python 3.11+ (uses `tomllib` from stdlib)
+
+No heavy dependencies. Fast install.
+
+## License
+
+MIT

xr_cli-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xr-cli"
+version = "0.1.0"
+description = "X (Twitter) research CLI — search, profile, timeline, cache"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Hernan Carlos Caravario", email = "hernan@hernancc.com" }
+]
+keywords = ["twitter", "x", "research", "cli", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet",
+]
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+]
+
+[project.scripts]
+xr = "xr.cli:main"
+
+[project.urls]
+Repository = "https://github.com/hernan-cc/xr"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xr"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xr_cli-0.1.0/src/xr/__init__.py

@@ -0,0 +1,2 @@
+"""XR — X (Twitter) Research CLI."""
+__version__ = "0.1.0"

xr_cli-0.1.0/src/xr/api.py

@@ -0,0 +1,55 @@
+"""HTTP client for X API v2 with rate limit handling."""
+from __future__ import annotations
+import sys
+import time
+from typing import Any
+
+import requests
+
+API_BASE = "https://api.x.com/2"
+MAX_RETRIES = 3
+
+class APIError(Exception):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+class RateLimitError(APIError):
+    def __init__(self, reset_at: int):
+        self.reset_at = reset_at
+        super().__init__(429, f"Rate limited. Resets at {reset_at}")
+
+class XClient:
+    def __init__(self, bearer_token: str):
+        self.bearer_token = bearer_token
+
+    def _url(self, endpoint: str) -> str:
+        return f"{API_BASE}/{endpoint}"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.bearer_token}",
+            "User-Agent": "xr-cli/0.1.0",
+        }
+
+    def get(self, endpoint: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make GET request with retry on rate limit."""
+        url = self._url(endpoint)
+        for attempt in range(MAX_RETRIES):
+            resp = requests.get(url, headers=self._headers(), params=params, timeout=15)
+
+            if resp.ok:
+                return resp.json()
+
+            if resp.status_code == 429:
+                reset_at = int(resp.headers.get("x-rate-limit-reset", 0))
+                if attempt < MAX_RETRIES - 1:
+                    wait = max(reset_at - int(time.time()), 1) + 1
+                    print(f"Rate limited. Waiting {wait}s...", file=sys.stderr)
+                    time.sleep(wait)
+                    continue
+                raise RateLimitError(reset_at)
+
+            raise APIError(resp.status_code, resp.text)
+
+        raise APIError(0, "Max retries exceeded")

xr_cli-0.1.0/src/xr/auth.py

@@ -0,0 +1,77 @@
+"""Credential loading and bearer token generation."""
+from __future__ import annotations
+import base64
+import os
+import tomllib
+from pathlib import Path
+
+import requests
+
+class CredentialError(Exception):
+    pass
+
+def _credentials_path() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+    return Path(xdg) / "xr" / "credentials.toml"
+
+def _legacy_path() -> Path:
+    return Path.home() / "charlie" / ".env.x-api"
+
+def load_credentials(
+    path: Path | None = None,
+    legacy_path: Path | None = None,
+) -> tuple[str, str]:
+    """Load consumer key and secret. Priority: env vars > toml > legacy .env file."""
+    # 1. Environment variables
+    env_key = os.environ.get("XR_CONSUMER_KEY")
+    env_secret = os.environ.get("XR_CONSUMER_SECRET")
+    if env_key and env_secret:
+        return env_key, env_secret
+
+    # 2. TOML credentials file
+    cred_path = path or _credentials_path()
+    if cred_path.exists():
+        with open(cred_path, "rb") as f:
+            data = tomllib.load(f)
+        creds = data.get("credentials", {})
+        key = creds.get("consumer_key")
+        secret = creds.get("consumer_secret")
+        if key and secret:
+            return key, secret
+
+    # 3. Legacy .env.x-api
+    lp = legacy_path or _legacy_path()
+    if lp.exists():
+        kvs = {}
+        with open(lp) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)
+                    kvs[k.strip()] = v.strip()
+        key = kvs.get("X_API_CONSUMER_KEY")
+        secret = kvs.get("X_API_CONSUMER_SECRET")
+        if key and secret:
+            return key, secret
+
+    raise CredentialError(
+        "No X API credentials found. Run 'xr auth setup' or set "
+        "XR_CONSUMER_KEY and XR_CONSUMER_SECRET environment variables."
+    )
+
+def get_bearer_token(consumer_key: str, consumer_secret: str) -> str:
+    """Generate OAuth 2.0 Bearer Token from consumer credentials."""
+    credentials = f"{consumer_key}:{consumer_secret}"
+    b64 = base64.b64encode(credentials.encode()).decode()
+    resp = requests.post(
+        "https://api.x.com/oauth2/token",
+        headers={
+            "Authorization": f"Basic {b64}",
+            "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        },
+        data="grant_type=client_credentials",
+        timeout=10,
+    )
+    if not resp.ok:
+        raise CredentialError(f"Failed to get bearer token: {resp.status_code} {resp.text}")
+    return resp.json()["access_token"]