X CLI Operations

Procedures

Step 1: Identify the Operation

1. Determine the intent of the request (e.g., post a tweet, read bookmarks, search users).
2. Run python3 scripts/find-operation.py --search "<keyword>" to locate the matching operation ID.
3. If the keyword search returns no results, broaden the search or run python3 scripts/find-operation.py --tag "<tag>" with one of: Tweets, Users, Bookmarks, Lists, Direct Messages, Spaces, Media, Communities, Trends, News.
4. If uncertain about an operation's parameters, run xcli spec <operationId> to inspect required and optional fields.

Step 2: Construct the Command

1. Read references/operations.md to identify the correct parameter format and common field sets for the target operation.
2. Build the xcli command following these rules:
   • Path parameters (e.g., user ID, tweet ID) use -p "key=value" and auto-substitute in the URL.
   • Query parameters (e.g., tweet.fields, max_results) also use -p "key=value".
   • Request body fields use -f "key=value" for simple payloads or -b '{"json": "here"}' for complex nested bodies.
   • Append -r when piping output or when raw JSON is needed for further processing.

Step 3: Execute the Operation

1. Run python3 scripts/exec-operation.py <operationId> [options] to execute the command.
2. Parse the JSON response from stdout.
3. If the response contains meta.next_token, pagination is available. Re-run with -p "pagination_token=<token>" to fetch the next page.

Step 4: Handle Multi-Step Workflows

1. For operations requiring the authenticated user's ID, first run: python3 scripts/exec-operation.py getUsersMe -p "user.fields=id" Extract data.id from the response.
2. For reply threads, extract data.id from a createPosts response and pass it as reply.in_reply_to_tweet_id in the next post.
3. For bulk lookups, use comma-separated values: -p "ids=123,456,789".

Error Handling

• If scripts/exec-operation.py returns an HTTP 401/403 error, the OAuth tokens may be expired. Run xcli call getUsersMe to verify authentication. If that also fails, the MCP server needs to be restarted to refresh tokens.
• If an HTTP 402 "CreditsDepleted" error occurs, the operation requires a paid X API plan. Switch to an endpoint available on the free tier or inform the user about the plan limitation.
• If an HTTP 429 "TooManyRequests" error occurs, wait and retry after the rate limit window resets.
• If scripts/find-operation.py returns no results, run xcli list without filters and scan the full operation list for the closest match.