mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-04-25 00:51:20 +00:00
feat(skills): replace xitter with xurl — the official X API CLI (#12303)
Swap the social-media/xitter skill (third-party wrapper around Infatoshi/x-cli) for a new social-media/xurl skill wrapping xdevplatform/xurl — the official X API CLI from the X developer platform team. Why: - xurl is officially maintained by the X dev platform team - OAuth 2.0 PKCE with auto-refresh + multi-app / multi-user support (vs. xitter's 5-env-var OAuth 1.0a + single account) - Credentials stored in ~/.xurl managed by xurl itself — no manual env var juggling for users - Substantially larger API surface: DMs, follows, blocks, mutes, media upload, streaming, and raw v2 endpoint access - Ships stronger agent-safety guardrails (forbidden-flag list, no --verbose in agent mode, never-read-~/.xurl rule) Adaptation: - Ported the openclaw SKILL.md (which the xdevplatform team seeded) to Hermes frontmatter conventions (prerequisites.commands, platforms, metadata.hermes.tags/homepage) — dropped openclaw-specific metadata - Added a Hermes-oriented one-time user setup section so the agent knows to direct the user to run auth commands themselves, never execute them with inline secrets - Preserved the mandatory secret-safety rules verbatim - Attribution block credits xdevplatform, openclaw, and the Hermes port Docs: updated website/docs/reference/skills-catalog.md to replace the xitter row with xurl.
This commit is contained in:
Teknium
GitHub
parent
6a3a6a0fb6
commit
0175ff7516
3 changed files with 387 additions and 203 deletions
|
|
@ -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
|
||||
386
skills/social-media/xurl/SKILL.md
Normal file
386
skills/social-media/xurl/SKILL.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue