Twitter / X

Use the twitter global in the REPL tool. It allows you to control the X/Twitter website with API interface- no tab open needed.

Quick Reference

js
// Auth check
const me = await twitter.getMe();
console.log(me); // → { id, screenName, name, description, followersCount, ... }

// Timeline (Following tab, chronological)
const timeline = await twitter.getTimeline({ count: 20 });
console.log(timeline.tweets.map(t => `@${t.author.screenName}: ${t.text.slice(0, 80)}`));

// Search
const results = await twitter.search('AI agents', { count: 20, product: 'Latest' });
console.log(results.tweets);

// Get a specific tweet
const tweet = await twitter.getTweet('1234567890');
console.log(tweet);

// Get the visible same-author thread from a tweet page
const thread = await twitter.getTweetThread('1234567890');
console.log(thread.tweets);

// Get user profile
const user = await twitter.getUser('steipete');
console.log(user);

// Post a tweet
const posted = await twitter.tweet('Hello from Aside!');
console.log(posted.id);

// Reply to a tweet
const reply = await twitter.reply('1234567890', 'Great thread!');

// Interactions
await twitter.like('1234567890');
await twitter.retweet('1234567890');
await twitter.bookmark('1234567890');

// Follow/unfollow (requires user ID, not handle)
await twitter.follow('123456');
await twitter.unfollow('123456');

// DMs
const inbox = await twitter.getDmInbox();
console.log(inbox.conversations);
const history = await twitter.getDmConversation('123-456');
console.log(history.messages);
await twitter.sendDm('123456', 'Hello!');

// Block/Mute
await twitter.block('123456');
await twitter.mute('123456');

// Notifications
const notifs = await twitter.getNotifications({ count: 10 });
console.log(notifs.notifications);

Methods

twitter.getMe(): Promise<XUser>

Get the authenticated user's profile.

twitter.getUser(screenName: string): Promise<XUser>

Get a user profile by screen name (handle, without @).

twitter.getTweet(tweetId: string): Promise<XTweet>

Get a single tweet by ID.

twitter.getTweetThread(tweetId: string): Promise<XTimelineResponse>

Get the focal tweet plus visible same-author replies in the thread. Use this for X status pages when the user asks what the current page/thread is about.

twitter.getTimeline(opts?): Promise<XTimelineResponse>

Get home timeline (Following tab, chronological).

• opts.count — Number of tweets (default 20).
• opts.cursor — Pagination cursor from previous response's nextCursor.

twitter.search(query: string, opts?): Promise<XTimelineResponse>

Search tweets.

• query — Search query (supports X search operators like from:user, to:user, since:2026-01-01).
• opts.count — Number of results (default 20).
• opts.product — 'Latest' (default), 'Top', 'People', 'Photos', 'Videos'.
• opts.cursor — Pagination cursor.

twitter.getUserTweets(screenName: string, opts?): Promise<XTimelineResponse>

Get a user's tweets by screen name.

• opts.count — Number of tweets (default 20).
• opts.cursor — Pagination cursor.

twitter.getBookmarks(opts?): Promise<XTimelineResponse>

Get bookmarked tweets.

twitter.tweet(text: string, opts?): Promise<XTweet>

Post a new tweet. Returns the created tweet.

• opts.mediaIds — Array of media IDs (from media upload) to attach.

twitter.reply(tweetId: string, text: string, opts?): Promise<XTweet>

Reply to a tweet. Returns the reply.

twitter.deleteTweet(tweetId: string): Promise<void>

twitter.like(tweetId: string): Promise<void>

twitter.unlike(tweetId: string): Promise<void>

twitter.retweet(tweetId: string): Promise<void>

twitter.unretweet(tweetId: string): Promise<void>

twitter.bookmark(tweetId: string): Promise<void>

twitter.unbookmark(tweetId: string): Promise<void>

twitter.follow(userId: string): Promise<void>

Follow by user ID. Get user ID from twitter.getUser(screenName).id.

twitter.unfollow(userId: string): Promise<void>

Unfollow by user ID.

twitter.getDmInbox(): Promise<XDmInbox>

Get DM inbox (list of conversations with last message preview).

twitter.getDmConversation(conversationId: string, opts?): Promise<XDmHistory>

Get messages in a DM conversation. Conversation ID format: "{lowerUserId}-{higherUserId}".

• opts.maxId — Pagination cursor for older messages (from nextCursor).

twitter.sendDm(userId: string, text: string, opts?): Promise<any>

Send a DM to a user by their user ID. Conversation ID is auto-constructed.

• opts.mediaId — Attach media (from media upload).
• opts.replyToId — Reply to a specific message.

twitter.block(userId: string): Promise<void>

twitter.unblock(userId: string): Promise<void>

twitter.mute(userId: string): Promise<void>

twitter.unmute(userId: string): Promise<void>

twitter.getNotifications(opts?): Promise<{ notifications: XNotification[]; nextCursor?: string }>

Get recent notifications.

• opts.count — Number of notifications (default 20).
• opts.cursor — Pagination cursor.

Types

ts
interface XUser {
  id: string;
  screenName: string;
  name: string;
  description: string;
  followersCount: number;
  followingCount: number;
  tweetCount: number;
  profileImageUrl: string;
  isBlueVerified: boolean;
}

interface XTweet {
  id: string;
  text: string;
  author: XUser;
  createdAt: Date;
  likes: number;
  retweets: number;
  replies: number;
  bookmarks: number;
  views: number;
  media: XMedia[];
  inReplyToId?: string;
  quotedTweet?: XTweet;
}

interface XMedia {
  type: 'photo' | 'video' | 'animated_gif';
  url: string;
  width: number;
  height: number;
}

interface XTimelineResponse {
  tweets: XTweet[];
  nextCursor?: string; // pass as opts.cursor for next page
}

interface XDmMessage {
  id: string;
  text: string;
  senderId: string;
  recipientId: string;
  createdAt: Date;
  mediaUrl?: string;
}

interface XDmConversation {
  conversationId: string;
  participants: string[]; // user IDs
  lastMessage?: XDmMessage;
}

interface XDmInbox { conversations: XDmConversation[] }
interface XDmHistory { messages: XDmMessage[]; nextCursor?: string }

interface XNotification {
  id: string;
  type: string;
  timestamp: Date;
  message: string;
  raw: any;
}