Metadata-Version: 2.4
Name: xpoz-cli
Version: 0.1.0
Summary: Standalone CLI wrapper around the xpoz Python SDK.
Author: Xpoz
License: MIT License
        
        Copyright (c) 2026 Xpoz
        
        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.
        
Project-URL: Homepage, https://www.xpoz.ai
Project-URL: Repository, https://github.com/XPOZpublic/xpoz-cli
Project-URL: Issues, https://github.com/XPOZpublic/xpoz-cli/issues
Keywords: xpoz,cli,twitter,instagram,reddit,tiktok,social-media
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xpoz>=0.6.0
Dynamic: license-file

# xpoz-cli

Work seamlessly with [Xpoz](https://www.xpoz.ai) from the command line.

A single standalone binary that wraps the [Xpoz Python SDK](https://github.com/XPOZpublic/xpoz-python-sdk) and exposes every SDK method as a CLI subcommand — Twitter, Instagram, Reddit, TikTok, and tracking — with paginated result handling, CSV export, and persistent auth.

## Install

Grab a prebuilt binary from the [Releases page](https://github.com/XPOZpublic/xpoz-cli/releases) for your platform:

| Platform | Asset |
|---|---|
| Linux x86_64 | `xpoz-cli-linux-amd64` |
| Linux arm64 | `xpoz-cli-linux-arm64` |
| macOS Apple Silicon | `xpoz-cli-macos-arm64` |
| Windows x86_64 | `xpoz-cli-windows-amd64.exe` |

macOS Intel is not currently shipped as a prebuilt binary — install from source with `pip install xpoz` and run `python xpoz_cli.py` directly, or build locally with `pyinstaller --onefile xpoz_cli.py`.

```bash
# macOS / Linux
curl -L -o xpoz-cli https://github.com/XPOZpublic/xpoz-cli/releases/latest/download/xpoz-cli-linux-amd64
chmod +x xpoz-cli
sudo mv xpoz-cli /usr/local/bin/
```

Native package-manager distribution (Homebrew, apt, winget) is planned.

## Quick start

Authenticate once — your API key is stored at `~/.config/xpoz/config.json` (or `%APPDATA%\xpoz\config.json` on Windows) with mode `0600`:

```bash
xpoz-cli auth login
# Get your API key from: https://www.xpoz.ai/settings
# Open in browser? [Y/n]: y
# Paste your API key: xpz_...

xpoz-cli auth status
xpoz-cli auth logout
```

Then call any SDK method on any platform:

```bash
xpoz-cli twitter get_user --identifier elonmusk

xpoz-cli twitter search_posts \
    --query '"AI" AND ethics' \
    --start-date 2025-01-01 \
    --limit 20

xpoz-cli reddit search_posts \
    --query "python tutorial" \
    --subreddit learnpython \
    --sort top \
    --time month \
    --all-pages

xpoz-cli twitter search_posts --query bitcoin --export-csv-url
```

## Discovery

The CLI is generated by reflecting on the installed SDK, so every method the SDK exposes is automatically a subcommand. Use `--help` at any level to explore:

```bash
xpoz-cli --help                             # global options and platforms
xpoz-cli twitter --help                     # available methods on twitter
xpoz-cli twitter search_posts --help        # flags, types, and an example
```

Each method's help screen shows a synthesized example built from its required parameters.

## Global options

| Flag | Purpose |
|---|---|
| `--api-key KEY` | Override stored key (env: `XPOZ_API_KEY`) |
| `--server-url URL` | Custom MCP server (env: `XPOZ_SERVER_URL`) |
| `--output json\|pretty` | JSON output format (default `json`) |
| `--all-pages` | Walk every page of a paginated result |
| `--max-pages N` | Safety cap for `--all-pages` |
| `--page N` | Jump to a specific page |
| `--export-csv-url` | Return a CSV download URL instead of rows |
| `--timeout SECS` | Operation timeout (default `300`) |

API key precedence: `--api-key` flag → `XPOZ_API_KEY` env → stored config.

## Build from source

Requires Python 3.12+.

```bash
pip install xpoz pyinstaller
pyinstaller --onefile --name xpoz-cli xpoz_cli.py
./dist/xpoz-cli --help
```

Or run directly:

```bash
pip install xpoz
python xpoz_cli.py twitter get_user --identifier elonmusk
```

## Releases

Multi-platform binaries are built by the [`build-release` workflow](.github/workflows/release.yml), triggered by:

- **Git tag push** (`git tag v0.1.0 && git push origin v0.1.0`) — builds all targets and publishes a GitHub Release.
- **Manual run** via the Actions tab — same flow with a user-supplied tag and optional prerelease flag.

## License

MIT — see [LICENSE](LICENSE).
