# Xurl Rs

> Drive the X (Twitter) API from the command line via `xr`, the xurl-rs CLI. Use when the user wants to post or thread, reply, quote, delete, like, repost, bookmark, follow, mute, block, send DMs, search recent posts, read a timeline or mentions, look up a user, upload media, stream filtered tweets, hit a raw `/2/...` endpoint, manage OAuth2 / OAuth1 / Bearer auth, register multiple X apps, inspect…

- **Type:** Skill
- **Install:** `agentstack add skill-brettdavies-xurl-rs-skill-xurl-rs-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [brettdavies](https://agentstack.voostack.com/s/brettdavies)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [brettdavies](https://github.com/brettdavies)
- **Source:** https://github.com/brettdavies/xurl-rs-skill
- **Website:** https://github.com/brettdavies/xurl-rs

## Install

```sh
agentstack add skill-brettdavies-xurl-rs-skill-xurl-rs-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# xurl-rs (`xr`)

`xr` is a Rust CLI for the X (Twitter) API. It ships ~30 high-level shortcut commands, a raw curl-style mode for any
`/2/...` endpoint, OAuth1 / OAuth2-PKCE / Bearer auth with a multi-app token store at `~/.xurl`, chunked media upload,
streaming, typed JSON-schema responses, and an agent-native output envelope.

The binary self-introspects. Treat it as the source of truth: this skill routes you to the binary's helpers and provides
the workflow patterns that the binary can't describe on its own.

## Hard guardrail — production credentials

The `xr` binary on the user's machine is configured against **real X API credentials**, not a sandbox. Every write
operation (post / reply / quote / delete / like / unlike / repost / unrepost / bookmark / unbookmark / follow / unfollow
/ block / unblock / mute / unmute / dm / media upload) hits production state.

Before any write op:

1. Use `--dry-run` first to surface input validation errors and confirm intent. Every write verb emits a typed `status:
   "dry_run"` envelope when `--output json` and `--dry-run` are both set; check `would_succeed: true` and `exit_code:
   0`.
2. Confirm scope with the user before issuing the live call when the action is destructive (`delete`, `block`,
   `unfollow`, `dm`, `post` to anything besides a test thread the user already named).
3. Prefer `--output json` with `--no-interactive` so failures arrive as structured envelopes you can act on.

Read ops (`read`, `search`, `whoami`, `user`, `timeline`, `mentions`, `bookmarks`, `likes`, `following`, `followers`,
`dms`, `usage`, `auth status`, `schema`, `validate`, `examples`, `version`) ignore `--dry-run` and are safe to run
without confirmation.

## Quick start — let the binary teach you

The binary ships three self-introspection commands. Reach for them before reading anything in `references/`:

```bash
xr examples                          # curated invocation gallery, ~120 lines, every major workflow
xr  --help                  # 3-5 examples per command + full flag matrix
xr schema --list --output json       # 35 typed response shapes, one per command
xr schema --command post --output json   # JSON Schema for a single response type
xr schema --envelope --output json   # the canonical agent-native output envelope (ok / dry_run / error)
xr auth status --output json         # current auth state across registered apps
```

For full read-only-probes-are-always-safe rules, see
[references/self-introspection.md](references/self-introspection.md).

## Deterministic helpers (`scripts/`)

The bundle ships two shellcheck-clean scripts that encode the rules the references describe. Prefer them when you can:
they enforce mechanically what the prose only requests.

| Script                                                      | Use for                                                                                                                                      |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `scripts/dry-run-gate.sh [--yes] -- xr  [args]` | Every write op. Runs `--dry-run` preflight, refuses on `would_succeed: false`, prompts on TTY or honors `--yes`, then `exec`s the live call. |
| `scripts/paginate.sh [--max-pages N] -- xr `     | Every cursor-paginated read. Streams `.data[]?` as compact JSONL, follows `meta.next_token`, caps at `--max-pages`.                          |

Both auto-detect `jaq` (preferred) or `jq`. When neither is installed, they emit a PM-aware install advice ranked by
what's already on the system. Install path after `xr skill install claude_code` (or the host equivalent) is
`~/.claude/skills/xurl-rs/scripts/`. Full contract: [scripts/README.md](scripts/README.md).

## Routing table

