xpoz-cli 0.1.0

Standalone CLI wrapper around the xpoz Python SDK.

xpoz-cli

Work seamlessly with Xpoz from the command line.

A single standalone binary that wraps the 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 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.

# 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:

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:

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:

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

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

Or run directly:

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

Releases

Multi-platform binaries are built by the build-release workflow, 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.