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:

~/.xsearch/config.json

Schema:

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

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

Useful setup commands:

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:

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

Import from stdin:

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:

xsearch get-post <post_id>

Search posts:

xsearch search-posts <query>

Search users:

xsearch search-users <query>

Fetch another page of the same search:

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:

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:

(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:

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.