letsbe/LetsBeBiz-Redesign
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Include full contents of all nested repositories

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Matt
2026-02-27 16:25:02 +01:00
parent 14ff8fd54c
commit 2401ed446f
7271 changed files with 1310112 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

461
openclaw/skills/xurl/SKILL.md Normal file
View File

@@ -0,0 +1,461 @@
---
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:
{
"openclaw":
{
"emoji": "𝕏",
"requires": { "bins": ["xurl"] },
"install":
[
{
"id": "brew",
"kind": "brew",
"formula": "xdevplatform/tap/xurl",
"bins": ["xurl"],
"label": "Install xurl (brew)",
},
{
"id": "npm",
"kind": "npm",
"package": "@xdevplatform/xurl",
"bins": ["xurl"],
"label": "Install xurl (npm)",
},
],
},
}
---
# 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)
```bash
brew install --cask xdevplatform/tap/xurl
```
### npm
```bash
npm install -g @xdevplatform/xurl
```
### Shell script
```bash
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
```bash
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:
```bash
xurl auth oauth2
```
For multiple pre-configured apps, switch between them:
```bash
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 | Manual, outside agent (do not pass secrets via agent) |
| Remove app | `xurl auth apps remove NAME` |
| Set default (interactive) | `xurl auth default` |
| Set default (command) | `xurl auth default APP_NAME [USERNAME]` |
| Use app per-request | `xurl --app NAME /2/users/me` |
| Auth status | `xurl auth status` |
> **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
```bash
# Simple post
xurl post "Hello world!"
# Post with media (upload first, then attach)
xurl media upload photo.jpg # → note the media_id from response
xurl post "Check this out" --media-id MEDIA_ID
# Multiple media
xurl post "Thread pics" --media-id 111 --media-id 222
# Reply to a post (by ID or URL)
xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"
# Reply with media
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID
# Quote a post
xurl quote 1234567890 "Adding my thoughts"
# Delete your own post
xurl delete 1234567890
```
### Reading
```bash
# Read a single post (returns author, text, metrics, entities)
xurl read 1234567890
xurl read https://x.com/user/status/1234567890
# Search recent posts (default 10 results)
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15
```
### User Info
```bash
# Your own profile
xurl whoami
# Look up any user
xurl user elonmusk
xurl user @XDevelopers
```
### Timelines & Mentions
```bash
# Home timeline (reverse chronological)
xurl timeline
xurl timeline -n 25
# Your mentions
xurl mentions
xurl mentions -n 20
```
### Engagement
```bash
# Like / unlike
xurl like 1234567890
xurl unlike 1234567890
# Repost / undo
xurl repost 1234567890
xurl unrepost 1234567890
# Bookmark / remove
xurl bookmark 1234567890
xurl unbookmark 1234567890
# List your bookmarks / likes
xurl bookmarks -n 20
xurl likes -n 20
```
### Social Graph
```bash
# Follow / unfollow
xurl follow @XDevelopers
xurl unfollow @XDevelopers
# List who you follow / your followers
xurl following -n 50
xurl followers -n 50
# List another user's following/followers
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20
# Block / unblock
xurl block @spammer
xurl unblock @spammer
# Mute / unmute
xurl mute @annoying
xurl unmute @annoying
```
### Direct Messages
```bash
# Send a DM
xurl dm @someuser "Hey, saw your post!"
# List recent DM events
xurl dms
xurl dms -n 25
```
### Media Upload
```bash
# Upload a file (auto‑detects type for images/videos)
xurl media upload photo.jpg
xurl media upload video.mp4
# Specify type and category explicitly
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg
# Check processing status (videos need server‑side processing)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID # poll until done
# Full workflow: upload then post
xurl media upload meme.png # response includes media id
xurl post "lol" --media-id MEDIA_ID
```
---
## Global Flags
These flags work on every command:
| Flag | Short | Description |
| ------------ | ----- | ------------------------------------------------------------------ |
| `--app` | | Use a specific registered app for this request (overrides default) |
| `--auth` | | Force auth type: `oauth1`, `oauth2`, or `app` |
| `--username` | `-u` | Which OAuth2 account to use (if you have multiple) |
| `--verbose` | `-v` | Forbidden in agent/LLM sessions (can leak auth headers/tokens) |
| `--trace` | `-t` | Add `X-B3-Flags: 1` trace header |
---
## 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:
```bash
# GET request (default)
xurl /2/users/me
# POST with JSON body
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
# PUT, PATCH, DELETE
xurl -X DELETE /2/tweets/1234567890
# Custom headers
xurl -H "Content-Type: application/json" /2/some/endpoint
# Force streaming mode
xurl -s /2/tweets/search/stream
# Full URLs also work
xurl https://api.x.com/2/users/me
```
---
## 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`:
```bash
xurl -s /2/some/endpoint
```
---
## 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:
```json
{
"data": {
"id": "1234567890",
"text": "Hello world!"
}
}
```
Errors are also returned as JSON:
```json
{
"errors": [
{
"message": "Not authorized",
"code": 403
}
]
}
```
---
## Common Workflows
### Post with an image
```bash
# 1. Upload the image
xurl media upload photo.jpg
# 2. Copy the media_id from the response, then post
xurl post "Check out this photo!" --media-id MEDIA_ID
```
### Reply to a conversation
```bash
# 1. Read the post to understand context
xurl read https://x.com/user/status/1234567890
# 2. Reply
xurl reply 1234567890 "Here are my thoughts..."
```
### Search and engage
```bash
# 1. Search for relevant posts
xurl search "topic of interest" -n 10
# 2. Like an interesting one
xurl like POST_ID_FROM_RESULTS
# 3. Reply to it
xurl reply POST_ID_FROM_RESULTS "Great point!"
```
### Check your activity
```bash
# See who you are
xurl whoami
# Check your mentions
xurl mentions -n 20
# Check your timeline
xurl timeline -n 20
```
### Set up multiple apps
```bash
# App credentials must already be configured manually outside agent/LLM context.
# Authenticate users on each pre-configured app
xurl auth default prod
xurl auth oauth2 # authenticates on prod app
xurl auth default staging
xurl auth oauth2 # authenticates on staging app
# Switch between them
xurl auth default prod alice # prod app, alice user
xurl --app staging /2/users/me # one-off request against staging
```
---
## 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.