@uniquedivine/tg-sai 0.0.4 → 0.0.5

package/main.ts

@@ -11,8 +11,11 @@ import {
 import { createRequire } from "node:module"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
+import { stdin as input, stdout as output } from "node:process"
+import { createInterface } from "node:readline/promises"
 import { Command } from "commander"
-
+import { addProvisionCommands } from "./provisioningCli"
+import { addCustodyWorkerCommands } from "./custodyWorkerCli"
 import type { BatchLogger } from "./actionExecutor"
 import { withFloodWaitRetry } from "./actionExecutor"
 import type {
@@ -23,6 +26,7 @@ import type {
 import { planAdminBootstrap } from "./adminAudit"
 import { saiBot, USERS } from "./cfg"
 import { runHealthCheck } from "./health"
+import { addRuntimeHealthCommands } from "./runtimeHealthCli"
 import {
   addTargetToChat,
   createMtcuteClient,
@@ -32,14 +36,20 @@ import {
   promoteTargetAdmin,
   transferTargetOwnership,
 } from "./mtcuteAdapter"
-import { formatSaiChatJsonLine, parseChatInputFile } from "./ops"
+import {
+  formatSaiChatJsonLine,
+  parseChatInputFile,
+  resolveBootstrapTarget,
+} from "./ops"
 import type { ChatInput } from "./ops"
 import {
   addProfile,
   configDir,
   discoveryReport,
+  findProfileIndex,
   getProfile,
   profileInputFromUser,
+  profileLabel,
   readConfig,
   redactedProfile,
   removeProfile,
@@ -106,8 +116,11 @@ interface SaiBootstrapOptions {
   run?: boolean
   /** Attempt ownership transfer when the Telegram password is available. */
   transferOwner?: boolean
+  /** Owner target: user ID or username. Defaults to the Sai custody account. */
+  targetUser?: number | string
 }
 
+
 interface TelegramEnv {
   apiId: number
   apiHash: string
@@ -116,7 +129,7 @@ interface TelegramEnv {
 }
 
 interface ProfileAddOptions {
-  name: string
+  name?: string
   apiId?: string
   apiHash?: string
   sessionString?: string
@@ -128,6 +141,7 @@ interface ProfileAddOptions {
   login?: boolean
   qr?: boolean
   phone?: boolean
+  interactive?: boolean
 }
 
 const saiBotAdminRights = {
@@ -285,12 +299,15 @@ async function getTelegramEnv(profileName?: string): Promise<TelegramEnv> {
   }
 }
 
-async function selectedProfileName(profileName?: string): Promise<string | null> {
+async function selectedProfileName(
+  profileName?: string,
+): Promise<string | null> {
   if (profileName) {
     return profileName
   }
   const config = await readConfig()
-  return config.activeProfile
+  const profile = config.profiles[0]
+  return profile ? profileLabel(profile, 0) : null
 }
 
 function parsePeer(value: string): number | string {
@@ -774,6 +791,7 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
     const actor = normalizeUser(await client.getMe())
     const actorUsername = actor.username ?? ""
     const profileName = await selectedProfileName(options.profile)
+    const ownerTarget = resolveBootstrapTarget(options.targetUser)
     const ownershipTransferEnabled =
       options.transferOwner !== false && env.password !== null
     console.log(`wrote_run_log: ${logPath}`)
@@ -787,7 +805,7 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
       transferOwner: ownershipTransferEnabled,
       passwordAvailable: env.password !== null,
       delayMs,
-      targetUser: USERS.uniqueDivine.id,
+      targetUser: ownerTarget,
       targetBot: saiBot.id,
     })
 
@@ -816,8 +834,8 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
             client,
             chat,
             actorUsername,
-            targetUserId: USERS.uniqueDivine.id,
-            targetPeer: USERS.uniqueDivine.handle,
+            targetUserId: ownerTarget,
+            targetPeer: ownerTarget,
             rights: ownerTargetAdminRights,
             actionPrefix: "owner_target",
             run: options.run === true,
@@ -827,7 +845,7 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
             env,
             chat,
             actorUsername,
-            targetUser: USERS.uniqueDivine.handle,
+            targetUser: ownerTarget,
             enabled: ownershipTransferEnabled,
             run: options.run === true,
           })
@@ -866,19 +884,6 @@ async function runSaiBootstrap(options: SaiBootstrapOptions): Promise<void> {
   })
 }
 
-function getCredentialsFromProfileAddOptions(
-  options: ProfileAddOptions,
-): TelegramCredentials | null {
-  if (options.apiId && options.apiHash && options.sessionString) {
-    return {
-      apiId: Number(options.apiId),
-      apiHash: options.apiHash,
-      sessionString: options.sessionString,
-    }
-  }
-  return null
-}
-
 function credentialValuesFromProfileAddOptions(
   options: ProfileAddOptions,
 ): TelegramCredentialValues {
@@ -890,6 +895,17 @@ function credentialValuesFromProfileAddOptions(
   }
 }
 
+function credentialValuesFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): TelegramCredentialValues {
+  return {
+    TELEGRAM_API_ID: env.TELEGRAM_API_ID,
+    TELEGRAM_API_HASH: env.TELEGRAM_API_HASH,
+    TELEGRAM_SESSION_STRING: env.TELEGRAM_SESSION_STRING,
+    TELEGRAM_PASSWORD: env.TELEGRAM_PASSWORD,
+  }
+}
+
 function profileFieldsFromCredentialValues(values: TelegramCredentialValues) {
   return {
     apiId: values.TELEGRAM_API_ID ? Number(values.TELEGRAM_API_ID) : null,
@@ -899,6 +915,10 @@ function profileFieldsFromCredentialValues(values: TelegramCredentialValues) {
   }
 }
 
+type ProfileCredentialFields = ReturnType<
+  typeof profileFieldsFromCredentialValues
+>
+
 function mergeCredentialValues(
   ...valuesList: Array<TelegramCredentialValues | null>
 ): TelegramCredentialValues {
@@ -916,10 +936,112 @@ function mergeCredentialValues(
   return merged
 }
 
+function redactedCredentialValue(key: string, value: string): string {
+  if (
+    key === "TELEGRAM_API_HASH" ||
+    key === "TELEGRAM_SESSION_STRING" ||
+    key === "TELEGRAM_PASSWORD"
+  ) {
+    return value ? "[redacted]" : ""
+  }
+  return value
+}
+
+function sourceLabel(candidate: DiscoveryReport["candidates"][number]): string {
+  return `${candidate.name} ${candidate.path} ${candidate.objectPath}`
+}
+
+function mergeDiscoveredValues(
+  candidates: DiscoveryReport["candidates"],
+): TelegramCredentialValues {
+  const merged: TelegramCredentialValues = {}
+  const origins: Partial<
+    Record<
+      keyof TelegramCredentialValues,
+      DiscoveryReport["candidates"][number]
+    >
+  > = {}
+
+  for (const candidate of candidates) {
+    for (const [key, value] of Object.entries(candidate.values)) {
+      if (value === undefined || value === "") {
+        continue
+      }
+      const typedKey = key as keyof TelegramCredentialValues
+      const previous = merged[typedKey]
+      if (previous !== undefined && previous !== value) {
+        const previousOrigin = origins[typedKey]!
+        throw new Error(
+          [
+            `Conflicting Telegram credential values for ${key}.`,
+            `- ${sourceLabel(previousOrigin)}: ${redactedCredentialValue(
+              key,
+              previous,
+            )}`,
+            `- ${sourceLabel(candidate)}: ${redactedCredentialValue(
+              key,
+              value,
+            )}`,
+            "Run `tg-sai profile find` and choose one source with `--src <number>`.",
+          ].join("\n"),
+        )
+      }
+      merged[typedKey] = value
+      origins[typedKey] = candidate
+    }
+  }
+
+  return merged
+}
+
+function assertNoExplicitSourceConflicts(params: {
+  sourceValues: TelegramCredentialValues
+  higherPrecedenceValues: TelegramCredentialValues
+  sourceDescription: string
+}): void {
+  for (const [key, value] of Object.entries(params.sourceValues)) {
+    if (value === undefined || value === "") {
+      continue
+    }
+    const higherValue =
+      params.higherPrecedenceValues[key as keyof TelegramCredentialValues]
+    if (
+      higherValue !== undefined &&
+      higherValue !== "" &&
+      higherValue !== value
+    ) {
+      throw new Error(
+        [
+          `Conflicting Telegram credential values for ${key}.`,
+          `- ${params.sourceDescription}: ${redactedCredentialValue(
+            key,
+            value,
+          )}`,
+          `- CLI/env: ${redactedCredentialValue(key, higherValue)}`,
+          "Remove the conflicting flag/env var or choose a different `--src`.",
+        ].join("\n"),
+      )
+    }
+  }
+}
+
 function validateLoginOptions(options: ProfileAddOptions): void {
   if (options.qr && options.phone) {
     throw new Error("--qr and --phone are mutually exclusive")
   }
+  if ((options.login || options.qr || options.phone) && options.sessionString) {
+    throw new Error("Fresh login cannot be combined with --session-string")
+  }
+}
+
+/** A new login can reuse app credentials, never another account's session or 2FA. */
+function profileLoginValues(
+  values: TelegramCredentialValues | null,
+  options: ProfileAddOptions,
+): TelegramCredentialValues {
+  if (!(options.login || options.qr || options.phone)) return values ?? {}
+  const { TELEGRAM_SESSION_STRING: _session, TELEGRAM_PASSWORD: _password, ...app } = values ?? {}
+  return app
 }
 
 async function generateSessionString(params: {
@@ -965,49 +1087,139 @@ async function generateSessionString(params: {
   }
 }
 
-async function getCredentialValuesFromSourceOption(
+async function discoveredValuesForProfileAdd(
   options: ProfileAddOptions,
-): Promise<TelegramCredentialValues | null> {
-  if (!options.src) {
-    return null
-  }
-  const index = Number(options.src)
-  if (!Number.isInteger(index) || index < 1) {
-    throw new Error("--src must be a 1-based source number")
+): Promise<{
+  values: TelegramCredentialValues | null
+  sourceDescription: string | null
+  explicit: boolean
+}> {
+  if (options.src) {
+    const index = Number(options.src)
+    if (!Number.isInteger(index) || index < 1) {
+      throw new Error("--src must be a 1-based source number")
+    }
+
+    const report = await discoveryReport()
+    const candidate = report.candidates[index - 1]
+    if (!candidate) {
+      throw new Error(`Unknown discovery source: ${options.src}`)
+    }
+    return {
+      values: profileLoginValues(candidate.values, options),
+      sourceDescription: sourceLabel(candidate),
+      explicit: true,
+    }
   }
 
   const report = await discoveryReport()
-  const candidate = report.candidates[index - 1]
-  if (!candidate) {
-    throw new Error(`Unknown discovery source: ${options.src}`)
+  return {
+    values: mergeDiscoveredValues(report.candidates.map((candidate) => ({
+      ...candidate, values: profileLoginValues(candidate.values, options),
+    }))),
+    sourceDescription: null,
+    explicit: false,
+  }
+}
+
+async function promptForMissingProfileFields(
+  profileFields: ProfileCredentialFields,
+  options: ProfileAddOptions,
+): Promise<void> {
+  if (!options.interactive) {
+    return
+  }
+
+  const rl = createInterface({ input, output })
+  try {
+    if (!profileFields.apiId) {
+      const value = (await rl.question("Telegram API ID: ")).trim()
+      if (value) {
+        profileFields.apiId = Number(value)
+      }
+    }
+    if (!profileFields.apiHash) {
+      const value = (await rl.question("Telegram API hash: ")).trim()
+      if (value) {
+        profileFields.apiHash = value
+      }
+    }
+    if (
+      !profileFields.sessionString &&
+      !options.qr &&
+      !options.phone &&
+      !options.login
+    ) {
+      const value = (
+        await rl.question("Generate a Telegram session now? [Y=QR/n/phone]: ")
+      )
+        .trim()
+        .toLowerCase()
+      if (value === "phone" || value === "p") {
+        options.phone = true
+      } else if (value === "" || value === "y" || value === "yes") {
+        options.qr = true
+      }
+    }
+  } finally {
+    rl.close()
   }
-  return candidate.values
 }
 
 async function inputFromProfileAddOptions(
   options: ProfileAddOptions,
 ): Promise<ProfileAddInput> {
   validateLoginOptions(options)
-  const credentials = getCredentialsFromProfileAddOptions(options)
-  const sourceValues = credentials
-    ? null
-    : await getCredentialValuesFromSourceOption(options)
+  const saved = getProfile(await readConfig(), options.name)
+  const enrollsAccount = Boolean(
+    options.login || options.qr || options.phone || options.src || options.sessionString,
+  )
+  if (saved && !enrollsAccount) {
+    // Resolve the saved target before discovery. A password/app metadata edit
+    // must never authenticate another discovered account and overwrite this one.
+    if (
+      (options.userId !== undefined && Number(options.userId) !== saved.userId) ||
+      (options.handle !== undefined && options.handle !== saved.handle)
+    ) {
+      throw new Error("Changing a saved account identity requires an explicit fresh login or session import")
+    }
+    return {
+      name: saved.name,
+      apiId: options.apiId === undefined ? saved.apiId : Number(options.apiId),
+      apiHash: options.apiHash ?? saved.apiHash,
+      sessionString: saved.sessionString,
+      password: options.password ?? saved.password,
+      handle: saved.handle,
+      userId: saved.userId,
+      displayName: options.displayName ?? saved.displayName,
+    }
+  }
+  if (!saved && options.password !== undefined && !enrollsAccount) {
+    throw new Error(`Unknown configured profile: ${options.name ?? "active profile"}. Use tg-sai profile list and select it with --name; --src selects credential discovery sources.`)
+  }
   const optionValues = credentialValuesFromProfileAddOptions(options)
-  const profileFields = credentials
-    ? {
-        apiId: credentials.apiId,
-        apiHash: credentials.apiHash,
-        sessionString: credentials.sessionString,
-        password: optionValues.TELEGRAM_PASSWORD ?? "",
-      }
-    : profileFieldsFromCredentialValues(
-        mergeCredentialValues(sourceValues, optionValues),
-      )
+  const envValues = profileLoginValues(credentialValuesFromEnv(), options)
+  const discovery = await discoveredValuesForProfileAdd(options)
+  const higherPrecedenceValues = mergeCredentialValues(envValues, optionValues)
+  if (discovery.explicit && discovery.values && discovery.sourceDescription) {
+    assertNoExplicitSourceConflicts({
+      sourceValues: discovery.values,
+      higherPrecedenceValues,
+      sourceDescription: discovery.sourceDescription,
+    })
+  }
+  const profileFields = profileFieldsFromCredentialValues(
+    mergeCredentialValues(discovery.values, envValues, optionValues),
+  )
+  await promptForMissingProfileFields(profileFields, options)
 
-  if (options.login && !profileFields.sessionString) {
+  if (
+    (options.login || options.qr || options.phone) &&
+    !profileFields.sessionString
+  ) {
     if (!profileFields.apiId || !profileFields.apiHash) {
       throw new Error(
-        "--login requires apiId and apiHash from flags, --src, env, or .env discovery",
+        "Session generation requires apiId and apiHash from flags, env, or discovery",
       )
     }
     profileFields.sessionString = await generateSessionString({
@@ -1072,33 +1284,117 @@ async function inputFromProfileAddOptions(
 
 async function runProfileList(): Promise<void> {
   const config = await readConfig()
-  const profiles = Object.values(config.profiles)
-  if (profiles.length === 0) {
+  if (config.profiles.length === 0) {
     console.log("No profiles configured.")
     return
   }
-  for (const profile of profiles) {
-    const active = config.activeProfile === profile.name ? "*" : " "
+  for (const [index, profile] of config.profiles.entries()) {
+    const active = index === 0 ? "*" : " "
     console.log(
-      `${active} ${profile.name}\t${profile.handle ?? ""}\t${profile.userId}\t${profile.displayName}`,
+      `${active} ${index}\t${profileLabel(profile, index)}\t${profile.userId}\t${profile.displayName}`,
     )
   }
 }
 
-async function runProfileShow(name: string): Promise<void> {
+async function runProfileShow(selector = "0"): Promise<void> {
   const config = await readConfig()
-  const profile = getProfile(config, name)
+  const profile = getProfile(config, selector)
   if (!profile) {
-    throw new Error(`Unknown profile: ${name}`)
+    throw new Error(`Unknown profile: ${selector}`)
   }
   console.log(JSON.stringify(redactedProfile(profile), null, 2))
 }
 
+async function printConfiguredProfiles(): Promise<void> {
+  console.log("\nConfigured local profiles (* marks the active/default profile):")
+  await runProfileList()
+}
+
+async function printProfileAddHelp(command: Command): Promise<void> {
+  command.outputHelp()
+  console.log(
+    "\nNo profile is saved and no Telegram login starts without explicit options.",
+  )
+  console.log(
+    "Use a new --name to add a separate account. Without --name, explicit options update the active profile.",
+  )
+  console.log("\nFresh QR login for a separate custody account:")
+  console.log(
+    "  tg-sai profile add --name sai-custody --login --qr --interactive",
+  )
+  console.log(
+    "Scan while signed into the intended Telegram account, then inspect it with:",
+  )
+  console.log("  tg-sai profile show sai-custody")
+  await printConfiguredProfiles()
+  console.log("\nInspect an existing profile with tg-sai profile show <selector>.")
+  console.log("Update a saved password with --name <saved-name-or-handle-or-index> --password '<password>'.")
+  console.log("--src selects a numbered credential source from profile find, not a saved profile index.")
+}
+
+async function printProfileRemoveHelp(command: Command): Promise<void> {
+  command.outputHelp()
+  console.log(
+    "\nRemoves a saved local profile, not the Telegram account or its chat memberships.",
+  )
+  console.log("Removing a profile does not revoke its Telegram sessions.")
+  console.log("No profile is removed without an explicit selector.")
+  const config = await readConfig()
+  if (config.profiles.length === 0) {
+    console.log("\nNo saved profiles are available to remove.")
+    console.log(
+      "Add an account with: tg-sai profile add --login --qr --interactive",
+    )
+    return
+  }
+
+  console.log("\nRunnable examples for saved profiles:")
+  let examples = 0
+  for (const [index, saved] of config.profiles.entries()) {
+    // Handles and names can overlap. Emit only selectors that resolve to this row.
+    const selector = [
+      saved.handle,
+      saved.name,
+      saved.userId?.toString(),
+      String(index),
+    ].find(
+      (candidate) =>
+        candidate != null && findProfileIndex(config, candidate) === index,
+    )
+    if (selector == null) continue
+    const argument = /^[A-Za-z0-9_@./:-]+$/.test(selector)
+      ? selector
+      : `'${selector.replaceAll("'", "'\\''")}'`
+    const label = JSON.stringify(profileLabel(saved, index))
+    console.log(
+      `  tg-sai profile remove -- ${argument}  # ${label}${index === 0 ? " [active]" : ""}`,
+    )
+    examples++
+  }
+  if (examples < config.profiles.length) {
+    console.log(
+      "Some profiles have ambiguous selectors; inspect tg-sai profile list before removing them.",
+    )
+  }
+  console.log(
+    "\nExamples use the current profile configuration. Run tg-sai profile list to inspect it.",
+  )
+}
+
 async function runProfileAdd(options: ProfileAddOptions): Promise<void> {
+  const previous = getProfile(await readConfig(), options.name)
   const input = await inputFromProfileAddOptions(options)
+  if (previous?.userId != null && input.userId !== previous.userId) {
+    throw new Error("Login or import does not match the saved account. Use a new --name for another account, or explicitly remove the old profile before replacing it.")
+  }
+  if (previous) input.name = previous.name
   const config = await addProfile(input)
-  const active = config.activeProfile === input.name ? "active" : "saved"
-  console.log(`profile_${active}: ${input.name}`)
+  const profile = getProfile(config, input.name)
+  const index = profile ? config.profiles.indexOf(profile) : 0
+  const savedProfile = profile ?? config.profiles[0]!
+  const active = index === 0 ? "default" : "saved"
+  console.log(`profile_${active}: ${profileLabel(savedProfile, index)}`)
+  console.log(`profile_index: ${index}`)
   console.log(`user_id: ${input.userId}`)
   console.log(`handle: ${input.handle ?? ""}`)
   console.log(`telegram_password: ${input.password ? "stored" : "missing"}`)
@@ -1134,7 +1430,23 @@ function printDiscoveryReport(report: DiscoveryReport): void {
     )
   }
   console.log("next:")
-  console.log("  tg-sai profile add --name <name> --src <number>")
+  try {
+    const values = mergeDiscoveredValues(report.candidates)
+    if (Object.keys(values).length === 0) {
+      console.log("  tg-sai profile add")
+      return
+    }
+    console.log("  tg-sai profile add")
+    if (!values.TELEGRAM_SESSION_STRING) {
+      console.log("  tg-sai profile add --qr")
+      console.log("  tg-sai profile add --phone")
+    }
+  } catch (error) {
+    console.log(
+      `  conflict: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    console.log("  tg-sai profile add --src <number>")
+  }
 }
 
 export function createProgram(): Command {
@@ -1150,22 +1462,13 @@ export function createProgram(): Command {
     program.help({ error: false })
   })
 
-  program
-    .command("health")
-    .description("Read-only preflight for the local tg-sai setup")
-    .action(async () => {
-      await runHealth()
-    })
+  addRuntimeHealthCommands(program, runHealth)
 
   program
     .command("audit")
     .description("Read-only audit for one chat and target user")
     .option("--profile <name>", "Profile name to use for Telegram credentials")
-    .requiredOption(
-      "--chat <id>",
-      "Telegram chat ID or username",
-      parsePeer,
-    )
+    .requiredOption("--chat <id>", "Telegram chat ID or username", parsePeer)
     .option(
       "--target-user <id>",
       "Target user ID or username",
@@ -1188,11 +1491,7 @@ Examples:
     .command("add-bot")
     .description("Add SaiTeam_bot and promote it to admin when possible")
     .option("--profile <name>", "Profile name to use for Telegram credentials")
-    .requiredOption(
-      "--chat <id>",
-      "Telegram chat ID or username",
-      parsePeer,
-    )
+    .requiredOption("--chat <id>", "Telegram chat ID or username", parsePeer)
     .option(
       "--target-user <id>",
       "Bot user ID used for membership audit",
@@ -1214,11 +1513,7 @@ Examples:
     .command("add-owner")
     .description("Add a target user as owner if possible, otherwise admin")
     .option("--profile <name>", "Profile name to use for Telegram credentials")
-    .requiredOption(
-      "--chat <id>",
-      "Telegram chat ID or username",
-      parsePeer,
-    )
+    .requiredOption("--chat <id>", "Telegram chat ID or username", parsePeer)
     .requiredOption(
       "--target-user <peer>",
       "Target user ID or username",
@@ -1265,6 +1560,11 @@ Examples:
       "--no-transfer-owner",
       "Skip ownership transfer even when TELEGRAM_PASSWORD is available",
     )
+    .option(
+      "--target-user <peer>",
+      "Owner target user ID or username; default is the Sai custody account",
+      parsePeer,
+    )
     .action(async (options: SaiBootstrapOptions) => {
       await runSaiBootstrap(options)
     })
@@ -1272,6 +1572,10 @@ Examples:
   const profile = program
     .command("profile")
     .description("Manage local Telegram session profiles")
+    .action(async () => {
+      profile.outputHelp()
+      await printConfiguredProfiles()
+    })
 
   profile
     .command("find")
@@ -1287,10 +1591,13 @@ Examples:
       await runProfileList()
     })
 
-  profile
+  const addProfileCommand = profile
     .command("add")
     .description("Add or update a Telegram session profile")
-    .requiredOption("--name <name>", "Profile name")
+    .option(
+      "--name <name>",
+      "Local profile name; use a distinct name for another account",
+    )
     .option("--api-id <id>", "Telegram API ID")
     .option("--api-hash <hash>", "Telegram API hash")
     .option("--session-string <value>", "Telegram session string")
@@ -1298,43 +1605,78 @@ Examples:
       "--password <value>",
       "Telegram 2FA password for ownership transfer",
     )
-    .option("--src <number>", "Use a numbered source from profile find")
-    .option("--login", "Generate a session string when missing")
-    .option("--qr", "Use QR login with --login")
-    .option("--phone", "Use phone login with --login")
+    .option("--src <number>", "Import a numbered credential source from profile find, not a saved profile")
+    .option(
+      "--login",
+      "Start a fresh account login, ignoring discovered sessions (defaults to QR)",
+    )
+    .option("--qr", "Generate a session string with QR login")
+    .option("--phone", "Generate a session string with phone login")
+    .option("-i, --interactive", "Prompt for missing profile values")
     .option("--handle <handle>", "Resolved Telegram handle")
     .option("--user-id <id>", "Resolved Telegram user ID")
     .option("--display-name <name>", "Resolved Telegram display name")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  tg-sai profile add --name sai-custody --login --qr --interactive
+  tg-sai profile add --name another-account --phone --interactive
+  tg-sai profile add --name another-account --src 1
+  tg-sai profile add --name existing-profile --password '<password>'
+
+If apiId/apiHash are missing, create a Telegram API app at:
+  https://my.telegram.org/apps
+`,
+    )
     .action(async (options: ProfileAddOptions) => {
+      if (Object.keys(options).length === 0) {
+        await printProfileAddHelp(addProfileCommand)
+        return
+      }
       await runProfileAdd(options)
     })
 
   profile
     .command("show")
     .description("Show one configured profile")
-    .argument("<name>", "Profile name")
-    .action(async (name: string) => {
-      await runProfileShow(name)
+    .argument(
+      "[selector]",
+      "Profile index, handle, user ID, or legacy name",
+      "0",
+    )
+    .action(async (selector: string) => {
+      await runProfileShow(selector)
     })
 
   profile
     .command("use")
     .description("Set the active profile")
-    .argument("<name>", "Profile name")
-    .action(async (name: string) => {
-      await setActiveProfile(name)
-      console.log(`active_profile: ${name}`)
+    .argument("<selector>", "Profile index, handle, user ID, or legacy name")
+    .action(async (selector: string) => {
+      const config = await setActiveProfile(selector)
+      const active = config.profiles[0]!
+      console.log(`active_profile: ${profileLabel(active, 0)}`)
     })
 
-  profile
+  const removeProfileCommand = profile
     .command("remove")
     .description("Remove one configured profile")
-    .argument("<name>", "Profile name")
-    .action(async (name: string) => {
-      await removeProfile(name)
-      console.log(`removed_profile: ${name}`)
+    .argument(
+      "[selector]",
+      "Profile index, handle, user ID, or legacy name; omit for examples",
+    )
+    .action(async (selector: string | undefined) => {
+      if (selector === undefined) {
+        await printProfileRemoveHelp(removeProfileCommand)
+        return
+      }
+      await removeProfile(selector)
+      console.log(`removed_profile: ${selector}`)
     })
 
+  addProvisionCommands(program)
+  addCustodyWorkerCommands(program)
   return program
 }