| name | x-cli |
| description | Use this skill when the task is to authenticate with X, fetch timelines, tweets, users, search results, followers, or following data through x-cli, or to troubleshoot x-cli auth, rate limits, and GraphQL query ID drift. |
| license | MIT |
| metadata | {"author":"Gladium AI","version":"1.0.0","category":"developer-tools","tags":["x","twitter","cli","graphql","scraping","golang"]} |
X CLI
Use this skill to operate x-cli safely and consistently.
Use This Skill For
- Logging into X through the browser-based auth flow
- Fetching home timelines, user timelines, tweets, user profiles, search results, followers, or following lists
- Using
--json output for downstream parsing or automation
- Diagnosing auth failures, rate limits, pagination, or GraphQL query ID rotation
- Updating or validating the CLI's endpoint/query ID registry when X changes its internal API
Core Rules
- Prefer
x-cli over ad hoc curl requests to X when the CLI surface already covers the task.
- Prefer
--json when another tool, agent, or script will consume the output.
- Treat
~/.x-cli/credentials.json as managed state. Use x-cli auth login, status, and logout instead of editing it manually.
- Use
tweet get with either a tweet ID or full X URL.
- Expect cursor-based pagination on list commands and preserve returned cursors when continuing a session.
- If multiple commands start returning
404 responses, suspect GraphQL query ID drift in internal/api/endpoints.go.
Quick Workflow
- Verify the binary and auth state.
- Authenticate if needed.
- Run the smallest command that answers the task.
- Switch to
--json for parsing or handoff.
- Follow pagination cursors or
--all only when the user wants broader retrieval.
- Use
--verbose when debugging HTTP failures or endpoint drift.
Prerequisites
x-cli available on PATH, or use the repo-local binary.- Google Chrome installed for browser-based login.
- A valid X account session.
For repo-local build and install commands, see references/install-and-build.md.
Standard Command Path
For a typical session:
x-cli auth status
x-cli auth login
x-cli timeline home --count 20
x-cli tweet get https://x.com/jack/status/20 --json
x-cli user get @jack
x-cli search "golang" --type latest --json
For follower graph inspection:
x-cli followers @jack --count 50
x-cli following @jack --count 50 --json
Load references/command-map.md when you need exact command shapes, pagination flags, or a quick reminder of the command surface.
Troubleshooting
- Start with
x-cli auth status to confirm stored credentials are present.
- Use
--verbose to inspect request URLs, HTTP codes, and raw response details.
- If pagination stalls or you need the next page later, reuse the emitted cursor exactly.
- If commands fail after a long idle period, re-run
x-cli auth login.
- If several commands return
404 or start failing at once, inspect internal/api/endpoints.go and refresh the query IDs from X's current web bundle.
For auth, rate-limit, and endpoint-drift notes, read references/auth-and-debugging.md.
Source: freecodexyz/x-cli — distributed by TomeVault.
