Metadata-Version: 2.4
Name: xpoz-cli
Version: 0.3.3
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.10
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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: xpoz>=0.6.3
Requires-Dist: exceptiongroup>=1.0; python_version < "3.11"
Dynamic: license-file

# xpoz-cli

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

Get data and insights from Twitter/X, Instagram, TikTok, Reddit and others social media with paginated result handling, CSV export, and persistent auth.

## Install

### One-liner (Linux/macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/XPOZpublic/xpoz-cli/main/install.sh | sh
```

Auto-detects your OS and CPU architecture, downloads the matching binary from GitHub Releases, verifies its SHA256, and drops it in `~/.local/bin/xpoz-cli`. Override the install dir with `XPOZ_INSTALL_DIR=/usr/local/bin`, or pin a version with `XPOZ_VERSION=v0.2.0`.

### One-liner (Windows, PowerShell)

```powershell
iwr -useb https://raw.githubusercontent.com/XPOZpublic/xpoz-cli/main/install.ps1 | iex
```

Same idea — installs to `%LOCALAPPDATA%\xpoz-cli\xpoz-cli.exe` and prints the one PATH command you need to run if it isn't already on your PATH.

### Homebrew (macOS / Linux)

```bash
brew tap XPOZpublic/xpoz
brew install xpoz-cli
```

Or in one line: `brew install XPOZpublic/xpoz/xpoz-cli`.

### winget (Windows)

```cmd
winget install Xpoz.XpozCli
```

(or `winget install xpoz-cli` once the manifest is published in [`microsoft/winget-pkgs`](https://github.com/microsoft/winget-pkgs)).

### pip (any platform with Python ≥3.10)

```bash
pip install xpoz-cli
```

Pulls the wheel from [PyPI](https://pypi.org/project/xpoz-cli/). Requires Python on the user's machine; the other channels above bundle Python via PyInstaller.

### Manual download

Pick the asset matching your platform from the [Releases page](https://github.com/XPOZpublic/xpoz-cli/releases):

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

Each release also publishes `SHA256SUMS` for offline verification:

```bash
curl -fsSLO https://github.com/XPOZpublic/xpoz-cli/releases/latest/download/xpoz-cli-linux-amd64
curl -fsSLO https://github.com/XPOZpublic/xpoz-cli/releases/latest/download/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
chmod +x xpoz-cli-linux-amd64 && sudo mv xpoz-cli-linux-amd64 /usr/local/bin/xpoz-cli
```

macOS Intel is not currently shipped as a prebuilt binary — use `pip install xpoz-cli` instead.

## 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.10+.

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