xcli-v2 0.1.0__tar.gz

xcli_v2-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+dist/
+build/

xcli_v2-0.1.0/.tasks/TODO.md

@@ -0,0 +1,23 @@
+# TODO
+
+## 2026-02-13
+
+- [x] Audit current CLI surface and relevant XDK endpoints.
+- [x] Expand `.tasks/backlog.md` into a detailed roadmap (phases, endpoint mapping, sequencing).
+- [x] Implement `xcli posts mine` and `xcli posts get --id <tweet_id>`.
+- [x] Implement `xcli timeline --user <handle>`.
+- [x] Implement auth UX improvements: `xcli auth status` and `xcli auth logout`.
+- [x] Implement media upload + attachment support in post/reply flows.
+- [x] Investigate tweet scheduling endpoint availability in public XDK/OpenAPI.
+- [x] Add tests for new functionality and run validation (`pytest`, `ruff`, `mypy`).
+
+### Notes
+
+- Existing commands are currently `compose`, `post`, `reply`, `quote`, and `auth` (`login`, `whoami`).
+- XDK supports required read endpoints: `users.get_posts`, `posts.get_by_id`, `users.get_timeline`, and `users.get_by_username`.
+- XDK OpenAPI includes Spaces `scheduled` state but no tweet scheduling field/path in post create APIs.
+- Media upload endpoint requires OAuth scope `media.write`; existing tokens without it must re-login.
+
+### Testing checklist
+
+- See `.tasks/notes/2026-02-13-testing-checklist.md` for the detailed checklist and live command validations.

xcli_v2-0.1.0/.tasks/backlog.md

@@ -0,0 +1,67 @@
+# xcli backlog
+
+## Roadmap
+
+### Endpoint inventory (XDK 0.8.x)
+
+Confirmed in the installed XDK client:
+
+- `client.users.get_me` -> authenticated user lookup.
+- `client.users.get_posts` -> user-authored posts (paginated iterator).
+- `client.posts.get_by_id` -> single post lookup.
+- `client.users.get_by_username` -> resolve `@handle` -> user id.
+- `client.users.get_timeline` -> reverse-chronological home timeline for a user id (paginated iterator).
+- `client.posts.create` -> create post/reply/quote.
+
+Scheduling note:
+
+- No native "scheduled post at timestamp" endpoint is exposed for posts in this XDK version.
+- `schedule/scheduled` terms currently appear in Spaces search state, not tweet create/update.
+- Treat tweet scheduling as API-capability investigation (possible private/limited-scope endpoint), not local queue emulation.
+
+### Phase 1: read + auth UX (active)
+
+1. Pull own recent tweets: `xcli posts mine`.
+2. Fetch a single tweet by id: `xcli posts get --id <tweet_id>`.
+3. Timeline lookup for a handle: `xcli timeline --user <handle>`.
+4. Better auth UX: `xcli auth logout` and `xcli auth status`.
+
+Done when:
+
+- Commands support both human output and `--json`.
+- Errors map to friendly messages (bad id, auth missing/expired, API errors).
+- Timeline and post-list commands respect a limit (`--limit`, sane defaults).
+
+### Phase 2: publish enhancements (active)
+
+1. Media upload + attach media to posts/replies.
+2. Validate media constraints and produce clear error messages.
+3. Keep `--dry-run` behavior useful when media is provided.
+
+Done when:
+
+- `xcli post ... --media <path> [--media <path>]` works for supported media.
+- Upload + create flow is atomic enough for CLI usage and surfaces upload failures.
+- Reply flow supports media attachment with same behavior.
+
+### Phase 3: stretch features
+
+1. Notifications/inbox command (investigate API support and tier access limits).
+2. Tweet scheduling command if/when API support is confirmed.
+3. Thread composer (`xcli thread create ...`).
+4. Shell completion + richer TUI-style previews.
+
+### OSS/release chores
+
+1. Add CI workflow for `ruff`, `mypy`, and `pytest`.
+2. Add changelog and release checklist.
+3. Add issue templates for bugs and feature requests.
+
+## Implementation notes
+
+- Keep command names lowercase and concise.
+- Reuse existing auth refresh and output helpers where possible.
+- Prefer atomic tasks with clean commit boundaries:
+  - `phase-1` command surface
+  - `phase-2` media upload + publish integration
+  - tests + docs updates

