xurl

• posting, replying, quoting, deleting posts
• searching posts and reading timelines/mentions
• liking, reposting, bookmarking
• following, unfollowing, blocking, muting
• direct messages
• media uploads (images and video)
• raw access to any X API v2 endpoint
• multi-app / multi-account workflows

xitter

xurl

• Never read, print, parse, summarize, upload, or send

  ~/.xurl

  to LLM context.
• Never ask the user to paste credentials/tokens into chat.
• The user must fill

  ~/.xurl

  with secrets manually on their own machine. In Docker, this must be the

  ~

  seen by Hermes tool subprocesses; see the Docker note below.
• Never recommend or execute auth commands with inline secrets in agent sessions.
• Never use

  --verbose

  /

  -v

  in agent sessions — it can expose auth headers/tokens.
• To verify credentials exist, only use:

  xurl auth status

  .

--bearer-token

--consumer-key

--consumer-secret

--access-token

--token-secret

--client-id

--client-secret

xurl auth oauth2

~/.xurl

1. Create or open an app at https://developer.x.com/en/portal/dashboard
2. Set the redirect URI to

   http://localhost:8080/callback

3. Copy the app's Client ID and Client Secret
4. Register the app locally (user runs this):
   bash

   xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

5. Authenticate (specify

   --app

   to bind the token to your app):
   bash

   xurl auth oauth2 --app my-app

   (This opens a browser for the OAuth 2.0 PKCE flow.)
   If X returns a

   UsernameNotFound

   error or 403 on the post-OAuth

   /2/users/me

   lookup, pass your handle explicitly (xurl v1.1.0+):
   bash

   xurl auth oauth2 --app my-app YOUR_USERNAME

   This binds the token to your handle and skips the broken

   /2/users/me

   call.
6. Set the app as default so all commands use it:
   bash

   xurl auth default my-app

7. Verify:
   bash

   xurl auth status
   xurl whoami

Common pitfall: If you omit

--app my-app

from

xurl auth oauth2

, the OAuth token is saved to the built-in

default

app profile — which has no client-id or client-secret. Commands will fail with auth errors even though the OAuth flow appeared to succeed. If you hit this, re-run

xurl auth oauth2 --app my-app

and

xurl auth default my-app

.

Docker HOME pitfall: In the official Hermes Docker layout,

/opt/data

is

HERMES_HOME

, but Hermes tool subprocesses use

/opt/data/home

as

HOME

. That means

~/.xurl

resolves to

/opt/data/home/.xurl

for Hermes-run

xurl

commands, not

/opt/data/.xurl

. Run the user setup with the same HOME:

bash

HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth status

If

HOME=/opt/data xurl auth status

succeeds but

HOME=/opt/data/home xurl auth status

shows no apps or tokens, Hermes tool calls will not see the credentials.

xurl post "Hello world!"

xurl reply POST_ID "Nice post!"

xurl quote POST_ID "My take"

xurl delete POST_ID

xurl read POST_ID

xurl search "QUERY" -n 10

xurl whoami

xurl user @handle

xurl timeline -n 20

xurl mentions -n 10

xurl like POST_ID

xurl unlike POST_ID

xurl repost POST_ID

xurl unrepost POST_ID

xurl bookmark POST_ID

xurl unbookmark POST_ID

xurl bookmarks -n 10

xurl likes -n 10

xurl follow @handle

xurl unfollow @handle

xurl following -n 20

xurl followers -n 20

xurl block @handle

xurl unblock @handle

xurl mute @handle

xurl unmute @handle

xurl dm @handle "message"

xurl dms -n 10

xurl media upload path/to/file.mp4

xurl media status MEDIA_ID

xurl auth apps list

xurl auth apps remove NAME

xurl auth default APP_NAME [USERNAME]

xurl --app NAME /2/users/me

xurl auth status

• POST_ID

  accepts full URLs too (e.g.

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

  ) — xurl extracts the ID.
• Usernames work with or without a leading

  @

  .

• /2/tweets/search/stream

• /2/tweets/sample/stream

• /2/tweets/sample10/stream

-s

• Non-zero exit code on any error.
• API errors are still printed as JSON to stdout, so you can parse them.
• Auth errors → have the user re-run

  xurl auth oauth2

  outside the agent session.
• Commands that need the caller's user ID (like, repost, bookmark, follow, etc.) will auto-fetch it via

  /2/users/me

  . An auth failure there surfaces as an auth error.

1. Verify prerequisites:

   xurl --help

   and

   xurl auth status

   .
2. Check default app has credentials. Parse the

   auth status

   output. The default app is marked with

   ▸

   . If the default app shows

   oauth2: (none)

   but another app has a valid oauth2 user, tell the user to run

   xurl auth default <that-app>

   to fix it. This is the most common setup mistake — the user added an app with a custom name but never set it as default, so xurl keeps trying the empty

   default

   profile.
3. If auth is missing entirely, stop and direct the user to the "One-Time User Setup" section — do NOT attempt to register apps or pass secrets yourself.
4. Start with a cheap read (

   xurl whoami

   ,

   xurl user @handle

   ,

   xurl search ... -n 3

   ) to confirm reachability.
5. Confirm the target post/user and the user's intent before any write action (post, reply, like, repost, DM, follow, block, delete).
6. Use JSON output directly — every response is already structured.
7. Never paste

   ~/.xurl

   contents back into the conversation.

• Rate limits: X enforces per-endpoint rate limits. A 429 means wait and retry. Write endpoints (post, reply, like, repost) have tighter limits than reads.
• Scopes: OAuth 2.0 tokens use broad scopes. A 403 on a specific action usually means the token is missing a scope — have the user re-run

  xurl auth oauth2

  .
• Token refresh: OAuth 2.0 tokens auto-refresh. Nothing to do.
• Multiple apps: Each app has isolated credentials/tokens. Switch with

  xurl auth default

  or

  --app

  .
• Multiple accounts per app: Select with

  -u / --username

  , or set a default with

  xurl auth default APP USER

  .
• Token storage:

  ~/.xurl

  is YAML. In Docker, use the Hermes subprocess HOME (

  /opt/data/home

  in the official image) so tokens land under

  /opt/data/home/.xurl

  . Never read or send this file to LLM context.
• Cost: X API access is typically paid for meaningful usage. Many failures are plan/permission problems, not code problems.

• Upstream CLI: https://github.com/xdevplatform/xurl (X developer platform team, Chris Park et al.)
• Upstream agent skill: https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
• Hermes adaptation: reformatted for Hermes skill conventions; safety guardrails preserved verbatim.