@tryarcanist/cli 0.1.318 → 0.1.320

package/README.md

@@ -13,7 +13,7 @@ Requires Node.js 22 or newer.
 ## Quick start
 
 ```bash
-arcanist auth login                 # paste a token from Settings > CLI
+arcanist auth login                 # approve login in your browser
 arcanist sessions list --json
 ```
 
@@ -25,14 +25,14 @@ arcanist sessions events "$SESSION_ID" --follow --json
 
 ## Authentication
 
-Generate a CLI token in the Arcanist UI at **Settings > CLI**, then:
+Start browser authorization from the CLI:
 
 ```bash
 arcanist auth login
-# paste your arc_... token when prompted; input is masked
+# approve the request in the browser
 ```
 
-Token config is stored at `~/.arcanist/config.json`. Multiple active tokens per user are supported; revoke tokens independently when a device or workflow no longer needs access.
+Token config is stored at `~/.arcanist/config.json`. Existing automation can still provide a token through `ARCANIST_TOKEN` or `--token-stdin`. Multiple active tokens per user are supported; revoke tokens independently when a device or workflow no longer needs access.
 
 Use a read-scoped token for inspection and debugging; use a write-scoped token only to create sessions, send prompts, or stop runs.
 
@@ -132,6 +132,18 @@ arcanist environments retry owner/repo --wait --json
 
 Agents should follow `repository.nextAction` and request a Zeus review only when it is `review`. The command waits through internal handoffs until setup is ready or there is a real action for the user or Arcanist.
 
+### `arcanist setup`
+
+Connect Arcanist and prepare one or more repository environments. The command starts browser authentication when needed, lists only repositories where GitHub reports write access, and queues at most 20 builds.
+
+```bash
+arcanist setup
+arcanist setup acme/web
+arcanist setup acme/web acme/api --json
+```
+
+With no repository arguments, the command returns the eligible repositories and `selection_required`. Rerun with the repositories to prepare. Builds continue after the command exits. The command prints an `arcanist environments status owner/repo --wait` command for each build so agents can track progress or leave it running.
+
 ### `arcanist auth login`
 
 ```bash
@@ -140,6 +152,8 @@ printf "arc_..." | arcanist auth login --token-stdin
 arcanist auth login --api-url https://api.tryarcanist.com
 ```
 