xcli_v2-0.1.0/.tasks/notes/2026-02-13-testing-checklist.md

@@ -0,0 +1,36 @@
+# Testing checklist (2026-02-13)
+
+## Automated checks
+
+- [x] `ruff check .`
+- [x] `python -m mypy src` (run via `.venv/bin/python -m mypy src`)
+- [x] `python -m pytest` (18 tests passing)
+
+## CLI surface checks
+
+- [x] `python -m xcli.cli --help`
+- [x] `python -m xcli.cli post --help`
+- [x] `python -m xcli.cli posts --help`
+- [x] `python -m xcli.cli auth --help`
+
+## Live API checks
+
+- [x] `xcli auth status --json`
+- [x] `xcli auth whoami --json`
+- [x] `xcli posts mine --limit 3 --json`
+- [x] `xcli posts get --id <id_from_mine> --json`
+- [x] `xcli timeline --user dremnik --limit 3 --json`
+
+## Optional follow-up checks
+
+- [ ] `xcli post "test" --media <image.png> --yes --json`
+- [ ] `xcli reply "test" --to <tweet_id> --media <image.png> --yes --json`
+- [ ] `xcli auth logout --json` then `xcli auth status --json`
+
+### Notes
+
+- Previous token scopes were missing `media.write` (`tweet.write users.read tweet.read offline.access`).
+- Added default scope `media.write` in config and CLI now returns a clear error if scope is missing.
+- After re-login, token includes `media.write`.
+- Media upload flow updated to use multipart form upload directly against `/2/media/upload`.
+- To complete media live checks: rerun the two media commands above with a normal local image file.

xcli_v2-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for helping improve `xcli`.
+
+## Local setup
+
+```bash
+pip install -e .[dev]
+```
+
+## Before opening a PR
+
+```bash
+ruff check
+mypy src
+pytest
+```
+
+## Commit style
+
+- Keep changes focused and atomic.
+- Add or update tests for behavior changes.
+- Update docs for any user-facing command changes.
+
+## Release process
+
+- Bump version in `pyproject.toml`.
+- Update `CHANGELOG.md`.
+- Tag the release in git.

xcli_v2-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Twitter CLI Contributors
+
+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.

xcli_v2-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: xcli-v2
+Version: 0.1.0
+Summary: Open-source CLI for composing and publishing X posts
+Author: Twitter CLI Contributors
+License: MIT
+License-File: LICENSE
+Keywords: automation,cli,social,twitter,x
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: platformdirs>=4.2.2
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: typer>=0.12.3
+Requires-Dist: xdk>=0.8.1
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.2; extra == 'dev'
+Requires-Dist: ruff>=0.6.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# xcli
+
+`xcli` is a command line tool for interacting with the X API.
+
+It is designed for local-first usage, safe publishing defaults, and open-source packaging.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install xcli-v2
+```
+
+## Quickstart
+
+1. Set OAuth app credentials:
+
+```bash
+export TWITTER_CLIENT_ID="..."
+export TWITTER_CLIENT_SECRET="..."
+```
+
+2. Run login flow:
+
+```bash
+xcli auth login
+```
+
+3. Draft content:
+
+```bash
+xcli compose "shipping small daily"
+```
+
+4. Post from terminal text (default):
+
+```bash
+xcli post "shipping small daily"
+```
+
+5. Preview without posting:
+
+```bash
+xcli post "shipping small daily" --dry-run
+```
+
+6. Post from file:
+
+```bash
+xcli post --file draft.txt
+```
+
+7. Attach media (repeat `--media` up to 4 files):
+
+```bash
+xcli post "launch day" --media image1.png --media image2.jpg
+```
+
+Currently supported media types are image uploads accepted by the X media upload endpoint (jpeg, png, webp, bmp, tiff).
+Media upload requires OAuth scope `media.write`; if you logged in before this was added,
+run `xcli auth login` again to refresh token scopes.
+
+## Commands
+
+- `xcli auth login`
+- `xcli auth whoami`
+- `xcli auth status`
+- `xcli auth logout`
+- `xcli compose`
+- `xcli post`
+- `xcli reply --to <tweet_id>`
+- `xcli quote --to <tweet_id>`
+- `xcli posts mine`
+- `xcli posts get --id <tweet_id>`
+- `xcli timeline --user <handle>`
+
+## Safety model
+
+- Posting commands send by default (with confirmation prompt).
+- Use `--dry-run` to preview payload without posting.
+- Non-interactive workflows can use `--yes`.
+- Machine output is available with `--json`.
+
+## Auth storage
+
+Default token path uses platform config directories:
+
+- macOS: `~/Library/Application Support/xcli/auth.json`
+- Linux: `~/.config/xcli/auth.json`
+- Windows: `%APPDATA%\\xcli\\auth.json`
+
+Legacy compatibility fallback is supported for `~/.twitter/auth.json`.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+ruff check
+mypy src
+```