| Task                                       | First action                                                                                 |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| User wants to authenticate                 | [templates/oauth2-setup.md](templates/oauth2-setup.md)                                       |
| User wants to post / reply / thread        | `scripts/dry-run-gate.sh` + [templates/post-reply-thread.md](templates/post-reply-thread.md) |
| User wants to search and pipe to a tool    | `scripts/paginate.sh` + [templates/search-and-process.md](templates/search-and-process.md)   |
| User wants to attach media                 | [templates/media-upload.md](templates/media-upload.md)                                       |
| Pick an auth mode for a one-off            | [references/auth-modes.md](references/auth-modes.md)                                         |
| Pick output format / pagination / dry-run  | [references/agent-flags.md](references/agent-flags.md)                                       |
| Parse a response or an error               | [references/output-envelope.md](references/output-envelope.md)                               |
| Look up X API endpoints / scopes / billing | [references/x-api-essentials.md](references/x-api-essentials.md)                             |
| Don't know what `xr` can do                | [references/self-introspection.md](references/self-introspection.md)                         |
| Stuck — what next?                         | [references/escalation.md](references/escalation.md)                                         |

## Iron rules

1. **Never invent X API endpoints, scopes, billing tiers, or rate-limit numbers.** They change. See
   [references/escalation.md](references/escalation.md) for the lookup order.
2. **Never run a live write op without confirming scope with the user first**, OR without a successful `--dry-run` pass
   against the exact same flags first.
3. **Never paste credentials into chat, commits, PR bodies, or shell history.** Pass secrets through env vars
   (`XURL_BEARER_TOKEN`, `--client-secret "$(op read op://...)"`) — never inline them.
4. **Read-only probes are always fine**: `xr --help`, `xr  --help`, `xr examples`, `xr schema ...`, `xr validate , or refresh this bundle
with `xr skill update claude_code` (or whichever host).

## Reference index

- [references/escalation.md](references/escalation.md) — when stuck: lookup order, iron rules, halt-vs-continue, worked
  examples.
- [references/self-introspection.md](references/self-introspection.md) — let the binary teach you (`examples`, `schema`,
  `validate`, `usage`).
- [references/auth-modes.md](references/auth-modes.md) — OAuth2 PKCE (browser + headless), OAuth1, Bearer, multi-app
  token store.
- [references/agent-flags.md](references/agent-flags.md) — output formats, pagination, dry-run, env-var precedence, exit
  codes.
- [references/output-envelope.md](references/output-envelope.md) — the `ok` / `dry_run` / `error` envelope, typed
  reasons, exit-code matrix.
- [references/x-api-essentials.md](references/x-api-essentials.md) — drift-resistant pointers into the X API (auth
  scopes, tiers, rate limits).

## Templates

- [templates/oauth2-setup.md](templates/oauth2-setup.md) — first-time OAuth2 (browser or headless), verify with `xr auth
  status`.
- [templates/post-reply-thread.md](templates/post-reply-thread.md) — compose, capture id, thread; leads with
  `scripts/dry-run-gate.sh`.
- [templates/search-and-process.md](templates/search-and-process.md) — `xr search --output jsonl | jaq`; leads with
  `scripts/paginate.sh`.
- [templates/media-upload.md](templates/media-upload.md) — chunked upload, attach `--media-id` via the gate.

## Scripts

- [scripts/dry-run-gate.sh](scripts/dry-run-gate.sh) — preflight → confirm → live wrapper for every `xr` write op.
- [scripts/paginate.sh](scripts/paginate.sh) — cursor-pagination loop for any `xr` list-style verb.
- [scripts/README.md](scripts/README.md) — full contract, exit codes, invocation patterns, jaq/jq fallback notes.

## Producer-side notes

This file is the *consumer* entry point and is loaded into the agent's context when the skill activates. *Producer-side*
notes for agents working **on** this bundle (release flow, branch model, CI) live in [AGENTS.md](AGENTS.md). Don't
conflate the two.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [brettdavies](https://github.com/brettdavies)
- **Source:** [brettdavies/xurl-rs-skill](https://github.com/brettdavies/xurl-rs-skill)
- **License:** Apache-2.0
- **Homepage:** https://github.com/brettdavies/xurl-rs

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-brettdavies-xurl-rs-skill-xurl-rs-skill
- Seller: https://agentstack.voostack.com/s/brettdavies
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.