@toloka-platform/sdk 0.1.0-preview.3

package/src/cli/program.ts

@@ -0,0 +1,851 @@
+import { Command, CommanderError, InvalidArgumentError } from "commander";
+import { assert } from "es-toolkit";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { createClient } from "../client";
+import type { PotatoClient } from "../client";
+import { PotatoApiError } from "../errors";
+import { readTolokaState } from "../state";
+import type { TolokaState } from "../state";
+import { authStatus, login, logout } from "./auth";
+import type { AuthPrompt } from "./auth";
+import { commandNameFromArgv, createCliAnalytics } from "./analytics";
+import type { CliAnalytics, CliAnalyticsCommandOutcome } from "./analytics";
+import { PRODUCTION_BASE_URL, resolveTolokaConfig } from "./config";
+import type { TolokaEnvironment } from "./config";
+import {
+  findCommandCredentials,
+  readStoredCredentials,
+  requireStoredCredentials,
+} from "./credentials";
+import type { StoredCredentials } from "./credentials";
+import {
+  generateDatasetFieldDeclarations,
+  listProjectDatasets,
+  loadDataset,
+  setProjectSecret,
+  uploadDataset,
+} from "./data";
+import { initProject, readAgentSkillStalenessWarning } from "./init";
+import {
+  applyProject,
+  importProject,
+  planProject,
+  projectStatus,
+  validateProject,
+} from "./project";
+import {
+  MISSING_PROJECT_ID_MESSAGE,
+  addProject,
+  createProject,
+  currentProject,
+  listRemoteProjects,
+  removeProject,
+  resolveProjectContext,
+  switchProject,
+} from "./project-context";
+import { estimatePipelineCost } from "./cost";
+import {
+  cancelPipelineRun,
+  listLivePipelines,
+  listPipelineRuns,
+  pickPipeline,
+  pipelineRunResults,
+  pipelineRunStatus,
+  startPipelineRun,
+} from "./runs";
+
+import type { RunOutcome } from "./runs";
+import { findSourceRoot } from "./source";
+
+export type CliIo = {
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  readonly readStdin: () => Promise<string>;
+  readonly prompt?: AuthPrompt;
+  readonly select?: (choices: readonly { name: string; value: string }[]) => Promise<string>;
+};
+
+export type ProgramContext = {
+  readonly environment: TolokaEnvironment;
+  readonly io: CliIo;
+  readonly injectedClient?: PotatoClient;
+  readonly analytics?: CliAnalytics;
+};
+
+type GlobalOptions = {
+  readonly sourceRoot?: string;
+  readonly apiKey?: string;
+  readonly baseUrl?: string;
+  readonly projectId?: string;
+};
+
+const CREDENTIAL_PRECEDENCE = [
+  "Credentials resolve in this order, highest first:",
+  "  1. --api-key / --base-url",
+  "  2. POTATO_API_KEY / POTATO_BASE_URL",
+  "  3. the file written by toloka login",
+  `The platform defaults to ${PRODUCTION_BASE_URL}.`,
+].join("\n");
+
+const positiveInteger = (raw: string): number => {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0)
+    throw new InvalidArgumentError("Expected a positive integer.");
+  return value;
+};
+
+const exitCodeForOutcome = (outcome: RunOutcome): number => {
+  if (outcome === "failed") return 1;
+  if (outcome === "timedOut") return 2;
+  return 0;
+};
+
+type Resolved = {
+  readonly sourceRoot: string;
+  readonly client: PotatoClient;
+  readonly state: TolokaState | undefined;
+  readonly stored: StoredCredentials | undefined;
+  readonly projectId?: string;
+};
+
+const resolveSourceRoot = async (globals: GlobalOptions, io: CliIo): Promise<string> => {
+  if (globals.sourceRoot !== undefined) return resolve(globals.sourceRoot);
+
+  const workingDirectory = process.cwd();
+  const discovered = await findSourceRoot(workingDirectory);
+  if (discovered === undefined || discovered === workingDirectory) return workingDirectory;
+
+  io.stderr(`Using project root ${discovered} (found from ${workingDirectory}).`);
+  return discovered;
+};
+
+const resolveInitRoot = (globals: GlobalOptions): string =>
+  globals.sourceRoot === undefined ? process.cwd() : resolve(globals.sourceRoot);
+
+const readCommandCredentials = async (globals: GlobalOptions, context: ProgramContext) => {
+  const { found, warning } = await findCommandCredentials(
+    context.environment,
+    globals.apiKey ?? context.environment.POTATO_API_KEY,
+  );
+  if (warning !== undefined) context.io.stderr(warning);
+  return found?.credentials;
+};
+
+const identifyClientUser = async (client: PotatoClient, analytics: CliAnalytics | undefined) => {
+  if (analytics?.shouldIdentify !== true) return;
+  try {
+    analytics.identifyCurrentUser(await client.me());
+  } catch {}
+};
+
+const resolveContext = async (
+  globals: GlobalOptions,
+  context: ProgramContext,
+): Promise<Resolved> => {
+  const sourceRoot = await resolveSourceRoot(globals, context.io);
+  const state = await readTolokaState(sourceRoot);
+  const stored = await readCommandCredentials(globals, context);
+  const config = resolveTolokaConfig(globals, state, context.environment, stored);
+  const client =
+    context.injectedClient ?? createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+  await identifyClientUser(client, context.analytics);
+
+  return {
+    sourceRoot,
+    client,
+    state,
+    stored,
+    ...(config.projectId === undefined ? {} : { projectId: config.projectId }),
+  };
+};
+
+const resolveSelectedProject = (
+  globals: GlobalOptions,
+  context: ProgramContext,
+  stored: StoredCredentials | undefined,
+  state: TolokaState | undefined,
+) =>
+  resolveProjectContext({
+    flags: globals,
+    environment: context.environment,
+    stored,
+    ...(state === undefined ? {} : { state }),
+  });
+
+export type CreatedProgram = {
+  readonly program: Command;
+  readonly exitCode: { value: number };
+};
+
+export function createProgram(context: ProgramContext): CreatedProgram {
+  const program = new Command("toloka");
+  const exitCode = { value: 0 };
+  let warnedAboutStaleSkills = false;
+
+  program
+    .description(
+      "Preview. Build and operate Toloka pipeline projects from TypeScript source. The public API may change.",
+    )
+    .option(
+      "--source-root <directory>",
+      "project root; discovered from the working directory when omitted",
+    )
+    .option("--api-key <key>", "API key for this command only")
+    .option("--base-url <url>", "platform base URL for this command only")
+    .option("--project-id <id>", "target project; overrides toloka.json")
+    .addHelpText("after", `\n${CREDENTIAL_PRECEDENCE}`)
+    .configureOutput({
+      writeOut: (text) => context.io.stdout(text.replace(/\n$/u, "")),
+      writeErr: (text) => context.io.stderr(text.replace(/\n$/u, "")),
+    })
+    .exitOverride();
+
+  const globals = (): GlobalOptions => program.opts<GlobalOptions>();
+
+  program.hook("postAction", async (thisCommand) => {
+    if (warnedAboutStaleSkills) return;
+    const commandNames = [];
+    for (let current: Command | null = thisCommand; current !== null; current = current.parent) {
+      commandNames.push(current.name());
+    }
+    if (commandNames.includes("init") || commandNames.includes("help")) return;
+    const sourceRoot = await resolveSourceRoot(globals(), context.io);
+    const warning = await readAgentSkillStalenessWarning(sourceRoot).catch(() => undefined);
+    if (warning === undefined) return;
+    warnedAboutStaleSkills = true;
+    context.io.stderr(warning);
+  });
+
+  program
+    .command("login")
+    .description("store an API key for this machine after verifying it")
+    .action(async () => {
+      const result = await login({
+        ...(globals().apiKey === undefined ? {} : { apiKey: globals().apiKey }),
+        ...(globals().baseUrl === undefined ? {} : { baseUrl: globals().baseUrl }),
+        ...(context.io.prompt === undefined ? {} : { prompt: context.io.prompt }),
+        write: context.io.stdout,
+        environment: context.environment,
+      });
+      context.io.stdout(result.output);
+      try {
+        const stored = await readStoredCredentials(context.environment);
+        if (stored === undefined) return;
+        const client = context.injectedClient ?? createClient(stored);
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+
+  program
+    .command("logout")
+    .description("remove stored credentials from this machine")
+    .action(async () => {
+      const result = await logout(context.environment);
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("auth-status")
+    .alias("whoami")
+    .description("show which platform and key the CLI would use")
+    .option("--show-token", "print the API key instead of masking it", false)
+    .action(async (options: { showToken: boolean }) => {
+      const flags = globals();
+      const credentialLookup = await findCommandCredentials(
+        context.environment,
+        flags.apiKey ?? context.environment.POTATO_API_KEY,
+      );
+      const stored = credentialLookup.found?.credentials;
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      const state = await readTolokaState(sourceRoot);
+      const project = resolveSelectedProject(flags, context, stored, state);
+      const injectedClient = context.injectedClient;
+
+      const result = await authStatus({
+        environment: context.environment,
+        showToken: options.showToken,
+        credentialLookup,
+        ...(flags.apiKey === undefined ? {} : { flagApiKey: flags.apiKey }),
+        ...(flags.baseUrl === undefined ? {} : { flagBaseUrl: flags.baseUrl }),
+        ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        ...(project === undefined ? {} : { project }),
+      });
+
+      context.io.stdout(result.output);
+      if (!result.authenticated) {
+        exitCode.value = 1;
+        return;
+      }
+      try {
+        const config = resolveTolokaConfig(flags, state, context.environment, stored);
+        const client =
+          context.injectedClient ??
+          createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+        await identifyClientUser(client, context.analytics);
+      } catch {}
+    });
+
+  const project = program
+    .command("project")
+    .description("select and manage the current platform project");
+  project
+    .command("list")
+    .description("list remote projects this key can see")
+    .action(async () => {
+      const flags = globals();
+      const { client, stored, state } = await resolveContext(flags, context);
+      const selected = resolveSelectedProject(flags, context, stored, state);
+      await listRemoteProjects({
+        client,
+        io: context.io,
+        ...(selected === undefined ? {} : { context: selected }),
+      });
+    });
+  project
+    .command("add")
+    .argument("[alias]", "local name for this project")
+    .argument("[projectId]", "platform project id")
+    .description("register a live project and select it")
+    .action(async (alias?: string, projectId?: string) => {
+      const flags = globals();
+      const found = await requireStoredCredentials(context.environment);
+      const client = context.injectedClient ?? createClient(found.credentials);
+      await addProject({
+        environment: context.environment,
+        flags,
+        client,
+        io: context.io,
+        afterPreflight: async () => identifyClientUser(client, context.analytics),
+        ...(alias === undefined ? {} : { alias }),
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+    });
+
+  project
+    .command("switch")
+    .argument("<alias>", "local project alias")
+    .description("select a registered project")
+    .action(async (alias: string) => {
+      await switchProject({
+        environment: context.environment,
+        flags: globals(),
+        alias,
+        io: context.io,
+      });
+    });
+  project
+    .command("current")
+    .description("show the project this command would use")
+    .action(async () => {
+      const flags = globals();
+      const stored = await readCommandCredentials(flags, context);
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      const state = await readTolokaState(sourceRoot);
+      const result = currentProject({
+        flags,
+        environment: context.environment,
+        stored,
+        ...(state === undefined ? {} : { state }),
+        io: context.io,
+      });
+      if (result.project === undefined) exitCode.value = 1;
+    });
+
+  project
+    .command("remove")
+    .argument("<alias>", "local project alias")
+    .description("forget a local project alias")
+    .action(async (alias: string) => {
+      await removeProject({
+        environment: context.environment,
+        flags: globals(),
+        alias,
+        io: context.io,
+      });
+    });
+  project
+    .command("create")
+    .argument("[alias]", "local name for the new project")
+    .option("--name <name>", "platform project name")
+    .option("--team-id <id>", "team that owns the project")
+    .description("create a live project and select it")
+    .action(async (alias: string | undefined, options: { name?: string; teamId?: string }) => {
+      const flags = globals();
+      const found = await requireStoredCredentials(context.environment);
+      const client = context.injectedClient ?? createClient(found.credentials);
+      const sourceRoot = await resolveSourceRoot(flags, context.io);
+      await createProject({
+        environment: context.environment,
+        flags,
+        client,
+        io: context.io,
+        sourceRoot,
+        afterPreflight: async () => identifyClientUser(client, context.analytics),
+        ...(alias === undefined ? {} : { alias }),
+        ...(options.name === undefined ? {} : { name: options.name }),
+        ...(options.teamId === undefined ? {} : { teamId: options.teamId }),
+      });
+    });
+
+  program
+    .command("init")
+    .description("initialize this project directory and install agent skills")
+    .action(async () => {
+      const flags = globals();
+      const sourceRoot = resolveInitRoot(flags);
+      const stored = await readCommandCredentials(flags, context);
+      const state = await readTolokaState(sourceRoot);
+      const selected = resolveSelectedProject(flags, context, stored, state);
+      const result = await initProject(
+        sourceRoot,
+        selected === undefined ? {} : { projectId: selected.id },
+      );
+      context.io.stdout(result.output);
+      if (result.warning !== undefined) context.io.stderr(result.warning);
+    });
+
+  program
+    .command("import")
+    .argument(
+      "[projectId]",
+      "existing project to write into source; defaults to the selected project",
+    )
+    .option("-f, --force", "replace an existing pipelines/ directory", false)
+    .description("generate TypeScript source from a live project")
+    .action(async (projectId?: string, options?: { force?: boolean }) => {
+      const {
+        sourceRoot,
+        client,
+        projectId: selectedProjectId,
+      } = await resolveContext(globals(), context);
+      const id = projectId ?? selectedProjectId;
+      assert(id, MISSING_PROJECT_ID_MESSAGE);
+      const result = await importProject(client, {
+        sourceRoot,
+        projectId: id,
+        ...(options?.force === true ? { force: true } : {}),
+      });
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("plan")
+    .description("show what apply would change")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await planProject(client, {
+        sourceRoot,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+
+  program
+    .command("validate")
+    .description("run platform spec validation and report matching checks")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await validateProject(client, {
+        sourceRoot,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+      if (!result.valid) exitCode.value = 1;
+    });
+
+  program
+    .command("apply")
+    .description("make the platform match source")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await applyProject(client, {
+        sourceRoot,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+
+  const secret = program.command("secret").description("manage project secrets");
+  secret
+    .command("set")
+    .argument("<name>", "secret name referenced by a code node")
+    .option(
+      "--from-env <variable>",
+      "read the value from this environment variable instead of stdin",
+    )
+    .description("set a secret value without writing it to disk")
+    .action(async (name: string, options: { fromEnv?: string }) => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+
+      const value =
+        options.fromEnv === undefined
+          ? (await context.io.readStdin()).replace(/\r?\n$/u, "")
+          : context.environment[options.fromEnv];
+      assert(
+        value !== undefined,
+        `Missing secret value. Set ${options.fromEnv ?? "the named environment variable"} or pipe it to stdin.`,
+      );
+
+      try {
+        const result = await setProjectSecret(client, { projectId, name, value });
+        context.io.stdout(result.output);
+      } catch {
+        context.io.stderr(`Failed to set secret ${name}.`);
+        exitCode.value = 1;
+      }
+    });
+
+  const dataset = program
+    .command("dataset")
+    .description("inspect and move dataset catalog and rows");
+  dataset
+    .command("list")
+    .description("list live datasets in the selected project")
+    .action(async () => {
+      const { client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await listProjectDatasets(client, { projectId });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("fields")
+    .argument("<name>", "dataset name or id")
+    .description("print field declarations inferred from uploaded rows")
+    .action(async (name: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await generateDatasetFieldDeclarations(client, {
+        sourceRoot,
+        datasetName: name,
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("load")
+    .argument("<name>", "dataset name or id")
+    .requiredOption("--out <file>", "JSONL file to write")
+    .option("--limit <n>", "how many rows to keep after download", positiveInteger)
+    .option("--timeout <ms>", "how long to wait for the export", positiveInteger)
+    .description("download live dataset rows into a JSONL file")
+    .action(async (name: string, options: { out: string; limit?: number; timeout?: number }) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await loadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        outPath: resolve(options.out),
+        ...(projectId === undefined ? {} : { projectId }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+      });
+      context.io.stdout(result.output);
+    });
+  dataset
+    .command("upload")
+    .argument("<name>", "dataset name or id")
+    .argument("<file>", "JSONL file, one JSON object per line")
+    .description("append rows to a dataset")
+    .action(async (name: string, file: string) => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      const result = await uploadDataset(client, {
+        sourceRoot,
+        datasetName: name,
+        filePath: resolve(file),
+        ...(projectId === undefined ? {} : { projectId }),
+      });
+      context.io.stdout(result.output);
+      if (result.warning !== undefined) context.io.stderr(result.warning);
+    });
+
+  const pipelineNameHelp =
+    "pipeline name or id; required unless a TTY picker can choose among several";
+  const pipeline = program
+    .command("pipeline")
+    .description("operate on a live pipeline in the selected project");
+  pipeline
+    .command("list")
+    .description("list live pipelines in the selected project")
+    .action(async () => {
+      const { client, projectId, state } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await listLivePipelines({ client, projectId, state });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("run")
+    .argument("[name]", pipelineNameHelp)
+    .option("--wait", "wait for the run to reach a terminal state", false)
+    .option("--timeout <ms>", "how long to wait", positiveInteger)
+    .description("start a run on a deployed pipeline")
+    .action(async (name: string | undefined, options: { wait: boolean; timeout?: number }) => {
+      const { client, state, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await startPipelineRun(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        wait: options.wait,
+        ...(options.timeout === undefined ? {} : { timeoutMs: options.timeout }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+  pipeline
+    .command("status")
+    .argument("[name]", pipelineNameHelp)
+    .description("report the latest run's state and item counts")
+    .action(async (name: string | undefined) => {
+      const { client, state, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await pipelineRunStatus(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+  pipeline
+    .command("runs")
+    .argument("[name]", pipelineNameHelp)
+    .option("--limit <n>", "how many runs to list", positiveInteger)
+    .description("list recent runs")
+    .action(async (name: string | undefined, options: { limit?: number }) => {
+      const { client, state, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await listPipelineRuns(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("cost")
+    .argument("[name]", pipelineNameHelp)
+    .option("--item-limit <n>", "cap how many items to price", positiveInteger)
+    .description("forecast what a run of this pipeline would bill")
+    .action(async (name: string | undefined, options: { itemLimit?: number }) => {
+      const { client, state, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await estimatePipelineCost(client, {
+        projectId,
+        state,
+        ...(name === undefined ? {} : { pipeline: name }),
+        ...(options.itemLimit === undefined ? {} : { itemLimit: options.itemLimit }),
+        ...(context.io.select === undefined ? {} : { select: context.io.select }),
+      });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("cancel")
+    .argument("<runId>", "run to cancel")
+    .description("request cancellation of a run")
+    .action(async (runId: string) => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await cancelPipelineRun(client, { runId });
+      context.io.stdout(result.output);
+    });
+  pipeline
+    .command("results")
+    .argument("<runId>", "run to read")
+    .option("--limit <n>", "how many items to scan", positiveInteger)
+    .option("--failed", "only report failed items", false)
+    .description("report a run's items")
+    .action(async (runId: string, options: { limit?: number; failed: boolean }) => {
+      const { client } = await resolveContext(globals(), context);
+      const result = await pipelineRunResults(client, {
+        runId,
+        failedOnly: options.failed,
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+      });
+      context.io.stdout(result.output);
+      exitCode.value = exitCodeForOutcome(result.outcome);
+    });
+
+  program
+    .command("status")
+    .description("report project health: live counts and pending source changes")
+    .action(async () => {
+      const { sourceRoot, client, projectId } = await resolveContext(globals(), context);
+      assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+      const result = await projectStatus(client, { sourceRoot, projectId });
+      context.io.stdout(result.output);
+    });
+
+  return { program, exitCode };
+}
+
+const readStandardInput = async (): Promise<string> => {
+  process.stdin.setEncoding("utf8");
+  const chunks: string[] = [];
+  for await (const chunk of process.stdin) chunks.push(String(chunk));
+  return chunks.join("");
+};
+
+const readMaskedLine = async (question: string): Promise<string> => {
+  process.stdout.write(question);
+  const wasRaw = process.stdin.isRaw;
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+
+  const { promise, resolve, reject } = Promise.withResolvers<string>();
+  let value = "";
+
+  const restore = () => {
+    process.stdin.off("data", onData);
+    process.stdin.off("end", onEnd);
+    process.stdin.off("error", onError);
+    process.stdin.setRawMode(wasRaw);
+    process.stdin.pause();
+  };
+
+  const finish = () => {
+    restore();
+    process.stdout.write("\n");
+  };
+
+  const onEnd = () => {
+    finish();
+    reject(new Error("Standard input closed before an API key was entered."));
+  };
+
+  const onError = (error: Error) => {
+    finish();
+    reject(error);
+  };
+
+  const onData = (chunk: string) => {
+    for (const character of chunk) {
+      if (character === "\r" || character === "\n") {
+        finish();
+        resolve(value);
+        return;
+      }
+      if (character === "\u0003" || character === "\u0004") {
+        finish();
+        reject(
+          new Error(
+            character === "\u0003"
+              ? "Canceled."
+              : "Standard input closed before an API key was entered.",
+          ),
+        );
+        return;
+      }
+      if (character === "\u007f" || character === "\b") {
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          process.stdout.write("\b \b");
+        }
+        continue;
+      }
+      value += character;
+      process.stdout.write("*");
+    }
+  };
+
+  process.stdin.on("data", onData);
+  process.stdin.once("end", onEnd);
+  process.stdin.once("error", onError);
+
+  try {
+    return await promise;
+  } finally {
+    restore();
+  }
+};
+
+const promptFromTerminal: AuthPrompt = async (question, options = {}) => {
+  if (options.mask === true) return readMaskedLine(question);
+
+  const input = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  try {
+    return await input.question(question);
+  } finally {
+    input.close();
+  }
+};
+
+export const terminalIo = (): CliIo => ({
+  stdout: (text) => console.log(text),
+  stderr: (text) => console.error(text),
+  readStdin: readStandardInput,
+  ...(process.stdin.isTTY ? { prompt: promptFromTerminal, select: pickPipeline } : {}),
+});
+
+type CommandResult = {
+  readonly code: number;
+  readonly outcome: CliAnalyticsCommandOutcome;
+  readonly error?: unknown;
+};
+const formatCliError = (error: unknown): string => {
+  if (error instanceof PotatoApiError) {
+    const details =
+      typeof error.body === "string"
+        ? error.body
+        : error.body === undefined
+          ? undefined
+          : JSON.stringify(error.body);
+    return details === undefined || details.length === 0
+      ? error.message
+      : `${error.message}\n${details}`;
+  }
+  return error instanceof Error ? error.message : String(error);
+};
+
+const runProgram = async (
+  program: Command,
+  exitCode: { value: number },
+  argv: readonly string[],
+  io: CliIo,
+): Promise<CommandResult> => {
+  try {
+    await program.parseAsync([...argv], { from: "user" });
+    const code = exitCode.value;
+    return { code, outcome: code === 0 ? "succeeded" : "failed" };
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      const code = error.exitCode === 0 ? 0 : 1;
+      return { code, outcome: code === 0 ? "succeeded" : "usage_error", error };
+    }
+    io.stderr(formatCliError(error));
+    return { code: 1, outcome: "failed", error };
+  }
+};
+
+export async function runTolokaCli(
+  argv: readonly string[],
+  environment: TolokaEnvironment = process.env,
+  io: CliIo = terminalIo(),
+  injectedClient?: PotatoClient,
+  analytics: CliAnalytics = createCliAnalytics({ environment }),
+): Promise<number> {
+  const { program, exitCode } = createProgram({
+    environment,
+    io,
+    analytics,
+    ...(injectedClient === undefined ? {} : { injectedClient }),
+  });
+
+  const startedAt = Date.now();
+  const result = await runProgram(program, exitCode, argv, io);
+  try {
+    analytics.captureCommand({
+      command: commandNameFromArgv(argv),
+      durationMs: Date.now() - startedAt,
+      exitCode: result.code,
+      outcome: result.outcome,
+      ...(result.error === undefined ? {} : { error: result.error }),
+    });
+    await analytics.shutdown();
+  } catch {}
+
+  return result.code;
+}