xurl

xurl — Agent Skill Reference

xurl is a CLI tool for the X API. It supports both shortcut commands (human/agent‑friendly one‑liners) and raw curl‑style access to any v2 endpoint. All commands return JSON to stdout.

Installation

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

Shell script

curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

Installs to ~/.local/bin. If it's not in your PATH, the script will tell you what to add.

Go

go install github.com/xdevplatform/xurl@latest

Prerequisites

This skill requires the xurl CLI utility: https://github.com/xdevplatform/xurl.

Before using any command you must be authenticated. Run xurl auth status to check.

Secret Safety (Mandatory)

• Never read, print, parse, summarize, upload, or send ~/.xurl (or copies of it) to the LLM context.
• Never ask the user to paste credentials/tokens into chat.
• The user must fill ~/.xurl with required secrets manually on their own machine.
• Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
• Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
• Never use --verbose / -v in agent/LLM sessions; it can expose sensitive headers/tokens in output.
• Sensitive flags that must never be used in agent commands: --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret.
• To verify whether at least one app with credentials is already registered, run: xurl auth status.

Register an app (recommended)

App credential registration must be done manually by the user outside the agent/LLM session. After credentials are registered, authenticate with:

xurl auth

For multiple pre-configured apps, switch between them:

Other auth methods

Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.

Tokens are persisted to ~/.xurl in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right Authorization header.

Quick Reference

Post IDs vs URLs: Anywhere POST_ID appears above you can also paste a full post URL (e.g. https://x.com/user/status/1234567890) — xurl extracts the ID automatically.

Usernames: Leading @ is optional. @elonmusk and elonmusk both work.

Command Details

Posting

Reading

User Info

Timelines & Mentions

Engagement

Social Graph

Direct Messages

Media Upload

Global Flags

These flags work on every command:

Raw API Access

The shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with any X API v2 endpoint:

Streaming

Streaming endpoints are auto‑detected. Known streaming endpoints include:

• /2/tweets/search/stream
• /2/tweets/sample/stream
• /2/tweets/sample10/stream

You can force streaming on any endpoint with -s:

Output Format

All commands return JSON to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:

Errors are also returned as JSON:

Common Workflows

Post with an image

Reply to a conversation

Search and engage

Check your activity

Set up multiple apps

Error Handling

• Non‑zero exit code on any error.
• API errors are printed as JSON to stdout (so you can still parse them).
• Auth errors suggest re‑running xurl auth oauth2 or checking your tokens.
• If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via /2/users/me. If that fails, you'll see an auth error.

Notes

• Rate limits: The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
• Scopes: OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run xurl auth oauth2 to get a fresh token.
• Token refresh: OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
• Multiple apps: Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with xurl auth default or --app.
• Multiple accounts: You can authenticate multiple OAuth 2.0 accounts per app and switch between them with --username / -u or set a default with xurl auth default APP USER.
• Default user: When no -u flag is given, xurl uses the default user for the active app (set via xurl auth default). If no default user is set, it uses the first available token.
• Token storage: ~/.xurl is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.