diff --git a/skills/social-media/xitter/SKILL.md b/skills/social-media/xitter/SKILL.md deleted file mode 100644 index 802924dff..000000000 --- a/skills/social-media/xitter/SKILL.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -name: xitter -description: Interact with X/Twitter via the x-cli terminal client using official X API credentials. Use for posting, reading timelines, searching tweets, liking, retweeting, bookmarks, mentions, and user lookups. -version: 1.0.0 -author: Siddharth Balyan + Hermes Agent -license: MIT -platforms: [linux, macos] -prerequisites: - commands: [uv] - env_vars: [X_API_KEY, X_API_SECRET, X_BEARER_TOKEN, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET] -metadata: - hermes: - tags: [twitter, x, social-media, x-cli] - homepage: https://github.com/Infatoshi/x-cli ---- - -# Xitter — X/Twitter via x-cli - -Use `x-cli` for official X/Twitter API interactions from the terminal. - -This skill is for: -- posting tweets, replies, and quote tweets -- searching tweets and reading timelines -- looking up users, followers, and following -- liking and retweeting -- checking mentions and bookmarks - -This skill intentionally does not vendor a separate CLI implementation into Hermes. Install and use upstream `x-cli` instead. - -## Important Cost / Access Note - -X API access is not meaningfully free for most real usage. Expect to need paid or prepaid X developer access. If commands fail with permissions or quota errors, check your X developer plan first. - -## Install - -Install upstream `x-cli` with `uv`: - -```bash -uv tool install git+https://github.com/Infatoshi/x-cli.git -``` - -Upgrade later with: - -```bash -uv tool upgrade x-cli -``` - -Verify: - -```bash -x-cli --help -``` - -## Credentials - -You need these five values from the X Developer Portal: -- `X_API_KEY` -- `X_API_SECRET` -- `X_BEARER_TOKEN` -- `X_ACCESS_TOKEN` -- `X_ACCESS_TOKEN_SECRET` - -Get them from: -- https://developer.x.com/en/portal/dashboard - -### Why does X need 5 secrets? - -Unfortunately, the official X API splits auth across both app-level and user-level credentials: - -- `X_API_KEY` + `X_API_SECRET` identify your app -- `X_BEARER_TOKEN` is used for app-level read access -- `X_ACCESS_TOKEN` + `X_ACCESS_TOKEN_SECRET` let the CLI act as your user account for writes and authenticated actions - -So yes — it is a lot of secrets for one integration, but this is the stable official API path and is still preferable to cookie/session scraping. - -Setup requirements in the portal: -1. Create or open your app -2. In user authentication settings, set permissions to `Read and write` -3. Generate or regenerate the access token + access token secret after enabling write permissions -4. Save all five values carefully — missing any one of them will usually produce confusing auth or permission errors - -Note: upstream `x-cli` expects the full credential set to be present, so even if you mostly care about read-only commands, it is simplest to configure all five. - -## Cost / Friction Reality Check - -If this setup feels heavier than it should be, that is because it is. X’s official developer flow is high-friction and often paid. This skill chooses the official API path because it is more stable and maintainable than browser-cookie/session approaches. - -If the user wants the least brittle long-term setup, use this skill. If they want a zero-setup or unofficial path, that is a different trade-off and not what this skill is for. - - -## Where to Store Credentials - -`x-cli` looks for credentials in `~/.config/x-cli/.env`. - -If you already keep your X credentials in `~/.hermes/.env`, the cleanest setup is: - -```bash -mkdir -p ~/.config/x-cli -ln -sf ~/.hermes/.env ~/.config/x-cli/.env -``` - -Or create a dedicated file: - -```bash -mkdir -p ~/.config/x-cli -cat > ~/.config/x-cli/.env <<'EOF' -X_API_KEY=your_consumer_key -X_API_SECRET=your_secret_key -X_BEARER_TOKEN=your_bearer_token -X_ACCESS_TOKEN=your_access_token -X_ACCESS_TOKEN_SECRET=your_access_token_secret -EOF -chmod 600 ~/.config/x-cli/.env -``` - -## Quick Verification - -```bash -x-cli user get openai -x-cli tweet search "from:NousResearch" --max 3 -x-cli me mentions --max 5 -``` - -If reads work but writes fail, regenerate the access token after confirming `Read and write` permissions. - -## Common Commands - -### Tweets - -```bash -x-cli tweet post "hello world" -x-cli tweet get https://x.com/user/status/1234567890 -x-cli tweet delete 1234567890 -x-cli tweet reply 1234567890 "nice post" -x-cli tweet quote 1234567890 "worth reading" -x-cli tweet search "AI agents" --max 20 -x-cli tweet metrics 1234567890 -``` - -### Users - -```bash -x-cli user get openai -x-cli user timeline openai --max 10 -x-cli user followers openai --max 50 -x-cli user following openai --max 50 -``` - -### Self / Authenticated User - -```bash -x-cli me mentions --max 20 -x-cli me bookmarks --max 20 -x-cli me bookmark 1234567890 -x-cli me unbookmark 1234567890 -``` - -### Quick Actions - -```bash -x-cli like 1234567890 -x-cli retweet 1234567890 -``` - -## Output Modes - -Use structured output when the agent needs to inspect fields programmatically: - -```bash -x-cli -j tweet search "AI agents" --max 5 -x-cli -p user get openai -x-cli -md tweet get 1234567890 -x-cli -v -j tweet get 1234567890 -``` - -Recommended defaults: -- `-j` for machine-readable output -- `-v` when you need timestamps, metrics, or metadata -- plain/default mode for quick human inspection - -## Agent Workflow - -1. Confirm `x-cli` is installed -2. Confirm credentials are present -3. Start with a read command (`user get`, `tweet search`, `me mentions`) -4. Use `-j` when extracting fields for later steps -5. Only perform write actions after confirming the target tweet/user and the user's intent - -## Pitfalls - -- **Paid API access**: many failures are plan/permission problems, not code problems. -- **403 oauth1-permissions**: regenerate the access token after enabling `Read and write`. -- **Reply restrictions**: X restricts many programmatic replies. `tweet quote` is often more reliable than `tweet reply`. -- **Rate limits**: expect per-endpoint limits and cooldown windows. -- **Credential drift**: if you rotate tokens in `~/.hermes/.env`, make sure `~/.config/x-cli/.env` still points at the current file. - -## Notes - -- Prefer official API workflows over cookie/session scraping. -- Use tweet URLs or IDs interchangeably — `x-cli` accepts both. -- If bookmark behavior changes upstream, check the upstream README first: - https://github.com/Infatoshi/x-cli diff --git a/skills/social-media/xurl/SKILL.md b/skills/social-media/xurl/SKILL.md new file mode 100644 index 000000000..2d7a017c9 --- /dev/null +++ b/skills/social-media/xurl/SKILL.md @@ -0,0 +1,386 @@ +--- +name: xurl +description: Interact with X/Twitter via xurl, the official X API CLI. Use for posting, replying, quoting, searching, timelines, mentions, likes, reposts, bookmarks, follows, DMs, media upload, and raw v2 endpoint access. +version: 1.0.0 +author: xdevplatform + openclaw + Hermes Agent +license: MIT +platforms: [linux, macos] +prerequisites: + commands: [xurl] +metadata: + hermes: + tags: [twitter, x, social-media, xurl, official-api] + homepage: https://github.com/xdevplatform/xurl + upstream_skill: https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md +--- + +# xurl — X (Twitter) API via the Official CLI + +`xurl` is the X developer platform's official CLI for the X API. It supports shortcut commands for common actions AND raw curl-style access to any v2 endpoint. All commands return JSON to stdout. + +Use this skill for: +- 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 + +This skill replaces the older `xitter` skill (which wrapped a third-party Python CLI). `xurl` is maintained by the X developer platform team, supports OAuth 2.0 PKCE with auto-refresh, and covers a substantially larger API surface. + +--- + +## Secret Safety (MANDATORY) + +Critical rules when operating inside an agent/LLM session: + +- **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. +- **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`. + +Forbidden flags in agent commands (they accept inline secrets): +`--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret` + +App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with `xurl auth oauth2` — also outside the agent session. Tokens persist to `~/.xurl` in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh. + +--- + +## Installation + +Pick ONE method. On Linux, the shell script or `go install` are the easiest. + +```bash +# Shell script (installs to ~/.local/bin, no sudo, works on Linux + macOS) +curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash + +# Homebrew (macOS) +brew install --cask xdevplatform/tap/xurl + +# npm +npm install -g @xdevplatform/xurl + +# Go +go install github.com/xdevplatform/xurl@latest +``` + +Verify: + +```bash +xurl --help +xurl auth status +``` + +If `xurl` is installed but `auth status` shows no apps or tokens, the user needs to complete auth manually — see the next section. + +--- + +## One-Time User Setup (user runs these outside the agent) + +These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them. + +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: + ```bash + xurl auth oauth2 + ``` + (This opens a browser for the OAuth 2.0 PKCE flow.) +6. Verify: + ```bash + xurl auth status + xurl whoami + ``` + +After this, the agent can use any command below without further setup. OAuth 2.0 tokens auto-refresh. + +--- + +## 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 / Unlike | `xurl like POST_ID` / `xurl unlike POST_ID` | +| Repost / Undo | `xurl repost POST_ID` / `xurl unrepost POST_ID` | +| Bookmark / Remove | `xurl bookmark POST_ID` / `xurl unbookmark POST_ID` | +| List bookmarks / likes | `xurl bookmarks -n 10` / `xurl likes -n 10` | +| Follow / Unfollow | `xurl follow @handle` / `xurl unfollow @handle` | +| Following / Followers | `xurl following -n 20` / `xurl followers -n 20` | +| Block / Unblock | `xurl block @handle` / `xurl unblock @handle` | +| Mute / Unmute | `xurl mute @handle` / `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` | +| List apps | `xurl auth apps list` | +| Remove app | `xurl auth apps remove NAME` | +| Set default app | `xurl auth default APP_NAME [USERNAME]` | +| Per-request app | `xurl --app NAME /2/users/me` | +| Auth status | `xurl auth status` | + +Notes: +- `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 `@`. + +--- + +## Command Details + +### Posting + +```bash +xurl post "Hello world!" +xurl post "Check this out" --media-id MEDIA_ID +xurl post "Thread pics" --media-id 111 --media-id 222 + +xurl reply 1234567890 "Great point!" +xurl reply https://x.com/user/status/1234567890 "Agreed!" +xurl reply 1234567890 "Look at this" --media-id MEDIA_ID + +xurl quote 1234567890 "Adding my thoughts" +xurl delete 1234567890 +``` + +### Reading & Search + +```bash +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 +``` + +### Users, Timeline, Mentions + +```bash +xurl whoami +xurl user elonmusk +xurl user @XDevelopers + +xurl timeline -n 25 +xurl mentions -n 20 +``` + +### Engagement + +```bash +xurl like 1234567890 +xurl unlike 1234567890 + +xurl repost 1234567890 +xurl unrepost 1234567890 + +xurl bookmark 1234567890 +xurl unbookmark 1234567890 + +xurl bookmarks -n 20 +xurl likes -n 20 +``` + +### Social Graph + +```bash +xurl follow @XDevelopers +xurl unfollow @XDevelopers + +xurl following -n 50 +xurl followers -n 50 + +# Another user's graph +xurl following --of elonmusk -n 20 +xurl followers --of elonmusk -n 20 + +xurl block @spammer +xurl unblock @spammer +xurl mute @annoying +xurl unmute @annoying +``` + +### Direct Messages + +```bash +xurl dm @someuser "Hey, saw your post!" +xurl dms -n 25 +``` + +### Media Upload + +```bash +# Auto-detect type +xurl media upload photo.jpg +xurl media upload video.mp4 + +# Explicit type/category +xurl media upload --media-type image/jpeg --category tweet_image photo.jpg + +# Videos need server-side processing — check status (or poll) +xurl media status MEDIA_ID +xurl media status --wait MEDIA_ID + +# Full workflow +xurl media upload meme.png # returns media id +xurl post "lol" --media-id MEDIA_ID +``` + +--- + +## Raw API Access + +The shortcuts cover common operations. For anything else, use raw curl-style mode against any X API v2 endpoint: + +```bash +# GET +xurl /2/users/me + +# POST with JSON body +xurl -X POST /2/tweets -d '{"text":"Hello world!"}' + +# DELETE / PUT / PATCH +xurl -X DELETE /2/tweets/1234567890 + +# Custom headers +xurl -H "Content-Type: application/json" /2/some/endpoint + +# Force streaming +xurl -s /2/tweets/search/stream + +# Full URLs also work +xurl https://api.x.com/2/users/me +``` + +--- + +## Global Flags + +| Flag | Short | Description | +| --- | --- | --- | +| `--app` | | Use a specific registered app (overrides default) | +| `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` | +| `--username` | `-u` | Which OAuth2 account to use (if multiple exist) | +| `--verbose` | `-v` | **Forbidden in agent sessions** — leaks auth headers | +| `--trace` | `-t` | Add `X-B3-Flags: 1` trace header | + +--- + +## Streaming + +Streaming endpoints are auto-detected. Known ones include: + +- `/2/tweets/search/stream` +- `/2/tweets/sample/stream` +- `/2/tweets/sample10/stream` + +Force streaming on any endpoint with `-s`. + +--- + +## Output Format + +All commands return JSON to stdout. Structure mirrors X API v2: + +```json +{ "data": { "id": "1234567890", "text": "Hello world!" } } +``` + +Errors are also JSON: + +```json +{ "errors": [ { "message": "Not authorized", "code": 403 } ] } +``` + +--- + +## Common Workflows + +### Post with an image +```bash +xurl media upload photo.jpg +xurl post "Check out this photo!" --media-id MEDIA_ID +``` + +### Reply to a conversation +```bash +xurl read https://x.com/user/status/1234567890 +xurl reply 1234567890 "Here are my thoughts..." +``` + +### Search and engage +```bash +xurl search "topic of interest" -n 10 +xurl like POST_ID_FROM_RESULTS +xurl reply POST_ID_FROM_RESULTS "Great point!" +``` + +### Check your activity +```bash +xurl whoami +xurl mentions -n 20 +xurl timeline -n 20 +``` + +### Multiple apps (credentials pre-configured manually) +```bash +xurl auth default prod alice # prod app, alice user +xurl --app staging /2/users/me # one-off against staging +``` + +--- + +## Error Handling + +- 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. + +--- + +## Agent Workflow + +1. Verify prerequisites: `xurl --help` and `xurl auth status`. +2. If auth is missing, stop and direct the user to the "One-Time User Setup" section — do NOT attempt to register apps or pass secrets yourself. +3. Start with a cheap read (`xurl whoami`, `xurl user @handle`, `xurl search ... -n 3`) to confirm reachability. +4. Confirm the target post/user and the user's intent before any write action (post, reply, like, repost, DM, follow, block, delete). +5. Use JSON output directly — every response is already structured. +6. Never paste `~/.xurl` contents back into the conversation. + +--- + +## Notes + +- **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. 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. + +--- + +## Attribution + +- 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. diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md index e5283ba01..27fbb8c76 100644 --- a/website/docs/reference/skills-catalog.md +++ b/website/docs/reference/skills-catalog.md @@ -251,7 +251,7 @@ Skills for interacting with social platforms — posting, reading, monitoring, a | Skill | Description | Path | |-------|-------------|------| -| `xitter` | Interact with X/Twitter via the x-cli terminal client using official X API credentials. Use for posting, reading timelines, searching tweets, liking, retweeting, bookmarks, mentions, and user lookups. | `social-media/xitter` | +| `xurl` | Interact with X/Twitter via xurl, the official X API CLI. Use for posting, replying, quoting, searching, timelines, mentions, likes, reposts, bookmarks, follows, DMs, media upload, and raw v2 endpoint access. | `social-media/xurl` | ## software-development