xpoz-cli

Work seamlessly with Xpoz 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)

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)

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)

brew install XPOZpublic/xpoz/xpoz-cli

The <owner>/<tap>/<formula> syntax auto-taps and installs in one step. Equivalent two-step form if you prefer:

brew tap XPOZpublic/xpoz
brew install xpoz-cli

Note: a bare brew install xpoz-cli won't work — the formula lives in our own tap, not in homebrew-core.

winget (Windows)

winget install Xpoz.XpozCli

(or winget install xpoz-cli once the manifest is published in microsoft/winget-pkgs).

pip (any platform with Python ≥3.10)

pip install xpoz-cli

Pulls the wheel from PyPI. 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:

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:

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:

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

Try it without signing up

Want to kick the tires first? Mint a free trial token — no sign-in required, valid for 5 days. It returns a limited set of results so you can see the CLI in action:

# Get a trial token (starts with "TRIAL")
curl -X POST https://api.xpoz.ai/api/trial/token \
  -H "Content-Type: application/json" \
  -d '{"source": "cli"}'
# -> { "success": true, "data": { "accessKey": "TRIAL...", "expiresInSeconds": 432000 }, ... }

export XPOZ_API_KEY=TRIAL...   # the token from the response above

xpoz-cli twitter get_user --identifier elonmusk

The source field is required — it just tells us where the trial request came from (e.g. skills, a specific page, sdk, cli).

Or pass it inline with --api-key:

xpoz-cli twitter get_user --identifier elonmusk \
    --api-key TRIAL...

For full results, grab your own API key and run xpoz-cli auth login.

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

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.