xcli

Quick start

bun link
xcli --help

Core workflows (primary)

Get liked posts:

xcli likes list --user me --limit 20

Get bookmarked posts:

xcli bookmarks list --user me --limit 20

Search recent posts:

xcli search posts "gamedev lang:en" --limit 20 --sort recency

Pagination + script-friendly output:

# stable URLs only
xcli likes list --plain

# machine output
xcli bookmarks list --json

# continue from previous response.paging.nextCursor
xcli search posts "gamedev" --limit 20 --cursor <next_token> --json

Time-bounded search:

xcli search posts "indie game" --since 2026-02-01T00:00:00Z --until 2026-02-18T23:59:59Z

Usage monitoring (app token)

xcli usage needs an app bearer token (app-token), not a user token.

xcli config set app-token "$X_APP_TOKEN"

xcli usage
xcli usage --days 30
xcli usage --days 30 --fields project_id,project_usage,project_cap,cap_reset_day --json

One-time setup (short)

Initialize config:

xcli config init
xcli config init --force
xcli cfg path

xcli config init is interactive on TTY (confirm create/overwrite). Wizard prompts for client-id, client-secret, redirect-uri, endpoint, and app-token. Press Enter to keep current/default value, or - to clear.

Save OAuth app credentials:

xcli config set client-id "$X_CLIENT_ID"
xcli config set client-secret "$X_CLIENT_SECRET"

redirect-uri is optional if you use default http://127.0.0.1:3000/callback.

Run OAuth login flow once:

xcli auth doctor
xcli auth login
xcli auth whoami

Precedence: env > config. OAuth callback page shows a confirmation message in browser.

Auth toolbox (advanced/manual flow)

xcli auth pkce new
xcli auth authorize-url --open
xcli auth callback listen
xcli auth token-exchange
xcli auth refresh

Commands

• xcli likes list: list liked posts for a user (me or user id).
• xcli bookmarks list: list bookmarked posts for a user (me or user id).
• xcli search posts: search recent global posts by query (--limit is 10..100).
• xcli usage: project usage metrics from X API usage endpoint (/2/usage/tweets).
• xcli config init|path|get|set|unset: manage local XDG config.
• xcli cfg ...: alias for xcli config ....
• xcli auth login|whoami|refresh: standard OAuth flow for user token lifecycle.
• xcli auth doctor|pkce new|authorize-url|callback listen|token-exchange: low-level OAuth tooling.

Global flags

• --plain
• --json
• -q
• -v
• --timeout <ms>
• --retries <n>
• --endpoint <url>
• --region <name>

Common errors

• 2: invalid arguments or missing required input.
• 3: authentication failed (401/403).
• 4: rate limited (429).
• 5: API/network error.
• 6: missing or invalid config.