Xurl

xurl

xurl is a curl-like CLI for the X API. It supports shortcut commands and raw curl-style access to X API v2 endpoints. Commands return JSON to stdout.

Source basis: xdevplatform/xurl SKILL.md on main at commit 1a17984e8205468f6ba95e7a3a1360fbef32c255, with local botfiles safety notes from ZON-153.

Mandatory Safety

• Prefer the birdclaw skill over direct xurl for follower/following analysis, unfollower checks, mutuals, non-mutual following, top followers, and leadgen exports whenever Birdclaw can answer from cache or its explicit sync workflow.
• Never read, print, parse, summarize, upload, or send ~/.xurl or copies of it to model context.
• Never ask the user to paste credentials, tokens, client IDs, client secrets, or app secrets into chat.
• Never run auth or app-registration commands with inline secret flags in an agent session.
• Never use --verbose / -v; it can expose sensitive headers or tokens.
• Never use these sensitive flags in agent commands: --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret.
• Default to read-only commands. Ask for explicit user approval before any write or social action: post, reply, quote, delete, like, unlike, repost, unrepost, bookmark, unbookmark, follow, unfollow, block, unblock, mute, unmute, DM, media upload, or webhook mutation.
• Prefer dry-run or preview text before write actions when xurl does not provide a native dry-run.

Local Setup Notes

On Azure-A100-GPU-VM, ZON-153 verified a working setup:

• xurl version reports xurl 1.1.0.
• xurl auth status is safe to run and should be the first check.
• self-x-app is the intended active app, with OAuth2 user curious_queue.
• The OAuth callback redirect URI is http://localhost:8080/callback.

If re-authentication is needed on an SSH VM, do not inline secrets. The prior working pattern was:

1. Confirm the user wants to run OAuth.
2. Check what owns local port 8080.
3. Stop any conflicting service only with explicit approval.
4. Use a browser bridge or tunnel so the browser reaches the VM callback listener.
5. Have the user complete the browser approval manually.
6. Close tunnels and restore services afterward.

Authentication Checks

Before using xurl:

xurl auth status
xurl whoami

For multiple preconfigured apps:

xurl auth default prod-app
xurl auth default prod-app alice
xurl --app dev-app /2/users/me
xurl auth apps redirect-uri get prod-app
xurl auth apps redirect-uri set prod-app http://localhost:8080/callback

App credential registration must be done manually by the user outside the agent session. After credentials are registered, OAuth can be started with:

xurl auth oauth2

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

Quick Reference

Post IDs can also be full post URLs, such as https://x.com/user/status/1234567890; xurl extracts the ID. Leading @ is optional for usernames.

Reading

xurl read 1234567890
xurl read https://x.com/user/status/1234567890
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15
xurl whoami
xurl user elonmusk
xurl user @XDevelopers
xurl timeline -n 25
xurl mentions -n 20

Social Graph

Use these read commands freely after the auth check:

xurl following -n 50
xurl followers -n 50
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

Ask for explicit approval before these write actions:

xurl follow @XDevelopers
xurl unfollow @XDevelopers
xurl block @spammer
xurl unblock @spammer
xurl mute @annoying
xurl unmute @annoying

Posting And Engagement

Ask for explicit approval before running any command in this section.

xurl post "Hello world!"
xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"
xurl quote 1234567890 "Adding my thoughts"
xurl delete 1234567890
xurl like 1234567890
xurl unlike 1234567890
xurl repost 1234567890
xurl unrepost 1234567890
xurl bookmark 1234567890
xurl unbookmark 1234567890

Read-only engagement lists:

xurl bookmarks -n 20
xurl likes -n 20

Direct Messages

Reading recent DMs is sensitive; confirm intent before running. Sending DMs is a write action and requires explicit approval.

xurl dms -n 10
xurl dm @someuser "message"

Media Upload

Media upload is a write-adjacent action and requires explicit approval.

xurl media upload photo.jpg
xurl media upload video.mp4
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID
xurl post "Check this out" --media-id MEDIA_ID

Raw API Access

Use raw curl-style mode for X API v2 endpoints not covered by shortcuts:

xurl /2/users/me
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
xurl -X DELETE /2/tweets/1234567890
xurl -H "Content-Type: application/json" /2/some/endpoint
xurl -s /2/tweets/search/stream
xurl https://api.x.com/2/users/me

Apply the same read/write approval rules to raw API access. Any raw POST, PUT, PATCH, or DELETE requires explicit approval.

Streaming

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

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

Force streaming with:

xurl -s /2/some/endpoint

Output

Responses are JSON. API errors are also JSON and non-zero exit codes indicate command errors:

{
  "errors": [
    {
      "message": "Not authorized",
      "code": 403
    }
  ]
}

Common Workflows

Read And Reply

xurl read https://x.com/user/status/1234567890

Draft the reply in chat first. Run the reply command only after explicit approval:

xurl reply 1234567890 "Here are my thoughts..."

Search And Review

xurl search "topic of interest" -n 10

Treat likes, replies, reposts, follows, and DMs as separate write actions that need approval.

Multiple Apps

xurl auth default prod
xurl auth oauth2
xurl auth default staging
xurl auth oauth2
xurl auth default prod alice
xurl --app staging /2/users/me

Credentials must already be configured manually outside the agent session.

Error Handling

• Auth errors suggest rerunning xurl auth oauth2 or checking tokens, but do not inspect token files.
• If X returns client-forbidden or client-not-enrolled after successful auth, check the app's X developer-console package and environment.
• If a command requires your user ID, xurl will fetch it with /2/users/me. When that endpoint is unreliable, use --username USERNAME or authenticate with xurl auth oauth2 USERNAME.
• If rate limited with HTTP 429, wait and retry later. Write endpoints have stricter limits than read endpoints.

Notes

• OAuth 2.0 tokens auto-refresh when expired.
• Each app has isolated credentials, tokens, and optional stored redirect_uri.
• REDIRECT_URI in the environment takes precedence over the app's stored redirect URI, which takes precedence over the built-in default.
• Use xurl auth apps redirect-uri get [NAME], xurl auth apps redirect-uri set NAME URI, or xurl auth apps update NAME --redirect-uri URI to inspect and manage callback URIs.
• A successful OAuth callback does not guarantee /2/* reads will work. If client-not-enrolled appears, verify the X app package and environment.
• Multiple OAuth 2.0 accounts can exist per app. Use --username / -u or xurl auth default APP USER to select one.
• When no -u flag is given, xurl uses the default user for the active app. If no default user is set, it uses the first available token.