+The default flow prints a browser authorization URL and waits for approval. `--json` writes the action immediately as JSONL on stderr and writes one final result to stdout. `--token-stdin` and `ARCANIST_TOKEN` remain available for automation that already has a token.
+
 ### `arcanist auth whoami`
 
 ```bash

package/dist/index.js

@@ -7370,7 +7370,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@tryarcanist/cli",
-  version: "0.1.318",
+  version: "0.1.320",
   description: "CLI for Arcanist - create and manage coding agent sessions",
   type: "module",
   bin: {
@@ -7620,7 +7620,7 @@ function timeoutError(timeoutMs) {
     hint: `Increase ${HTTP_TIMEOUT_ENV} for slow links, or check the API connection.`
   });
 }
-async function apiRequest(config2, path, init, read) {
+async function apiRequest(connection, path, init, read) {
   const timeoutMs = parseHttpTimeoutMs();
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -7628,8 +7628,8 @@ async function apiRequest(config2, path, init, read) {
     const headers = new Headers(init?.headers);
     headers.set("Content-Type", "application/json");
     headers.set("User-Agent", CLI_USER_AGENT);
-    headers.set("Authorization", `Bearer ${config2.token}`);
-    const res = await fetch(`${normalizeBaseUrl(config2.apiUrl)}${path}`, {
+    if (connection.token) headers.set("Authorization", `Bearer ${connection.token}`);
+    const res = await fetch(`${normalizeBaseUrl(connection.apiUrl)}${path}`, {
       ...init,
       headers,
       signal: controller.signal
@@ -7659,6 +7659,9 @@ function resourceNounForPath(path) {
 async function apiFetch(config2, path, init) {
   return apiRequest(config2, path, init, (res) => res.json());
 }
+async function publicApiFetch(apiUrl, path, init) {
+  return apiRequest({ apiUrl }, path, init, (res) => res.json());
+}
 async function apiFetchText(config2, path, init) {
   return apiRequest(config2, path, init, (res) => res.text());
 }
@@ -7865,9 +7868,6 @@ function isLoopbackHost(parsed) {
 // src/runtime.ts
 import { randomUUID } from "crypto";
 import { createInterface } from "readline/promises";
-var ASCII_FIRST_PRINTABLE = 32;
-var ASCII_DELETE = 127;
-var ANSI_CONTROL_SEQUENCE = /\u001b\[[0-9:;<=>?]*[ -/]*[@-~]/g;
 function getRuntimeOptions(command, options = {}) {
   const globals = command?.optsWithGlobals?.();
   const merged = { ...globals, ...options };
@@ -7915,70 +7915,6 @@ async function confirmOrThrow(message) {
     rl.close();
   }
 }
-async function readHiddenPrompt(prompt) {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new CliError("user", "No interactive terminal available. Re-run with --token-stdin or set ARCANIST_TOKEN.");
-  }
-  return new Promise((resolve3, reject) => {
-    const stdin = process.stdin;
-    const inputChars = [];
-    let ansiCarry = "";
-    let settled = false;
-    const cleanup = () => {
-      stdin.removeListener("data", onData);
-      stdin.removeListener("error", onError);
-      if (stdin.isTTY) stdin.setRawMode(false);
-      stdin.pause();
-    };
-    const finish = () => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      process.stdout.write("\n");
-      resolve3(inputChars.join(""));
-    };
-    const fail = (error51) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      process.stdout.write("\n");
-      reject(error51);
-    };
-    const onData = (chunk) => {
-      const normalized = normalizePromptChunk(chunk, ansiCarry);
-      ansiCarry = normalized.carry;
-      const text = normalized.text;
-      for (const char of text) {
-        if (char === "\n" || char === "\r") {
-          finish();
-          return;
-        }
-        if (char === "") {
-          fail(new CliError("user", "Interrupted.", { exitCode: EXIT_CODE_INTERRUPTED }));
-          return;
-        }
-        if (char === "\x7F" || char === "\b") {
-          if (inputChars.length > 0) {
-            inputChars.pop();
-            process.stdout.write("\b \b");
-          }
-          continue;
-        }
-        if (isControlCharacter(char)) continue;
-        inputChars.push(char);
-        process.stdout.write("*");
-      }
-    };
-    const onError = (error51) => {
-      fail(new CliError("user", `Failed to read input: ${error51.message}`));
-    };
-    process.stdout.write(prompt);
-    stdin.resume();
-    if (stdin.isTTY) stdin.setRawMode(true);
-    stdin.on("data", onData);
-    stdin.on("error", onError);
-  });
-}
 function applyColorEnvironment(options) {
   if (options.noColor === true || !process.stdout.isTTY) {
     process.env.NO_COLOR = "1";
@@ -7998,47 +7934,6 @@ function assertArcanistSessionMutationAllowed(subcommand) {
     }
   );
 }
-function normalizePromptChunk(chunk, carry) {
-  const raw = carry + (Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk);
-  let text = "";
-  let index = 0;
-  while (index < raw.length) {
-    const char = raw[index];
-    if (char !== "\x1B") {
-      text += char;
-      index += 1;
-      continue;
-    }
-    const sequence = matchAnsiControlSequence(raw, index);
-    if (sequence.kind === "incomplete") {
-      return { text, carry: raw.slice(index) };
-    }
-    if (sequence.kind === "complete") {
-      index = sequence.nextIndex;
-      continue;
-    }
-    index += 1;
-  }
-  return { text, carry: "" };
-}
-function matchAnsiControlSequence(text, startIndex) {
-  if (startIndex + 1 >= text.length) {
-    return { kind: "incomplete", nextIndex: startIndex };
-  }
-  if (text[startIndex + 1] !== "[") {
-    return { kind: "none", nextIndex: startIndex + 1 };
-  }
-  ANSI_CONTROL_SEQUENCE.lastIndex = startIndex;
-  const match = ANSI_CONTROL_SEQUENCE.exec(text);
-  if (match && match.index === startIndex) {
-    return { kind: "complete", nextIndex: startIndex + match[0].length };
-  }
-  return { kind: "incomplete", nextIndex: startIndex };
-}
-function isControlCharacter(char) {
-  const code = char.charCodeAt(0);
-  return code < ASCII_FIRST_PRINTABLE || code === ASCII_DELETE;
-}
 
 // src/utils/terminal-text.ts
 function sanitizeTerminalText(value) {
@@ -22729,6 +22624,7 @@ var INTEGRATION_REGISTRY = {
 };
 
 // ../../shared/constants/onboarding.ts
+var MAX_ENVIRONMENT_SETUP_REPOSITORIES = 20;
 var CREDENTIAL_VALIDATION_STATUS = {
   VALIDATED: "validated",
   SAVED_UNVERIFIED: "saved_unverified",
@@ -23293,6 +23189,16 @@ async function waitForSetup(config2, fullName, pollIntervalMs) {
     }
   });
 }
+async function prepareEnvironments(config2, options) {
+  const response = await apiFetch(config2, "/api/settings/repositories/onboarding", {
+    method: "POST",
+    body: JSON.stringify({
+      repositories: options.repositories.map(({ owner, repo }) => ({ owner, name: repo })),
+      ...options.workspace ? { workspace: true } : {}
+    })
+  });
+  return response.repositories;
+}
 async function environmentStatusCommand(repoArg, options = {}, command) {
   const pollIntervalMs = options.wait ? parsePollInterval(options.pollInterval, { defaultMs: SETUP_POLL_INTERVAL_MS, maxMs: null }) : null;
   const repo = requestedRepo(repoArg);
@@ -23305,11 +23211,7 @@ async function environmentPrepareCommand(repoArg, options = {}, command) {
   const pollIntervalMs = options.wait ? parsePollInterval(options.pollInterval, { defaultMs: SETUP_POLL_INTERVAL_MS, maxMs: null }) : null;
   const repo = requestedRepo(repoArg);
   const { config: config2 } = resolveBusinessContext(command, options);
-  const response = await apiFetch(config2, "/api/settings/repositories/onboarding", {
-    method: "POST",
-    body: JSON.stringify({ repositories: [{ owner: repo.owner, name: repo.repo }] })
-  });
-  const result = response.repositories[0];
+  const [result] = await prepareEnvironments(config2, { repositories: [repo] });
   if (!result) throw new CliError("server", "Environment setup returned no repository result.");
   if (result.status === "forbidden") {
     throw new CliError("auth", `You must have write access to ${repo.fullName} to prepare its environment.`);
@@ -23357,15 +23259,18 @@ async function hadesCommand(repo, options = {}, command) {
 }
 
 // src/commands/login.ts
+var DEVICE_AUTH_START_PATH = "/api/auth/cli/device";
+var DEVICE_AUTH_TOKEN_PATH = "/api/auth/cli/device/token";
 async function loginCommand(options, command) {
   const runtime = getRuntimeOptions(command, options);
-  let token;
+  const apiUrl = resolveLoginApiUrl(runtime.apiUrl);
+  let token = null;
   if (options.tokenStdin) {
     token = await readStdinTrimmed();
   } else if (runtime.token) {
     token = runtime.token;
   } else {
-    token = await readHiddenPrompt("Enter your CLI token: ");
+    token = await loginWithDeviceAuthorization(apiUrl, runtime);
   }
   if (!token) {
     throw new CliError("user", "No token provided.");
@@ -23373,25 +23278,55 @@ async function loginCommand(options, command) {
   if (!token.startsWith("arc_")) {
     throw new CliError("user", "Invalid token format. Token must start with 'arc_'.");
   }
-  const apiUrl = resolveLoginApiUrl(runtime.apiUrl);
-  saveConfig({ apiUrl, token });
-  if (runtime.json) {
-    writeJson({ ok: true, apiUrl });
-  } else if (!runtime.quiet) {
-    console.log(`Logged in. API: ${apiUrl}`);
-  }
   try {
-    await apiFetch({ apiUrl, token }, "/api/cli-tokens");
-    if (!runtime.json && !runtime.quiet) console.log("Token verified.");
+    await apiFetch({ apiUrl, token }, "/api/auth/whoami");
+    const config2 = { apiUrl, token };
+    saveConfig(config2);
+    if (options.emitResult === false) return config2;
+    if (runtime.json) writeJson({ ok: true, apiUrl });
+    else if (!runtime.quiet) {
+      console.log(`Logged in. API: ${apiUrl}`);
+      console.log("Token verified.");
+    }
+    return config2;
   } catch (err) {
-    if (!runtime.json && !runtime.quiet) {
-      if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
-        console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
-      } else {
-        console.warn("Warning: Could not reach API to verify token.");
-      }
+    if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
+      throw new CliError("auth", "Token could not be verified. It may be invalid or expired.");
     }
+    throw err;
+  }
+}
+async function loginWithDeviceAuthorization(apiUrl, runtime) {
+  const authorization = await publicApiFetch(apiUrl, DEVICE_AUTH_START_PATH, {
+    method: "POST",
+    body: "{}"
+  });
+  emitAction(runtime, { url: authorization.verificationUrl, userCode: authorization.userCode });
+  if (!runtime.json && !runtime.quiet) console.error("Waiting for approval...");
+  const deadline = Date.now() + authorization.expiresIn * 1e3;
+  const pollIntervalMs = Math.max(1, authorization.pollInterval) * 1e3;
+  while (Date.now() < deadline) {
+    const response = await publicApiFetch(apiUrl, DEVICE_AUTH_TOKEN_PATH, {
+      method: "POST",
+      body: JSON.stringify({ deviceCode: authorization.deviceCode })
+    });
+    if ("accessToken" in response) return response.accessToken;
+    await sleep(pollIntervalMs);
+  }
+  throw new CliError("auth", "CLI authorization expired.", { hint: "Run `arcanist auth login` again." });
+}
+function emitAction(runtime, action) {
+  if (runtime.json) {
+    process.stderr.write(
+      `${JSON.stringify({ type: "action_required", action: { kind: "authorize_cli", ...action } })}
+`
+    );
+    return;
   }
+  process.stderr.write(`Authorize Arcanist in your browser:
+${action.url}
+Code: ${action.userCode}
+`);
 }
 
 // ../../shared/agent/agent-runtime-backend.ts
@@ -26994,6 +26929,296 @@ async function usageCommand(sessionId, options, command) {
   if (usage.totalCostUsd !== void 0) console.log(`Cost: ${String(usage.totalCostUsd)}`);
 }
 
+// ../../shared/utils/shell.ts
+var SHELL_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// ../../shared/types/sandbox.ts
+var APP_RUNTIME_ENTRY_TYPE = {
+  Compose: "compose",
+  Dockerfile: "dockerfile",
+  Command: "command"
+};
+
+// ../../shared/types/repo-runtime.ts
+var ENVIRONMENT_REPOS_MAX = 8;
+var SANDBOX_PATH_PATTERN = /^\/workspace\/(?!\.+$)(?!.*\.\.)[A-Za-z0-9._-]+$/;
+var EnvironmentRepoSchema = external_exports.object({
+  repoOwner: external_exports.string().trim().min(1, "repoOwner is required"),
+  repoName: external_exports.string().trim().min(1, "repoName is required"),
+  sandboxPath: external_exports.string().regex(SANDBOX_PATH_PATTERN, "sandboxPath must be a single path segment under /workspace").optional()
+}).strict();
+function environmentRepoSandboxPath(repo) {
+  return repo.sandboxPath ?? `/workspace/${repo.repoName}`;
+}
+var EnvironmentReposSchema = external_exports.array(EnvironmentRepoSchema).min(1, "at least one repo is required").max(ENVIRONMENT_REPOS_MAX, `at most ${ENVIRONMENT_REPOS_MAX} repos are allowed`).superRefine((repos2, ctx) => {
+  if (repos2.length === 0) return;
+  const primaryOwner = repos2[0].repoOwner.toLowerCase();
+  if (repos2[0].sandboxPath !== void 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: [0, "sandboxPath"],
+      message: `the primary repo is always cloned to /workspace/${repos2[0].repoName}`
+    });
+  }
+  const seenRepos = /* @__PURE__ */ new Set();
+  const seenPaths = /* @__PURE__ */ new Set();
+  repos2.forEach((repo, index) => {
+    if (repo.repoOwner.toLowerCase() !== primaryOwner) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "repoOwner"],
+        message: "all repos must share the primary repo's owner"
+      });
+    }
+    const repoKey = `${repo.repoOwner}/${repo.repoName}`.toLowerCase();
+    if (seenRepos.has(repoKey)) {
+      ctx.addIssue({ code: "custom", path: [index], message: `duplicate repo ${repo.repoOwner}/${repo.repoName}` });
+    }
+    seenRepos.add(repoKey);
+    const path = environmentRepoSandboxPath(repo);
+    if (!SANDBOX_PATH_PATTERN.test(path)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index],
+        message: `repo name ${repo.repoName} needs an explicit sandboxPath`
+      });
+      return;
+    }
+    if (seenPaths.has(path)) {
+      ctx.addIssue({ code: "custom", path: [index], message: `sandbox path ${path} is already taken` });
+    }
+    seenPaths.add(path);
+  });
+});
+var CredentialDeclarationSchema = external_exports.object({
+  name: external_exports.string(),
+  envVar: external_exports.string(),
+  source: external_exports.enum(["business_openai_key", "business_anthropic_key"]).optional()
+});
+var StringRecordSchema = external_exports.record(
+  external_exports.string().regex(SHELL_ENV_KEY_PATTERN, "must be a POSIX-style environment variable name"),
+  external_exports.string()
+);
+var AppRuntimeProfileConfigSchema = external_exports.object({
+  cwd: external_exports.string().optional(),
+  kind: external_exports.string().optional(),
+  runner: external_exports.string().optional(),
+  entry: external_exports.object({
+    type: external_exports.enum([
+      APP_RUNTIME_ENTRY_TYPE.Compose,
+      APP_RUNTIME_ENTRY_TYPE.Dockerfile,
+      APP_RUNTIME_ENTRY_TYPE.Command
+    ]),
+    files: external_exports.array(external_exports.string()).optional(),
+    service: external_exports.string().optional(),
+    profiles: external_exports.array(external_exports.string()).optional(),
+    context: external_exports.string().optional(),
+    dockerfile: external_exports.string().optional(),
+    command: external_exports.string().optional()
+  }).strict().optional(),
+  url: external_exports.object({ hostPort: external_exports.number().int().optional(), path: external_exports.string().optional() }).strict().optional(),
+  portMapping: external_exports.object({ containerPort: external_exports.number().int().optional() }).strict().optional(),
+  additionalPorts: external_exports.array(
+    external_exports.object({
+      service: external_exports.string().optional(),
+      hostPort: external_exports.number().int().optional(),
+      containerPort: external_exports.number().int().optional()
+    }).strict()
+  ).optional(),
+  runtimeVariables: StringRecordSchema.optional(),
+  composeEnv: StringRecordSchema.optional(),
+  generatedComposeEnv: external_exports.record(
+    external_exports.string(),
+    external_exports.union([
+      external_exports.object({ type: external_exports.literal("alphanumeric"), length: external_exports.number().int() }).strict(),
+      external_exports.object({ type: external_exports.literal("hex"), bytes: external_exports.number().int() }).strict()
+    ])
+  ).optional(),
+  env: StringRecordSchema.optional(),
+  ready: external_exports.object({
+    path: external_exports.string().optional(),
+    nonEmptyPath: external_exports.string().optional(),
+    timeoutSeconds: external_exports.number().int().optional()
+  }).strict().optional(),
+  open: external_exports.object({ path: external_exports.string().optional() }).strict().optional(),
+  auth: external_exports.object({
+    command: external_exports.string().optional(),
+    validatePath: external_exports.string().optional(),
+    browserStateEnvVar: external_exports.string().optional(),
+    credentials: external_exports.array(CredentialDeclarationSchema).optional()
+  }).strict().optional(),
+  e2e: external_exports.object({
+    testCommand: external_exports.string(),
+    seedCommand: external_exports.string().optional(),
+    resetCommand: external_exports.string().optional(),
+    credentials: external_exports.array(CredentialDeclarationSchema).optional()
+  }).strict().optional()
+}).strict();
+var EnvironmentProvisioningConfigSchema = external_exports.object({
+  sandbox: external_exports.object({ appRuntime: AppRuntimeProfileConfigSchema.optional() }).strict().optional()
+}).strict();
+
+// src/commands/setup.ts
+var INSTALL_POLL_INTERVAL_MS = 5e3;
+var INSTALL_WAIT_TIMEOUT_MS = 20 * 60 * 1e3;
+var ONBOARDING_REPOS_PATH = "/api/onboarding/repos";
+async function setupCommand(repoArgs = [], options = {}, command) {
+  if (repoArgs.length > MAX_ENVIRONMENT_SETUP_REPOSITORIES) {
+    throw new CliError("user", `At most ${MAX_ENVIRONMENT_SETUP_REPOSITORIES} repositories can be prepared at once.`);
+  }
+  if (options.workspace && repoArgs.length === 1) {
+    throw new CliError("user", "A multi-repository workspace requires at least two repositories.");
+  }
+  if (options.workspace && repoArgs.length > ENVIRONMENT_REPOS_MAX) {
+    throw new CliError("user", `A workspace supports at most ${ENVIRONMENT_REPOS_MAX} repositories.`);
+  }
+  const runtime = getRuntimeOptions(command, options);
+  let config2 = loadConfig(runtime);
+  if (!config2) config2 = await loginCommand({ ...runtime, emitResult: false }, command);
+  const requested = repoArgs.map((value) => {
+    const repo = parseRepoArg(value);
+    return `${repo.owner}/${repo.repo}`;
+  });
+  const inventory = await ensureGitHubRepositories({ config: config2, requested, runtime });
+  if (!inventory) return;
+  const eligible = eligibleRepositoryNames(inventory.repos);
+  const selected = selectRepositories({ eligible, requested, runtime });
+  if (!selected) return;
+  const repositories = await prepareEnvironments(config2, {
+    repositories: selected.map((value) => parseRepoArg(value)),
+    workspace: options.workspace
+  });
+  const rejected = repositories.filter((result) => result.status === "forbidden" || result.status === "failed");
+  const accepted = repositories.filter((result) => result.status !== "forbidden" && result.status !== "failed");
+  if (accepted.length === 0) {
+    throw new CliError(
+      rejected.some((result) => result.status === "forbidden") ? "auth" : "server",
+      `Environment setup was rejected for: ${rejected.map((result) => result.fullName).join(", ")}.`
+    );
+  }
+  const queued = accepted.filter((result) => result.status !== "already_ready");
+  const tracking = trackingCommands(queued.map((result) => result.fullName));
+  const payload = {
+    status: rejected.length > 0 ? "partial" : queued.length > 0 ? "queued" : "ready",
+    repositories,
+    workspace: options.workspace === true,
+    tracking
+  };
+  emit(void 0, runtime, payload, () => {
+    console.log(
+      queued.length > 0 ? `Environment preparation started for ${queued.length} ${queued.length === 1 ? "repository" : "repositories"}.` : "The selected environments are ready."
+    );
+    if (rejected.length > 0) {
+      console.log(`Could not start: ${rejected.map((result) => sanitizeTerminalText(result.fullName)).join(", ")}.`);
+    }
+    for (const line of tracking) console.log(line);
+  });
+}
+function eligibleRepositoryNames(repos2) {
+  return repos2.filter((repo) => {
+    return typeof repo.fullName === "string" && repo.canReview === true;
+  }).map((repo) => repo.fullName).sort((a, b) => a.localeCompare(b));
+}
+function selectRepositories(options) {
+  const { eligible, requested, runtime } = options;
+  if (requested.length === 0) {
+    emit(
+      void 0,
+      runtime,
+      {
+        status: "selection_required",
+        repositories: eligible,
+        next: "Rerun with one or more owner/repo arguments."
+      },
+      () => {
+        console.log("Repositories available to prepare:");
+        for (const repository of eligible) console.log(`  ${sanitizeTerminalText(repository)}`);
+        console.log("Rerun with one or more owner/repo arguments.");
+      }
+    );
+    return null;
+  }
+  const eligibleNames = new Map(eligible.map((repository) => [repository.toLowerCase(), repository]));
+  const selected = [
+    ...new Map(
+      requested.map((repository) => [
+        repository.toLowerCase(),
+        eligibleNames.get(repository.toLowerCase()) ?? repository
+      ])
+    ).values()
+  ];
+  const unavailable = selected.filter((repository) => !eligibleNames.has(repository.toLowerCase()));
+  if (unavailable.length > 0) {
+    throw new CliError("auth", `Repositories are unavailable or lack write access: ${unavailable.join(", ")}.`);
+  }
+  return selected;
+}
+async function ensureGitHubRepositories(options) {
+  const { config: config2, requested, runtime } = options;
+  let inventory = await apiFetch(config2, `${ONBOARDING_REPOS_PATH}?refresh=1`);
+  const readOnly = new Set(
+    inventory.repos.filter((repo) => repo.canReview !== true && typeof repo.fullName === "string").map((repo) => String(repo.fullName).toLowerCase())
+  );
+  const inaccessible = requested.filter((repository) => readOnly.has(repository.toLowerCase()));
+  if (inaccessible.length > 0) {
+    throw new CliError("auth", `Repositories lack write access: ${inaccessible.join(", ")}.`);
+  }
+  if (inventorySatisfiesRequest(inventory, requested)) return inventory;
+  if (inventory.ssoOrgs.length > 0) return emitSsoRequirement({ apiUrl: config2.apiUrl, inventory, runtime });
+  const install = await apiFetch(config2, "/api/github/install-url");
+  emitSetupAction(runtime, { kind: "install_github", url: install.url });
+  if (!runtime.json && !runtime.quiet) console.error("Waiting for GitHub repository access...");
+  const deadline = Date.now() + INSTALL_WAIT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(INSTALL_POLL_INTERVAL_MS);
+    inventory = await apiFetch(config2, ONBOARDING_REPOS_PATH);
+    if (inventorySatisfiesRequest(inventory, requested)) return inventory;
+    if (inventory.ssoOrgs.length > 0) return emitSsoRequirement({ apiUrl: config2.apiUrl, inventory, runtime });
+  }
+  throw new CliError("server", "Timed out waiting for GitHub repository access.", {
+    hint: `Finish repository selection at ${install.url}, then rerun \`arcanist setup\`.`
+  });
+}
+function inventorySatisfiesRequest(inventory, requested) {
+  const eligible = new Set(eligibleRepositoryNames(inventory.repos).map((repository) => repository.toLowerCase()));
+  if (requested.length > 0) return requested.every((repository) => eligible.has(repository.toLowerCase()));
+  return inventory.complete === true && eligible.size > 0;
+}
+function emitSsoRequirement(options) {
+  const { apiUrl, inventory, runtime } = options;
+  for (const org of inventory.ssoOrgs) {
+    if (typeof org.authorizeUrl !== "string") continue;
+    const url2 = org.authorizeUrl.startsWith("/") ? `${apiUrl}${org.authorizeUrl}` : org.authorizeUrl;
+    emitSetupAction(runtime, {
+      kind: "authorize_github_sso",
+      url: url2,
+      organization: org.login ?? org.orgId
+    });
+  }
+  emit(
+    void 0,
+    runtime,
+    {
+      status: "action_required",
+      action: "authorize_github_sso",
+      repositories: eligibleRepositoryNames(inventory.repos),
+      ssoOrgs: inventory.ssoOrgs,
+      next: "Authorize GitHub SSO, then rerun arcanist setup."
+    },
+    () => console.log("Authorize GitHub SSO, then rerun arcanist setup.")
+  );
+  return null;
+}
+function emitSetupAction(runtime, action) {
+  if (runtime.json) process.stderr.write(`${JSON.stringify({ type: "action_required", action })}
+`);
+  else process.stderr.write(`Action required: ${action.url}
+`);
+}
+function trackingCommands(repositories) {
+  return repositories.map((repository) => `Track later: arcanist environments status ${repository} --wait`);
+}
+
 // src/commands/stop.ts
 async function stopCommand(sessionId, options = {}, command) {
   const { config: config2 } = resolveBusinessContext(command, options);
@@ -27238,7 +27463,7 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
   applyColorEnvironment(getRuntimeOptions(actionCommand));
 });
 var auth = program.command("auth").description("Authentication commands");