xcli_v2-0.1.0/README.md

@@ -0,0 +1,102 @@
+# xcli
+
+`xcli` is a command line tool for interacting with the X API.
+
+It is designed for local-first usage, safe publishing defaults, and open-source packaging.
+
+## Install
+
+Install from PyPI:
+
+```bash
+pip install xcli-v2
+```
+
+## Quickstart
+
+1. Set OAuth app credentials:
+
+```bash
+export TWITTER_CLIENT_ID="..."
+export TWITTER_CLIENT_SECRET="..."
+```
+
+2. Run login flow:
+
+```bash
+xcli auth login
+```
+
+3. Draft content:
+
+```bash
+xcli compose "shipping small daily"
+```
+
+4. Post from terminal text (default):
+
+```bash
+xcli post "shipping small daily"
+```
+
+5. Preview without posting:
+
+```bash
+xcli post "shipping small daily" --dry-run
+```
+
+6. Post from file:
+
+```bash
+xcli post --file draft.txt
+```
+
+7. Attach media (repeat `--media` up to 4 files):
+
+```bash
+xcli post "launch day" --media image1.png --media image2.jpg
+```
+
+Currently supported media types are image uploads accepted by the X media upload endpoint (jpeg, png, webp, bmp, tiff).
+Media upload requires OAuth scope `media.write`; if you logged in before this was added,
+run `xcli auth login` again to refresh token scopes.
+
+## Commands
+
+- `xcli auth login`
+- `xcli auth whoami`
+- `xcli auth status`
+- `xcli auth logout`
+- `xcli compose`
+- `xcli post`
+- `xcli reply --to <tweet_id>`
+- `xcli quote --to <tweet_id>`
+- `xcli posts mine`
+- `xcli posts get --id <tweet_id>`
+- `xcli timeline --user <handle>`
+
+## Safety model
+
+- Posting commands send by default (with confirmation prompt).
+- Use `--dry-run` to preview payload without posting.
+- Non-interactive workflows can use `--yes`.
+- Machine output is available with `--json`.
+
+## Auth storage
+
+Default token path uses platform config directories:
+
+- macOS: `~/Library/Application Support/xcli/auth.json`
+- Linux: `~/.config/xcli/auth.json`
+- Windows: `%APPDATA%\\xcli\\auth.json`
+
+Legacy compatibility fallback is supported for `~/.twitter/auth.json`.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+ruff check
+mypy src
+```

xcli_v2-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xcli-v2"
+version = "0.1.0"
+description = "Open-source CLI for composing and publishing X posts"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Twitter CLI Contributors" },
+]
+keywords = ["x", "twitter", "cli", "automation", "social"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "platformdirs>=4.2.2",
+  "python-dotenv>=1.0.1",
+  "typer>=0.12.3",
+  "xdk>=0.8.1",
+]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.11.1",
+  "pytest>=8.3.2",
+  "ruff>=0.6.4",
+]
+
+[project.scripts]
+xcli = "xcli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xcli"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/xcli/cmd/*.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = "xdk"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "xdk.*"
+ignore_missing_imports = true

xcli_v2-0.1.0/src/xcli/__init__.py

@@ -0,0 +1,5 @@
+"""xcli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

xcli_v2-0.1.0/src/xcli/cli.py

@@ -0,0 +1,38 @@
+"""CLI entrypoint for xcli."""
+
+from __future__ import annotations
+
+import typer
+
+from xcli.cmd.auth import app as auth_app
+from xcli.cmd.compose import compose_cmd
+from xcli.cmd.posts import app as posts_app
+from xcli.cmd.publish import post_cmd, quote_cmd, reply_cmd
+from xcli.cmd.timeline import timeline_cmd
+from xcli.core.errors import XcliError
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Command line tool for interacting with the X API.",
+)
+
+app.add_typer(auth_app, name="auth")
+app.add_typer(posts_app, name="posts")
+app.command("compose")(compose_cmd)
+app.command("post")(post_cmd)
+app.command("reply")(reply_cmd)
+app.command("quote")(quote_cmd)
+app.command("timeline")(timeline_cmd)
+
+
+def main() -> None:
+    try:
+        app()
+    except XcliError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

xcli_v2-0.1.0/src/xcli/cmd/__init__.py

@@ -0,0 +1 @@
+"""Command modules for xcli."""

xcli_v2-0.1.0/src/xcli/cmd/auth.py

@@ -0,0 +1,124 @@
+"""Auth commands."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import typer
+
+from xcli.core.config import load_settings
+from xcli.core.errors import ApiError, AuthError
+from xcli.core.output import emit
+from xcli.core.session import make_authed_client
+from xcli.core.token_store import TokenStore
+from xcli.core.x_auth import run_login
+from xcli.core.x_client import get_me, make_user_client
+
+app = typer.Typer(no_args_is_help=True, help="Authenticate xcli with the X API.")
+
+
+@app.command("login")
+def login(
+    no_browser: bool = typer.Option(False, help="Do not auto-open a browser."),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    settings = load_settings()
+    token = run_login(settings, open_browser=not no_browser)
+
+    store = TokenStore()
+    store.save(token)
+
+    out: dict[str, object] = {
+        "message": "Login successful.",
+        "token_path": str(store.primary),
+    }
+
+    access_token = token.get("access_token")
+    if isinstance(access_token, str) and access_token:
+        try:
+            client = make_user_client(access_token)
+            me = get_me(client)
+            out["username"] = me.get("username")
+            out["name"] = me.get("name")
+            out["id"] = me.get("id")
+        except ApiError as exc:
+            out["message"] = (
+                "Login successful, but profile lookup failed. "
+                "Run `xcli auth whoami` to retry."
+            )
+            out["warning"] = str(exc)
+
+    emit(out, json_output=json_output)
+
+
+@app.command("whoami")
+def whoami(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    client = make_authed_client()
+    me = get_me(client)
+
+    emit(
+        {
+            "message": "Authenticated user:",
+            "username": me.get("username"),
+            "name": me.get("name"),
+            "id": me.get("id"),
+        },
+        json_output=json_output,
+    )
+
+
+@app.command("status")
+def status(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    store = TokenStore()
+    token = store.load()
+    if not token:
+        emit(
+            {
+                "message": "Not authenticated.",
+                "logged_in": False,
+                "token_path": str(store.primary),
+            },
+            json_output=json_output,
+        )
+        return
+
+    out: dict[str, object] = {
+        "message": "Authentication status:",
+        "logged_in": bool(token.get("access_token")),
+        "token_path": str(store.primary),
+    }
+
+    expires_at = token.get("expires_at")
+    if isinstance(expires_at, (int, float)):
+        out["expires_at"] = datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat()
+
+    try:
+        client = make_authed_client()
+        me = get_me(client)
+        out["username"] = me.get("username")
+        out["name"] = me.get("name")
+        out["id"] = me.get("id")
+    except (AuthError, ApiError) as exc:
+        out["warning"] = str(exc)
+
+    emit(out, json_output=json_output)
+
+
+@app.command("logout")
+def logout(
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    store = TokenStore()
+    removed = store.clear()
+
+    out: dict[str, object] = {
+        "message": "Logged out." if removed else "No token files found. Already logged out.",
+        "count": len(removed),
+        "token_path": str(store.primary),
+        "removed": [str(path) for path in removed],
+    }
+    emit(out, json_output=json_output)