feat: support relay profile selection

README.md

@@ -1,12 +1,13 @@
 # bird 🐦 — fast X CLI for tweeting, replying, and reading
 
-`bird` is a fast X CLI for tweeting, replying, and reading via X/Twitter GraphQL through twitter safe relay.
+`bird` is a fast X CLI for tweeting, replying, and reading via X/Twitter GraphQL through
+[twitter safe relay](https://github.com/fa0311/twitter_api_safe_relay).
 
 ## Disclaimer
 
 This project uses X/Twitter’s [**documented**](https://github.com/fa0311/TwitterInternalAPIDocument) internal web
-GraphQL API through twitter safe relay. X can change endpoints, query IDs, and anti-bot behavior at any time —
-**expect this to break without notice**.
+GraphQL API through [twitter safe relay](https://github.com/fa0311/twitter_api_safe_relay). X can change endpoints,
+query IDs, and anti-bot behavior at any time — **expect this to break without notice**.
 
 ## Install
 
@@ -17,7 +18,7 @@ npm config set @yuta:registry=https://git.yutakobayashi.com/api/packages/yuta/np
 npm install -g @yuta/bird
 
 # one-shot (no install)
-npx -y @yuta/bird whoami
+npx -y --@yuta:registry=https://git.yutakobayashi.com/api/packages/yuta/npm/ @yuta/bird whoami
 ```
 
 Nix flakes:
@@ -26,12 +27,6 @@ Nix flakes:
 nix run git+https://git.yutakobayashi.com/yuta/bird -- --help
 ```
 
-Homebrew (macOS, prebuilt Bun binary):
-
-```bash
-brew install steipete/tap/bird
-```
-
 ## Quickstart
 
 ```bash
@@ -139,7 +134,8 @@ By default, the command fetches from For You, News, Sports, and Entertainment ta
 import { TwitterClient } from '@yuta/bird';
 
 const client = new TwitterClient({
-  relayBaseUrl: process.env.TWITTER_RELAY_BASE_URL
+  relayBaseUrl: process.env.TWITTER_RELAY_BASE_URL,
+  profileName: process.env.BIRD_PROFILE_NAME
 });
 
 // Search for tweets
@@ -190,6 +186,7 @@ const sportsNews = await client.getNews(10, {
 
 Global options:
 - `--relay-base-url <url>`: twitter safe relay base URL (defaults to `TWITTER_RELAY_BASE_URL`).
+- `--profile-name <name>`: twitter safe relay profile name (sent as `x-profile-name`).
 - `--timeout <ms>`: abort requests after the given timeout (milliseconds).
 - `--quote-depth <n>`: max quoted tweet depth in JSON output (default: 1; 0 disables).
 - `--plain`: stable output (no emoji, no color).
@@ -200,14 +197,16 @@ Global options:
 
 ## Authentication (GraphQL)
 
-`bird` does not handle Twitter authentication locally. It sends Twitter API-compatible requests to twitter safe relay,
-and the relay handles authentication.
+`bird` does not handle Twitter authentication locally. It sends Twitter API-compatible requests to
+[twitter safe relay](https://github.com/fa0311/twitter_api_safe_relay), and the relay handles authentication.
 
 Write operations:
 - `tweet`/`reply` primarily use GraphQL (`CreateTweet`).
 - If GraphQL returns error `226` (“automated request”), `bird` falls back to the legacy `statuses/update.json` endpoint.
 
 Configure the relay URL with `TWITTER_RELAY_BASE_URL` or `--relay-base-url`.
+When your relay has multiple profiles, select one with `--profile-name`, `BIRD_PROFILE_NAME`, or `profileName`
+in config; bird forwards it as the `x-profile-name` header.
 
 ## Config (JSON5)
 
@@ -221,6 +220,7 @@ Example `~/.config/bird/config.json5`:
 ```json5
 {
   relayBaseUrl: "http://localhost:6900",
+  profileName: "main",
   timeoutMs: 20000,
   quoteDepth: 1
 }
@@ -228,6 +228,7 @@ Example `~/.config/bird/config.json5`:
 
 Environment shortcuts:
 - `TWITTER_RELAY_BASE_URL`
+- `BIRD_PROFILE_NAME`
 - `BIRD_TIMEOUT_MS`
 - `BIRD_QUOTE_DEPTH`
 

src/cli/program.ts

@@ -105,14 +105,15 @@ export function createProgram(ctx: CliContext): Command {
       `\n\n${ctx.colors.section('Config')}\n${ctx.colors.muted(
         `  Reads ${ctx.colors.argument('~/.config/bird/config.json5')} and ${ctx.colors.argument('./.birdrc.json5')} (JSON5)`,
       )}\n${ctx.colors.muted(
-        `  Supports: relayBaseUrl, timeoutMs, quoteDepth`,
+        `  Supports: relayBaseUrl, profileName, timeoutMs, quoteDepth`,
       )}\n\n${ctx.colors.section('Env')}\n${ctx.colors.muted(
-        `  ${ctx.colors.option('TWITTER_RELAY_BASE_URL')}, ${ctx.colors.option('NO_COLOR')}, ${ctx.colors.option('BIRD_TIMEOUT_MS')}, ${ctx.colors.option('BIRD_QUOTE_DEPTH')}`,
+        `  ${ctx.colors.option('TWITTER_RELAY_BASE_URL')}, ${ctx.colors.option('BIRD_PROFILE_NAME')}, ${ctx.colors.option('NO_COLOR')}, ${ctx.colors.option('BIRD_TIMEOUT_MS')}, ${ctx.colors.option('BIRD_QUOTE_DEPTH')}`,
       )}`,
   );
 
   program
     .option('--relay-base-url <url>', 'twitter safe relay base URL', ctx.config.relayBaseUrl)
+    .option('--profile-name <name>', 'twitter safe relay profile name')
     .option('--media <path>', 'Attach media file (repeatable, up to 4 images or 1 video)', collect)
     .option('--alt <text>', 'Alt text for the corresponding --media (repeatable)', collect)
     .option('--timeout <ms>', 'Request timeout in milliseconds')

src/cli/shared.ts

@@ -17,6 +17,7 @@ import type { TweetData } from '../lib/twitter-client.js';
 
 export type BirdConfig = {
   relayBaseUrl?: string;
+  profileName?: string;
   timeoutMs?: number;
   quoteDepth?: number;
 };
@@ -44,6 +45,7 @@ export type CliContext = {
   applyOutputFromCommand: (command: Command) => void;
   resolveTimeoutFromOptions: (options: { timeout?: string | number }) => number | undefined;
   resolveQuoteDepthFromOptions: (options: { quoteDepth?: string | number }) => number | undefined;
+  resolveProfileNameFromOptions: (opts: ProfileOptions) => string | undefined;
   resolveRelayBaseUrlFromOptions: (opts: RelayOptions) => string | undefined;
   loadMedia: (opts: { media: string[]; alts: string[] }) => MediaSpec[];
   printTweets: (tweets: TweetData[], opts?: { json?: boolean; emptyMessage?: string; showSeparator?: boolean }) => void;
@@ -138,6 +140,10 @@ type RelayOptions = {
   relayBaseUrl?: string;
 };
 
+type ProfileOptions = {
+  profileName?: string;
+};
+
 export function createCliContext(normalizedArgs: string[], env: NodeJS.ProcessEnv = process.env): CliContext {
   const isTty = process.stdout.isTTY;
   let output: OutputConfig = resolveOutputConfigFromArgv(normalizedArgs, env, isTty);
@@ -235,6 +241,10 @@ export function createCliContext(normalizedArgs: string[], env: NodeJS.ProcessEn
     return opts.relayBaseUrl || config.relayBaseUrl || env.TWITTER_RELAY_BASE_URL;
   }
 
+  function resolveProfileNameFromOptions(opts: ProfileOptions): string | undefined {
+    return opts.profileName || env.BIRD_PROFILE_NAME || config.profileName;
+  }
+
   function loadMedia(opts: { media: string[]; alts: string[] }): MediaSpec[] {
     if (opts.media.length === 0) {
       return [];
@@ -367,6 +377,7 @@ export function createCliContext(normalizedArgs: string[], env: NodeJS.ProcessEn
     applyOutputFromCommand,
     resolveTimeoutFromOptions,
     resolveQuoteDepthFromOptions,
+    resolveProfileNameFromOptions,
     resolveRelayBaseUrlFromOptions,
     loadMedia,
     printTweets,

src/commands/bookmarks.ts

@@ -35,6 +35,7 @@ export function registerBookmarksCommand(program: Command, ctx: CliContext): voi
         }
         const maxPages = maxPagesParsed.value;
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
         const usePagination = Boolean(cmdOpts.all || cmdOpts.cursor);
         if (maxPages !== undefined && !usePagination) {
@@ -46,7 +47,7 @@ export function registerBookmarksCommand(program: Command, ctx: CliContext): voi
           process.exit(1);
         }
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
         const folderId = cmdOpts.folderId ? extractBookmarkFolderId(cmdOpts.folderId) : null;
         if (cmdOpts.folderId && !folderId) {
           console.error(`${ctx.p('err')}Invalid --folder-id. Expected numeric ID or https://x.com/i/bookmarks/<id>.`);

src/commands/check.ts

@@ -10,6 +10,7 @@ export function registerCheckCommand(program: Command, ctx: CliContext): void {
       const opts = program.opts();
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
       console.log(`${ctx.p('info')}Relay check`);
       console.log('-'.repeat(40));
@@ -21,7 +22,7 @@ export function registerCheckCommand(program: Command, ctx: CliContext): void {
 
       console.log(`${ctx.p('ok')}relay: ${relayBaseUrl}`);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
       const result = await client.getCurrentUser();
 
       if (result.success && result.user) {

src/commands/home.ts

@@ -15,13 +15,14 @@ export function registerHomeCommand(program: Command, ctx: CliContext): void {
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const count = Number.parseInt(cmdOpts.count || '20', 10);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
       if (!Number.isFinite(count) || count <= 0) {
         console.error(`${ctx.p('err')}Invalid --count. Expected a positive integer.`);
         process.exit(1);
       }
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
       const includeRaw = cmdOpts.jsonFull ?? false;
 
       const result = cmdOpts.following

src/commands/lists.ts

@@ -43,8 +43,9 @@ export function registerListsCommand(program: Command, ctx: CliContext): void {
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const count = Number.parseInt(cmdOpts.count || '100', 10);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
 
       const result = cmdOpts.memberOf ? await client.getListMemberships(count) : await client.getOwnedLists(count);
 
@@ -109,8 +110,9 @@ export function registerListsCommand(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
         const timelineOptions = { includeRaw };
         const paginationOptions = { includeRaw, maxPages: pagination.maxPages, cursor: pagination.cursor };

src/commands/news.ts

@@ -102,6 +102,7 @@ export function registerNewsCommand(program: Command, ctx: CliContext): void {
         const count = Number.parseInt(cmdOpts.count || '10', 10);
         const tweetsPerItem = Number.parseInt(cmdOpts.tweetsPerItem || '5', 10);
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
         if (Number.isNaN(count) || count < 1) {
           console.error(`${ctx.p('err')}--count must be a positive number`);
@@ -134,7 +135,7 @@ export function registerNewsCommand(program: Command, ctx: CliContext): void {
         // If no specific tabs selected, use defaults (all tabs except trending)
         const tabsToFetch = tabs.length > 0 ? tabs : undefined;
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
         const withTweets = cmdOpts.withTweets ?? false;
         const aiOnly = cmdOpts.aiOnly ?? false;

src/commands/post.ts

@@ -41,7 +41,8 @@ export function registerPostCommands(program: Command, ctx: CliContext): void {
         process.exit(1);
       }
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
       const mediaIds = await uploadMediaOrExit(client, media, ctx);
       const result = await client.tweet(text, mediaIds);
 
@@ -72,9 +73,10 @@ export function registerPostCommands(program: Command, ctx: CliContext): void {
       }
       const tweetId = ctx.extractTweetId(tweetIdOrUrl);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
       console.error(`${ctx.p('info')}Replying to tweet: ${tweetId}`);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
       const mediaIds = await uploadMediaOrExit(client, media, ctx);
       const result = await client.reply(text, tweetId, mediaIds);
 

src/commands/read.ts

@@ -18,8 +18,9 @@ export function registerReadCommands(program: Command, ctx: CliContext): void {
 
       const tweetId = ctx.extractTweetId(tweetIdOrUrl);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
       const includeRaw = cmdOpts.jsonFull ?? false;
       const result = await client.getTweet(tweetId, { includeRaw });
 
@@ -69,8 +70,9 @@ export function registerReadCommands(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
 
         const result = pagination.usePagination
@@ -136,8 +138,9 @@ export function registerReadCommands(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
 
         const result = pagination.usePagination

src/commands/search.ts

@@ -32,6 +32,7 @@ export function registerSearchCommands(program: Command, ctx: CliContext): void
         const count = Number.parseInt(cmdOpts.count || '10', 10);
         const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
         const usePagination = cmdOpts.all || cmdOpts.cursor;
         if (maxPages !== undefined && !usePagination) {
@@ -47,7 +48,7 @@ export function registerSearchCommands(program: Command, ctx: CliContext): void
           process.exit(1);
         }
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
         const searchOptions = { includeRaw };
         const paginationOptions = { includeRaw, maxPages, cursor: cmdOpts.cursor };
@@ -90,8 +91,9 @@ export function registerSearchCommands(program: Command, ctx: CliContext): void
 
       let query: string | null = fromUserOpt.query;
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
 
       if (!query) {
         const who = await client.getCurrentUser();

src/commands/unbookmark.ts

@@ -11,8 +11,9 @@ export function registerUnbookmarkCommand(program: Command, ctx: CliContext): vo
       const opts = program.opts();
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
       let failures = 0;
 
       for (const input of tweetIdOrUrls) {

src/commands/user-tweets.ts

@@ -87,8 +87,9 @@ export function registerUserTweetsCommand(program: Command, ctx: CliContext): vo
           process.exit(2);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
 
         // Look up user ID from username
         console.error(`${ctx.p('info')}Looking up @${username}...`);

src/commands/users.ts

@@ -37,8 +37,9 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
 
         let userId = cmdOpts.user;
         if (!userId) {
@@ -187,8 +188,9 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs });
 
         let userId = cmdOpts.user;
         if (!userId) {
@@ -328,6 +330,7 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
         const count = Number.parseInt(cmdOpts.count || '20', 10);
         const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
         const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+        const profileName = ctx.resolveProfileNameFromOptions(opts);
 
         const usePagination = cmdOpts.all || cmdOpts.cursor;
         if (maxPages !== undefined && !usePagination) {
@@ -343,7 +346,7 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
           process.exit(1);
         }
 
-        const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+        const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
         const includeRaw = cmdOpts.jsonFull ?? false;
         const timelineOptions = { includeRaw };
         const paginationOptions = { includeRaw, maxPages, cursor: cmdOpts.cursor };
@@ -373,8 +376,9 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
       const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
       const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
       const relayBaseUrl = ctx.resolveRelayBaseUrlFromOptions(opts);
+      const profileName = ctx.resolveProfileNameFromOptions(opts);
 
-      const client = new TwitterClient({ relayBaseUrl, timeoutMs, quoteDepth });
+      const client = new TwitterClient({ relayBaseUrl, profileName, timeoutMs, quoteDepth });
       const result = await client.getCurrentUser();
 
       if (result.success && result.user) {

src/lib/twitter-client-base.ts

@@ -15,12 +15,14 @@ export type Mixin<TBase extends AbstractConstructor<TwitterClientBase>, TAdded>
 
 export abstract class TwitterClientBase {
   protected relayBaseUrl: string;
+  protected profileName?: string;
   protected timeoutMs?: number;
   protected quoteDepth: number;
   protected clientUserId?: string;
 
   constructor(options: TwitterClientOptions) {
     this.relayBaseUrl = this.normalizeRelayBaseUrl(options.relayBaseUrl ?? process.env.TWITTER_RELAY_BASE_URL);
+    this.profileName = this.normalizeProfileName(options.profileName);
     this.timeoutMs = options.timeoutMs;
     this.quoteDepth = normalizeQuoteDepth(options.quoteDepth);
   }
@@ -73,7 +75,7 @@ export abstract class TwitterClientBase {
   }
 
   protected getHeaders(): Record<string, string> {
-    return {};
+    return this.profileName ? { 'x-profile-name': this.profileName } : {};
   }
 
   private normalizeRelayBaseUrl(value: string | undefined): string {
@@ -84,6 +86,11 @@ export abstract class TwitterClientBase {
     return trimmed.replace(TRAILING_SLASHES, '');
   }
 
+  private normalizeProfileName(value: string | undefined): string | undefined {
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+  }
+
   private toRelayUrl(url: string): string {
     const parsed = new URL(url);
     if (!['x.com', 'twitter.com', 'api.twitter.com', 'upload.twitter.com'].includes(parsed.hostname)) {
@@ -93,11 +100,11 @@ export abstract class TwitterClientBase {
   }
 
   protected getJsonHeaders(): Record<string, string> {
-    return { 'content-type': 'application/json' };
+    return { 'content-type': 'application/json', ...this.getHeaders() };
   }
 
   protected getUploadHeaders(): Record<string, string> {
-    return {};
+    return this.getHeaders();
   }
 
   protected async ensureClientUserId(): Promise<void> {

src/lib/twitter-client-types.ts

@@ -326,6 +326,7 @@ export interface FollowingResult {
 
 export interface TwitterClientOptions {
   relayBaseUrl?: string;
+  profileName?: string;
   timeoutMs?: number;
   // Max depth for quoted tweets (0 disables). Defaults to 1.
   quoteDepth?: number;

src/lib/twitter-client-users.ts

@@ -205,11 +205,15 @@ export function withUsers<TBase extends AbstractConstructor<TwitterClientBase>>(
               ? data.user_id
               : typeof data?.user_id_str === 'string'
                 ? data.user_id_str
-                : typeof data?.user?.id_str === 'string'
-                  ? data.user.id_str
-                  : typeof data?.user?.id === 'string'
-                    ? data.user.id
-                    : null;
+                : typeof data?.id_str === 'string'
+                  ? data.id_str
+                  : typeof data?.id === 'string'
+                    ? data.id
+                    : typeof data?.user?.id_str === 'string'
+                      ? data.user.id_str
+                      : typeof data?.user?.id === 'string'
+                        ? data.user.id
+                        : null;
 
           if (username && userId) {
             this.clientUserId = userId;

tests/cli.shared.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { createCliContext } from '../src/cli/shared.js';
+
+describe('createCliContext', () => {
+  it('resolves profileName from CLI options before env', () => {
+    const ctx = createCliContext([], { BIRD_PROFILE_NAME: 'env-profile' } as NodeJS.ProcessEnv);
+
+    expect(ctx.resolveProfileNameFromOptions({ profileName: 'cli-profile' })).toBe('cli-profile');
+  });
+
+  it('resolves profileName from env when CLI option is absent', () => {
+    const ctx = createCliContext([], { BIRD_PROFILE_NAME: 'env-profile' } as NodeJS.ProcessEnv);
+
+    expect(ctx.resolveProfileNameFromOptions({})).toBe('env-profile');
+  });
+});

tests/commands.bookmarks.test.ts

@@ -9,6 +9,7 @@ describe('bookmarks command', () => {
     const ctx = {
       resolveTimeoutFromOptions: () => undefined,
       resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
+      resolveProfileNameFromOptions: () => undefined,
       p: () => '',
       printTweets: () => undefined,
     } as unknown as CliContext;

tests/commands.news.test.ts

@@ -14,6 +14,7 @@ describe('news command', () => {
       resolveTimeoutFromOptions: () => 30000,
       resolveQuoteDepthFromOptions: () => undefined,
       resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
+      resolveProfileNameFromOptions: () => undefined,
       p: (type: string) => `[${type}] `,
       colors: {
         accent: (text: string) => text,

tests/commands.read.test.ts

@@ -9,6 +9,7 @@ describe('replies command', () => {
     ({
       resolveTimeoutFromOptions: () => undefined,
       resolveQuoteDepthFromOptions: () => 1,
+      resolveProfileNameFromOptions: () => undefined,
       extractTweetId: (input: string) => input,
       resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
       p: () => '',
@@ -74,6 +75,38 @@ describe('replies command', () => {
       errorSpy.mockRestore();
     }
   });
+
+  it('passes profileName to TwitterClient', async () => {
+    const program = new Command();
+    registerReadCommands(program, {
+      ...createMockContext(),
+      resolveProfileNameFromOptions: () => 'work',
+    });
+
+    const getTweetSpy = vi.spyOn(TwitterClient.prototype, 'getTweet').mockImplementation(async function () {
+      const headers = (this as unknown as { getHeaders: () => Record<string, string> }).getHeaders();
+      expect(headers).toEqual({ 'x-profile-name': 'work' });
+      return {
+        success: true,
+        tweet: {
+          id: '123',
+          text: 'hello',
+          author: { username: 'tester', name: 'Tester' },
+          createdAt: '2024-01-01T00:00:00Z',
+          url: 'https://x.com/tester/status/123',
+        },
+      };
+    });
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+    try {
+      await program.parseAsync(['node', 'bird', 'read', '123', '--json']);
+      expect(getTweetSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      getTweetSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
 });
 
 describe('thread command', () => {
@@ -81,6 +114,7 @@ describe('thread command', () => {
     ({
       resolveTimeoutFromOptions: () => undefined,
       resolveQuoteDepthFromOptions: () => 1,
+      resolveProfileNameFromOptions: () => undefined,
       extractTweetId: (input: string) => input,
       resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
       p: () => '',

tests/commands.search.test.ts

@@ -14,6 +14,7 @@ describe('search command', () => {
       resolveTimeoutFromOptions: () => undefined,
       resolveQuoteDepthFromOptions: () => undefined,
       resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
+      resolveProfileNameFromOptions: () => undefined,
       p: () => '',
       printTweetsResult: vi.fn(),
     };

tests/commands.users.test.ts

@@ -7,6 +7,7 @@ import { TwitterClient } from '../src/lib/twitter-client.js';
 const baseCtx = {
   resolveTimeoutFromOptions: () => undefined,
   resolveRelayBaseUrlFromOptions: () => 'https://relay.example',
+  resolveProfileNameFromOptions: () => undefined,
   p: () => '',
   printTweets: () => undefined,
 } as unknown as CliContext;

tests/help-output.test.ts

@@ -46,6 +46,7 @@ describe('root help output', () => {
     cmd.outputHelp();
 
     expect(help).toContain('--relay-base-url');
+    expect(help).toContain('--profile-name');
     expect(help).not.toContain('--auth-token');
     expect(help).not.toContain('--ct0');
     expect(help).toContain('--timeout');

tests/twitter-client-coverage.core.test.ts

@@ -124,6 +124,41 @@ describe('TwitterClient core coverage', () => {
     expect(headers).toEqual({});
   });
 
+  it('adds x-profile-name header when profileName is set', () => {
+    const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl, profileName: 'work' });
+    const clientPrivate = client as unknown as TwitterClientPrivate;
+
+    expect(clientPrivate.getHeaders()).toEqual({ 'x-profile-name': 'work' });
+  });
+
+  it('ignores blank profileName values', () => {
+    const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl, profileName: '   ' });
+    const clientPrivate = client as unknown as TwitterClientPrivate;
+
+    expect(clientPrivate.getHeaders()).toEqual({});
+  });
+
+  it('adds x-profile-name to JSON headers when profileName is set', () => {
+    const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl, profileName: 'work' });
+    const clientPrivate = client as unknown as TwitterClientPrivate & {
+      getJsonHeaders: () => Record<string, string>;
+    };
+
+    expect(clientPrivate.getJsonHeaders()).toEqual({
+      'content-type': 'application/json',
+      'x-profile-name': 'work',
+    });
+  });
+
+  it('adds x-profile-name to upload headers when profileName is set', () => {
+    const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl, profileName: 'work' });
+    const clientPrivate = client as unknown as TwitterClientPrivate & {
+      getUploadHeaders: () => Record<string, string>;
+    };
+
+    expect(clientPrivate.getUploadHeaders()).toEqual({ 'x-profile-name': 'work' });
+  });
+
   describe('fetchUserArticlePlainText failures', () => {
     it('returns empty object when response is not ok', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeResponse({ ok: false, status: 500 }));

tests/twitter-client.current-user.test.ts

@@ -107,6 +107,24 @@ describe('TwitterClient getCurrentUser', () => {
     expect(mockFetch).toHaveBeenCalledTimes(2);
   });
 
+  it('reads top-level id_str from verify_credentials responses', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        id_str: '12345',
+        screen_name: 'tester',
+        name: 'Test User',
+      }),
+    });
+
+    const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(true);
+    expect(result.user).toEqual({ id: '12345', username: 'tester', name: 'Test User' });
+  });
+
   it('continues on fetch errors and still succeeds via later API endpoint', async () => {
     mockFetch
       .mockRejectedValueOnce(new Error('boom'))