-auth.command("login").description("Authenticate with a personal access token").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText(
+auth.command("login").description("Authenticate through your browser").option("--token-stdin", "Read token from stdin instead of interactive prompt").option("--api-url <url>", "Set custom API URL").addHelpText(
   "after",
   `
 Examples:
@@ -27246,7 +27471,9 @@ Examples:
   printf "arc_..." | arcanist auth login --token-stdin
   ARCANIST_TOKEN=arc_... arcanist auth whoami --json
 `
-).action((options, command) => loginCommand(options, command));
+).action(async (options, command) => {
+  await loginCommand(options, command);
+});
 auth.command("whoami").description("Print the authenticated user and token scope").addHelpText(
   "after",
   `
@@ -27255,6 +27482,21 @@ Examples:
   ARCANIST_TOKEN=arc_... arcanist auth whoami --json
 `
 ).action((options, command) => whoamiCommand(options, command));
+program.command("setup").description("Connect GitHub repositories and prepare their Zeus environments").argument("[repos...]", "Repositories in owner/name form").option("--workspace", "Prepare the repositories as one multi-repository workspace").addHelpText(
+  "after",
+  `
+Examples:
+  arcanist setup
+  arcanist setup acme/web
+  arcanist setup acme/web acme/api --json
+  arcanist setup acme/web acme/api --workspace
+
+With no repositories, the command returns the eligible repositories. Rerun with the
+repositories to prepare. By default each repository gets its own environment; use
+--workspace to prepare them together. Builds continue after the command exits; use
+the emitted environment status commands to track them.
+`
+).action((repos2, options, command) => setupCommand(repos2, options, command));
 var codex = program.command("codex").description("Codex subscription (bring-your-own-subscription) commands");
 codex.command("login").description("Authenticate a Codex/ChatGPT subscription and store it for your Codex sessions").option("--codex-path <path>", "Path to the codex executable (default: codex on PATH, or ARCANIST_CODEX_BIN)").addHelpText(
   "after",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.318",
+  "version": "0.1.320",
   "description": "CLI for Arcanist - create and manage coding agent sessions",
   "type": "module",
   "bin": {