# Xsearch

> Use when an agent needs to perform Twitter/X research with the local xsearch CLI, including checking auth status, importing user-provided cookies, searching posts/users, retrieving posts by ID, and handling JSON-only command output without exposing cookie secrets.

- Skill: `labyla/xsearch` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add labyla/xsearch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/labyla/xsearch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: labyla (https://skillmd.com/u/labyla)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/labyla/xsearch

---


# X/Twitter Research With xsearch

Use the local `xsearch` CLI when the user asks to retrieve or search Twitter/X content and provides, or has already configured, an authenticated cookie session.

## Ground Rules

- Treat `auth.cookies` as a secret.
- Never print raw cookies in final answers, logs, examples, or error summaries.
- All `xsearch` command output is JSON, including errors and help.
- Prefer using the CLI rather than editing core request logic.
- Do not add commands or change the CLI contract during research tasks.

## Config

Default config file:

```text
~/.xsearch/config.json
```

Schema:

```json
{
  "auth": {
    "cookies": ""
  },
  "network": {
    "proxy": "",
    "user_agent": ""
  }
}
```

`auth.cookies` is a Cookie header string, not a JSON array.

Useful setup commands:

```bash
xsearch config init
xsearch config show
xsearch config set auth.cookies "<cookie-header>"
xsearch config set network.proxy <value>
xsearch config set network.user_agent <value>
xsearch auth status
```

## Importing Cookies

Import browser-export cookies from a file:

```bash
xsearch auth import-cookies /path/to/cookies.json
```

Import from stdin:

```bash
cat /path/to/cookies.json | xsearch auth import-cookies -
```

Accepted input formats:

- JSON object with a `cookies` array.
- Raw JSON array of cookie objects.
- Existing Cookie header string, for example `auth_token=...; ct0=...; twid=...`.

The command stores only `name=value` pairs in `auth.cookies` and redacts cookie values in output.

Common error codes:

- `CONFIG_NOT_FOUND`: run `xsearch config init`.
- `INVALID_COOKIES_FORMAT`: cookie input could not be parsed.
- `COOKIES_EMPTY`: no usable non-empty cookie names and values were found.

## Research Commands

Map the user's request to one of the existing commands:

- Search posts, tweets, mentions, hashtags, or topics: `xsearch search-posts <query>`
- Search accounts, profiles, handles, or users: `xsearch search-users <query>`
- Inspect one post/tweet by ID: `xsearch get-post <post_id>`

Retrieve one post:

```bash
xsearch get-post <post_id>
```

Search posts:

```bash
xsearch search-posts <query>
```

Search users:

```bash
xsearch search-users <query>
```

Fetch another page of the same search:

```bash
xsearch search-posts <query> --cursor <cursor_bottom>
xsearch search-users <query> --cursor <cursor_bottom>
```

Quote queries in the shell when they contain spaces or operators:

```bash
xsearch search-posts "from:openai lang:en -filter:replies"
```

## Build Search Queries

When the user gives structured constraints, convert them into one query string. Join non-empty blocks with one space in this order:

1. words block
2. negative words block
3. hashtags block
4. from-users block
5. language block
6. replies filter block

Use these formats:

- Words: `(word1 OR word2 OR ...)`
- Negative words: `-word`
- Hashtags: `(#tag1 OR #tag2 OR ...)`; add `#` automatically for raw tag names.
- From users: `(from:user1 OR from:user2 OR ...)`; use lowercase usernames without `@`.
- Language: append as-is, usually `lang:en`.
- Exclude replies: append `-filter:replies`; include replies by omitting this block.

Practical examples:

```text
(release OR update) (from:openai OR from:github) lang:en -filter:replies
(solana) -scam -giveaway (#sol OR #crypto) lang:en -filter:replies
(from:nasa OR from:spacex)
```

Practical rules:

- Quote tokens that contain spaces before inserting them into a query.
- Do not include `#` in raw hashtag input when you are building the hashtag block yourself.
- Keep the user's exact intent; do not add filters such as `lang:en` or `-filter:replies` unless requested or clearly implied.

## Pagination

Search responses include `cursor_top` and `cursor_bottom`.

For normal forward pagination, pass `cursor_bottom` back to the same command with the same query:

```bash
xsearch search-posts "open source ai lang:en" --cursor "<cursor_bottom>"
```

Keep the query unchanged while paginating. If pagination returns no new results or an auth error, report that the configured session may need refresh or that X/Twitter returned no additional page.

## Output Handling

All command output is JSON. Parse the JSON and summarize relevant fields rather than pasting raw payloads by default.

- On success, read from `data`.
- For search commands, use `data.posts` or `data.users` and retain `cursor_bottom` when the user may want more results.
- On error, report the JSON `error.message` and `error.code` when present.
- Do not expose `auth.cookies`, imported cookie input, or config secrets.

## Workflow

1. Check auth with `xsearch auth status`.
2. If auth is missing and the user supplied cookies, import them with `xsearch auth import-cookies <path>` or `-`.
3. Build a query string when the user gives structured constraints.
4. Run the mapped search or retrieval command.
5. Parse the JSON output, summarize relevant results, and keep `cursor_bottom` available for follow-up pagination.
6. If a command fails, report the JSON error code/message and the action needed; do not expose secrets.

## Reporting Results

When summarizing search results, include only what the CLI returned. Avoid claiming completeness, ranking guarantees, or freshness beyond the command output. For failures caused by authentication or X/Twitter access restrictions, say that the configured session may need to be refreshed.