/xurl

name: xurl
description: A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint.
metadata:
  {
    "emoji": "🐦",
    "requires": { "bins": ["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 oauth2

For multiple pre-configured apps, switch between them:

xurl auth default prod-app          # set default app
xurl auth default prod-app alice    # set default app + user
xurl --app dev-app /2/users/me      # one-off override

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

| Action | Command | | ------------------------- | ----------------------------------------------------- | | Post | `xurl post "Hello world!"` | | Reply | `xurl reply POST_ID "Nice post!"` | | Quote | `xurl quote POST_ID "My take"` | | Delete a post | `xurl delete POST_ID` | | Read a post | `xurl read POST_ID` | | Search posts | `xurl search "QUERY" -n 10` | | Who am I | `xurl whoami` | | Look up a user | `xurl user @handle` | | Home timeline | `xurl timeline -n 20` | | Mentions | `xurl mentions -n 10` | | Like | `xurl like POST_ID` | | Unlike | `xurl unlike POST_ID` | | Repost | `xurl repost POST_ID` | | Undo repost | `xurl unrepost POST_ID` | | Bookmark | `xurl bookmark POST_ID` | | Remove bookmark | `xurl unbookmark POST_ID` | | List bookmarks | `xurl bookmarks -n 10` | | List likes | `xurl likes -n 10` | | Follow | `xurl follow @handle` | | Unfollow | `xurl unfollow @handle` | | List following | `xurl following -n 20` | | List followers | `xurl followers -n 20` | | Block | `xurl block @handle` | | Unblock | `xurl unblock @handle` | | Mute | `xurl mute @handle` | | Unmute | `xurl unmute @handle` | | Send DM | `xurl dm @handle "message"` | | List DMs | `xurl dms -n 10` | | Upload media | `xurl media upload path/to/file.mp4` | | Media status | `xurl media status MEDIA_ID` | | **App Management** | | | Register app | Manual, outside agent (do not pass secrets via agent) | | List apps | `xurl auth apps list` | | Update app creds |