@getmagical/cli 0.1.5 → 0.1.6

package/dist/index.js

@@ -1276,7 +1276,7 @@ mutation UpdateAutomationById($id: ID!, $input: UpdateAutomationInput!) {
 ];
 
 // src/program.ts
-import { Command, InvalidArgumentError, Option } from "commander";
+import { Command as Command2, InvalidArgumentError as InvalidArgumentError2, Option as Option2 } from "commander";
 
 // src/api.ts
 import { z as z2 } from "zod";
@@ -1323,15 +1323,20 @@ function getApiErrorDetail(responseBody) {
   }
   return parsedResponse.data.errors.map((error) => error.message).join("\n");
 }
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/u, "");
+}
 function createMagicalApiClient({
   apiBaseUrl,
   fetchFn = fetch
 }) {
+  const resolveApiBaseUrl = typeof apiBaseUrl === "string" ? () => apiBaseUrl : apiBaseUrl;
   async function fetchJson({
     accessToken,
-    url,
+    path: path5,
     init
   }) {
+    const url = `${trimTrailingSlash(await resolveApiBaseUrl())}${path5}`;
     const headers = new Headers(init?.headers);
     headers.set("authorization", `Bearer ${accessToken}`);
     const response = await fetchFn(url, {
@@ -1339,7 +1344,7 @@ function createMagicalApiClient({
       headers
     }).catch((error) => {
       throw new CliError(
-        `Failed to reach Magical API at ${url}. Check MAGICAL_API_URL and make sure service-main is running.`,
+        `Failed to reach Magical API at ${url}. Check your configured base URL and make sure service-main is running.`,
         { cause: error }
       );
     });
@@ -1379,7 +1384,7 @@ function createMagicalApiClient({
       const parsedResponse = graphQlResponseSchema.safeParse(
         await fetchJson({
           accessToken,
-          url: `${apiBaseUrl}/graphql`,
+          path: "/graphql",
           init: {
             method: "POST",
             headers,
@@ -1404,7 +1409,7 @@ function createMagicalApiClient({
       const parsedResponse = workosOrganizationsResponseSchema.safeParse(
         await fetchJson({
           accessToken,
-          url: `${apiBaseUrl}/workos/organizations`
+          path: "/workos/organizations"
         })
       );
       if (!parsedResponse.success) {
@@ -1423,7 +1428,7 @@ function createMagicalApiClient({
       const parsedResponse = workosUserSchema.safeParse(
         await fetchJson({
           accessToken,
-          url: `${apiBaseUrl}/workos/user/${userId}`
+          path: `/workos/user/${userId}`
         })
       );
       if (!parsedResponse.success) {
@@ -1434,57 +1439,19 @@ function createMagicalApiClient({
   };
 }
 
-// src/command-presentation.ts
-var rootOperationalGroupDescriptions = /* @__PURE__ */ new Map([
-  ["agents", "Query agents."],
-  ["agent-runs", "Query agent runs."],
-  ["automations", "Manage automations."],
-  ["automation-runs", "Inspect and control automation runs."],
-  ["catalog", "Inspect available commands, models, and tools."],
-  ["graphql", "Inspect GraphQL metadata."]
-]);
-function configureCommandPresentation(command) {
-  const originalCreateCommand = command.createCommand.bind(command);
-  command.createCommand = (name) => configureCommandPresentation(originalCreateCommand(name));
-  command.createHelp = () => new MagicalHelp();
-  return command;
-}
-function createOperationHelpExamples(operationSpec) {
-  const baseCommand = `mgcl ${operationSpec.cli.path.join(" ")}`;
-  const requiredOptions = operationSpec.cli.options.filter((optionSpec) => optionSpec.required).map((optionSpec) => {
-    if (optionSpec.valueType === "boolean") {
-      return `--${optionSpec.flagName}`;
-    }
-    if (optionSpec.valueType === "number") {
-      return `--${optionSpec.flagName} 10`;
-    }
-    if (optionSpec.valueType === "json") {
-      return `--${optionSpec.flagName} '{...}'`;
-    }
-    if (optionSpec.valueType === "string-array") {
-      return `--${optionSpec.flagName} value-a,value-b`;
-    }
-    return `--${optionSpec.flagName} <${optionSpec.flagName}>`;
-  });
-  const baseInvocation = [baseCommand, ...requiredOptions].join(" ");
-  return [
-    baseInvocation,
-    `${baseInvocation} --org <org>`,
-    `${baseInvocation} --json`
-  ];
-}
-
 // src/config.ts
 import os from "os";
 import path from "path";
 var DEFAULT_MAGICAL_API_URL = "https://api-agt.getmagical.io";
 var DEFAULT_WORKOS_API_URL = "https://api.workos.com";
 var DEFAULT_WORKOS_CLIENT_ID = "client_01JJZ6XJ1RF248P20WF63M4VAM";
+var DEFAULT_STAGING_WORKOS_CLIENT_ID = "client_01JJZ6X26BGFBT8AC303XPQ9EQ";
 var DEFAULT_KEYCHAIN_SERVICE_NAME = "@getmagical/mcp-cli";
 var DEFAULT_CLI_DIST_TAG = "latest";
 var DEFAULT_CLI_NPM_REGISTRY_URL = "https://registry.npmjs.org/";
 var CLI_CONFIG_DIRECTORY_NAME = "magical-mcp-cli";
 var CLI_STATE_FILE_NAME = "state.json";
+var CLI_SETTINGS_FILE_NAME = "settings.json";
 function resolvePlatformConfigDirectory() {
   const customConfigDirectory = process.env["MAGICAL_CLI_CONFIG_DIR"];
   if (customConfigDirectory) {
@@ -1506,19 +1473,202 @@ function getRuntimeConfig() {
   );
   return {
     cliDistTag: process.env["MAGICAL_CLI_DIST_TAG"] ?? DEFAULT_CLI_DIST_TAG,
-    magicalApiUrl: process.env["MAGICAL_API_URL"] ?? DEFAULT_MAGICAL_API_URL,
+    magicalApiUrl: DEFAULT_MAGICAL_API_URL,
     npmRegistryUrl: process.env["MAGICAL_CLI_NPM_REGISTRY_URL"] ?? DEFAULT_CLI_NPM_REGISTRY_URL,
     stateFilePath: path.join(configDirectory, CLI_STATE_FILE_NAME),
     workosApiUrl: DEFAULT_WORKOS_API_URL,
-    workosClientId: process.env["WORKOS_CLIENT_ID"] ?? DEFAULT_WORKOS_CLIENT_ID,
-    keychainServiceName: DEFAULT_KEYCHAIN_SERVICE_NAME,
-    ...process.env["WORKOS_AUTHKIT_DOMAIN"] ? { workosAuthkitDomain: process.env["WORKOS_AUTHKIT_DOMAIN"] } : {}
+    workosClientId: DEFAULT_WORKOS_CLIENT_ID,
+    keychainServiceName: DEFAULT_KEYCHAIN_SERVICE_NAME
   };
 }
 function requireWorkosClientId(config) {
   return config.workosClientId;
 }
 
+// src/settings.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import path2 from "path";
+import { safeJsonParse } from "@magical/common/stdlib/json.util";
+import { isErr } from "@magical/common/stdlib/result.util";
+import { z as z3 } from "zod";
+var cliSettingsSchema = z3.object({
+  env: z3.object({
+    baseUrl: z3.url().optional()
+  }).default({})
+});
+function createEmptyCliSettings() {
+  return {
+    env: {}
+  };
+}
+function hasCliSettingsOverrides(settings) {
+  return settings.env.baseUrl !== void 0;
+}
+function resolveSettingsFilePath(stateFilePath) {
+  return path2.join(path2.dirname(stateFilePath), CLI_SETTINGS_FILE_NAME);
+}
+function resolveConfiguredApiBaseUrl({
+  defaultApiBaseUrl,
+  settings
+}) {
+  return settings.env.baseUrl ?? defaultApiBaseUrl;
+}
+function shouldUseStagingWorkosClientId(settings) {
+  return settings.env.baseUrl !== void 0;
+}
+function createFileSettingsStore(stateFilePath) {
+  const settingsFilePath = resolveSettingsFilePath(stateFilePath);
+  return {
+    async load() {
+      const fileContents = await readFile(settingsFilePath, "utf8").catch(
+        (error) => {
+          if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+          }
+          throw new CliError("Failed to load CLI settings.", { cause: error });
+        }
+      );
+      if (fileContents === null) {
+        return createEmptyCliSettings();
+      }
+      const parsedJson = safeJsonParse(fileContents);
+      if (isErr(parsedJson)) {
+        throw new CliError("Stored CLI settings are invalid.", {
+          cause: parsedJson.error.cause
+        });
+      }
+      const parsed = cliSettingsSchema.safeParse(parsedJson.value);
+      if (!parsed.success) {
+        throw new CliError("Stored CLI settings are invalid.", {
+          cause: parsed.error
+        });
+      }
+      return parsed.data;
+    },
+    async save(settings) {
+      if (!hasCliSettingsOverrides(settings)) {
+        await rm(settingsFilePath, { force: true });
+        return;
+      }
+      await mkdir(path2.dirname(settingsFilePath), { recursive: true });
+      await writeFile(
+        settingsFilePath,
+        `${JSON.stringify(settings, null, 2)}
+`
+      );
+    }
+  };
+}
+
+// src/auth-login.ts
+function writeJsonOutput(io, value) {
+  io.info(JSON.stringify(value, null, 2));
+}
+async function handleAuthLogin(dependencies, options) {
+  const settings = await dependencies.settingsStore?.load() ?? createEmptyCliSettings();
+  const clientId = shouldUseStagingWorkosClientId(settings) ? DEFAULT_STAGING_WORKOS_CLIENT_ID : requireWorkosClientId(dependencies.runtimeConfig);
+  const deviceAuthorization = await dependencies.authClient.startDeviceAuthorization({ clientId });
+  const verificationUrl = deviceAuthorization.verification_uri_complete ?? deviceAuthorization.verification_uri;
+  const promptWriter = options.json ? dependencies.io.error : dependencies.io.info;
+  promptWriter(
+    formatAuthLoginPrompt({
+      userCode: deviceAuthorization.user_code,
+      verificationUrl
+    })
+  );
+  await dependencies.openExternalUrl(verificationUrl).catch(() => {
+    promptWriter(formatBrowserOpenFallback());
+  });
+  const tokenResponse = await dependencies.authClient.pollForDeviceTokens({
+    clientId,
+    deviceCode: deviceAuthorization.device_code,
+    ...deviceAuthorization.expires_in ? { expiresInSeconds: deviceAuthorization.expires_in } : {},
+    ...deviceAuthorization.interval ? { intervalSeconds: deviceAuthorization.interval } : {}
+  });
+  const accessTokenClaims = dependencies.authClient.decodeAccessTokenClaims(
+    tokenResponse.access_token
+  );
+  const [user, organizations] = await Promise.all([
+    dependencies.apiClient.fetchUser({
+      accessToken: tokenResponse.access_token,
+      userId: accessTokenClaims.sub
+    }),
+    dependencies.apiClient.fetchOrganizations({
+      accessToken: tokenResponse.access_token
+    })
+  ]);
+  const defaultOrgId = accessTokenClaims.org_id ?? organizations[0]?.id ?? null;
+  const nextState = {
+    account: {
+      clientId,
+      email: user.email,
+      userId: user.id
+    },
+    defaultOrgId,
+    lastUsedOrgId: defaultOrgId,
+    organizations
+  };
+  await Promise.all([
+    dependencies.refreshTokenStore.save(
+      nextState.account,
+      tokenResponse.refresh_token
+    ),
+    dependencies.stateStore.save(nextState)
+  ]);
+  const defaultOrganization = organizations.find((organization) => organization.id === defaultOrgId) ?? null;
+  if (options.json) {
+    writeJsonOutput(dependencies.io, nextState);
+    return;
+  }
+  dependencies.io.info(
+    formatAuthLoginSuccess({
+      account: nextState.account,
+      defaultOrganization,
+      organizationCount: organizations.length
+    })
+  );
+}
+
+// src/command-presentation.ts
+var rootOperationalGroupDescriptions = /* @__PURE__ */ new Map([
+  ["agents", "Query agents."],
+  ["agent-runs", "Query agent runs."],
+  ["automations", "Manage automations."],
+  ["automation-runs", "Inspect and control automation runs."],
+  ["catalog", "Inspect available commands, models, and tools."],
+  ["graphql", "Inspect GraphQL metadata."]
+]);
+function configureCommandPresentation(command) {
+  const originalCreateCommand = command.createCommand.bind(command);
+  command.createCommand = (name) => configureCommandPresentation(originalCreateCommand(name));
+  command.createHelp = () => new MagicalHelp();
+  return command;
+}
+function createOperationHelpExamples(operationSpec) {
+  const baseCommand = `mgcl ${operationSpec.cli.path.join(" ")}`;
+  const requiredOptions = operationSpec.cli.options.filter((optionSpec) => optionSpec.required).map((optionSpec) => {
+    if (optionSpec.valueType === "boolean") {
+      return `--${optionSpec.flagName}`;
+    }
+    if (optionSpec.valueType === "number") {
+      return `--${optionSpec.flagName} 10`;
+    }
+    if (optionSpec.valueType === "json") {
+      return `--${optionSpec.flagName} '{...}'`;
+    }
+    if (optionSpec.valueType === "string-array") {
+      return `--${optionSpec.flagName} value-a,value-b`;
+    }
+    return `--${optionSpec.flagName} <${optionSpec.flagName}>`;
+  });
+  const baseInvocation = [baseCommand, ...requiredOptions].join(" ");
+  return [
+    baseInvocation,
+    `${baseInvocation} --org <org>`,
+    `${baseInvocation} --json`
+  ];
+}
+
 // src/keychain.ts
 import keytar from "keytar";
 function buildKeychainAccountName(account) {
@@ -1574,7 +1724,7 @@ function resolveOpenCommand(url) {
 // src/self-update.ts
 import { spawn as spawn2 } from "child_process";
 import fs from "fs";
-import path2 from "path";
+import path3 from "path";
 import { fileURLToPath } from "url";
 var CLI_PACKAGE_NAME = "@getmagical/cli";
 var DEFAULT_CLI_DIST_TAG2 = "latest";
@@ -1585,9 +1735,9 @@ function resolveInstalledPackageRoot({
   packageName
 }) {
   const packagePathSegments = packageName.split("/");
-  let currentPath = path2.dirname(entryFilePath);
+  let currentPath = path3.dirname(entryFilePath);
   for (; ; ) {
-    const currentPathSegments = currentPath.split(path2.sep).filter(Boolean);
+    const currentPathSegments = currentPath.split(path3.sep).filter(Boolean);
     const currentPackageSegments = currentPathSegments.slice(
       -packagePathSegments.length
     );
@@ -1596,7 +1746,7 @@ function resolveInstalledPackageRoot({
     )) {
       return currentPath;
     }
-    const parentPath = path2.dirname(currentPath);
+    const parentPath = path3.dirname(currentPath);
     if (parentPath === currentPath) {
       return null;
     }
@@ -1606,14 +1756,14 @@ function resolveInstalledPackageRoot({
 function resolveInstallPrefixFromPackageRoot(packageRootPath) {
   let currentPath = packageRootPath;
   for (; ; ) {
-    if (path2.basename(currentPath) === "node_modules") {
-      const nodeModulesParentPath = path2.dirname(currentPath);
-      if (path2.basename(nodeModulesParentPath) === "lib") {
-        return path2.dirname(nodeModulesParentPath);
+    if (path3.basename(currentPath) === "node_modules") {
+      const nodeModulesParentPath = path3.dirname(currentPath);
+      if (path3.basename(nodeModulesParentPath) === "lib") {
+        return path3.dirname(nodeModulesParentPath);
       }
       return nodeModulesParentPath;
     }
-    const parentPath = path2.dirname(currentPath);
+    const parentPath = path3.dirname(currentPath);
     if (parentPath === currentPath) {
       return null;
     }
@@ -1630,13 +1780,13 @@ function resolveManagedNpmCommand(installPrefix) {
   if (process.platform === "win32") {
     return null;
   }
-  const managedNodeExecutable = path2.join(
+  const managedNodeExecutable = path3.join(
     installPrefix,
     MANAGED_NODE_SUBPATH,
     "bin",
     "node"
   );
-  const managedNpmCli = path2.join(
+  const managedNpmCli = path3.join(
     installPrefix,
     MANAGED_NODE_SUBPATH,
     "lib",
@@ -1734,34 +1884,135 @@ async function selfUpdateInstalledCli({
   });
 }
 
+// src/settings-command.ts
+import { isErr as isErr2 } from "@magical/common/stdlib/result.util";
+import { safeUrlConstructor } from "@magical/common/stdlib/url.utils";
+import { Command, InvalidArgumentError, Option } from "commander";
+function writeJsonOutput2(io, value) {
+  io.info(JSON.stringify(value, null, 2));
+}
+function requireSettingsStore(settingsStore) {
+  if (!settingsStore) {
+    throw new CliError("CLI settings are not configured for this instance.");
+  }
+  return settingsStore;
+}
+function parseBaseUrl(value) {
+  const parsedUrl = safeUrlConstructor(value);
+  if (isErr2(parsedUrl)) {
+    throw new InvalidArgumentError("Expected a valid URL for base-url.");
+  }
+  return parsedUrl.value.toString().replace(/\/$/u, "");
+}
+async function clearSavedAuth(dependencies) {
+  const state = await dependencies.stateStore.load();
+  if (!state) {
+    return false;
+  }
+  await dependencies.refreshTokenStore.clear(state.account);
+  await dependencies.stateStore.clear();
+  return true;
+}
+async function handleSettingsEnvBaseUrl(dependencies, rawBaseUrl, options) {
+  if (options.reset && rawBaseUrl) {
+    throw new CliError("Pass either a base URL or --reset, not both.");
+  }
+  if (!options.reset && !rawBaseUrl) {
+    throw new CliError("Provide a base URL or pass --reset.");
+  }
+  const settingsStore = requireSettingsStore(dependencies.settingsStore);
+  const currentSettings = await settingsStore.load();
+  const { baseUrl: _baseUrl, ...remainingEnvSettings } = currentSettings.env;
+  if (options.reset) {
+    const nextSettings2 = {
+      ...currentSettings,
+      env: remainingEnvSettings
+    };
+    await settingsStore.save(nextSettings2);
+    const authCleared2 = await clearSavedAuth(dependencies);
+    if (options.json) {
+      writeJsonOutput2(dependencies.io, {
+        authCleared: authCleared2,
+        settings: nextSettings2
+      });
+      return;
+    }
+    dependencies.io.info(
+      authCleared2 ? 'Cleared the persisted base-url override and removed saved auth. Run "mgcl auth login" again.' : "Cleared the persisted base-url override."
+    );
+    return;
+  }
+  const nextBaseUrl = parseBaseUrl(rawBaseUrl ?? "");
+  const nextSettings = {
+    ...currentSettings,
+    env: {
+      ...currentSettings.env,
+      baseUrl: nextBaseUrl
+    }
+  };
+  await settingsStore.save(nextSettings);
+  const authCleared = await clearSavedAuth(dependencies);
+  if (options.json) {
+    writeJsonOutput2(dependencies.io, {
+      authCleared,
+      settings: nextSettings
+    });
+    return;
+  }
+  dependencies.io.info(
+    authCleared ? `Saved base-url override ${nextBaseUrl} and removed saved auth. Run "mgcl auth login" again.` : `Saved base-url override ${nextBaseUrl}.`
+  );
+}
+function createSettingsCommand(dependencies) {
+  const settingsCommand = configureCommandPresentation(
+    new Command("settings").description("Manage persisted CLI settings.")
+  ).helpGroup("Workspace:").addHelpText(
+    "after",
+    `
+${formatExamples("Examples", [
+      "mgcl settings env base-url http://main.localhost:1355",
+      "mgcl settings env base-url --reset"
+    ])}`
+  );
+  const settingsEnvCommand = settingsCommand.command("env").description("Manage persisted environment overrides.");
+  settingsEnvCommand.command("base-url [url]").description("Set or clear the persisted Magical API base URL override.").addOption(new Option("--reset", "Clear the persisted base URL override.")).action(async function(baseUrl) {
+    await handleSettingsEnvBaseUrl(
+      dependencies,
+      baseUrl,
+      this.optsWithGlobals()
+    );
+  });
+  return settingsCommand;
+}
+
 // src/state.ts
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
-import path3 from "path";
-import { z as z3 } from "zod";
-var cliAccountSchema = z3.object({
-  clientId: z3.string().min(1),
-  email: z3.string().nullable(),
-  userId: z3.string().min(1)
+import { mkdir as mkdir2, readFile as readFile2, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import path4 from "path";
+import { z as z4 } from "zod";
+var cliAccountSchema = z4.object({
+  clientId: z4.string().min(1),
+  email: z4.string().nullable(),
+  userId: z4.string().min(1)
 });
-var cliOrganizationSchema = z3.object({
-  id: z3.string().min(1),
-  name: z3.string().min(1),
-  primaryDomain: z3.string().nullable().default(null)
+var cliOrganizationSchema = z4.object({
+  id: z4.string().min(1),
+  name: z4.string().min(1),
+  primaryDomain: z4.string().nullable().default(null)
 });
-var cliStateSchema = z3.object({
+var cliStateSchema = z4.object({
   account: cliAccountSchema,
-  defaultOrgId: z3.string().nullable(),
-  lastUsedOrgId: z3.string().nullable(),
-  organizations: z3.array(cliOrganizationSchema)
+  defaultOrgId: z4.string().nullable(),
+  lastUsedOrgId: z4.string().nullable(),
+  organizations: z4.array(cliOrganizationSchema)
 });
 function createFileStateStore(stateFilePath) {
   return {
     async clear() {
-      await rm(stateFilePath, { force: true });
+      await rm2(stateFilePath, { force: true });
     },
     async load() {
       try {
-        const fileContents = await readFile(stateFilePath, "utf8");
+        const fileContents = await readFile2(stateFilePath, "utf8");
         const parsed = cliStateSchema.safeParse(JSON.parse(fileContents));
         if (!parsed.success) {
           throw new CliError("Stored CLI state is invalid.");
@@ -1778,43 +2029,43 @@ function createFileStateStore(stateFilePath) {
       }
     },
     async save(state) {
-      await mkdir(path3.dirname(stateFilePath), { recursive: true });
-      await writeFile(stateFilePath, `${JSON.stringify(state, null, 2)}
+      await mkdir2(path4.dirname(stateFilePath), { recursive: true });
+      await writeFile2(stateFilePath, `${JSON.stringify(state, null, 2)}
 `);
     }
   };
 }
 
 // src/workos-auth.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var DEFAULT_DEVICE_POLL_INTERVAL_SECONDS = 5;
 function buildFormHeaders() {
   const headers = new Headers();
   headers.set("content-type", "application/x-www-form-urlencoded");
   return headers;
 }
-var deviceAuthorizationSchema = z4.object({
-  device_code: z4.string().min(1),
-  expires_in: z4.number().int().positive().optional(),
-  interval: z4.number().int().positive().optional(),
-  user_code: z4.string().min(1),
-  verification_uri: z4.url(),
-  verification_uri_complete: z4.url().optional()
+var deviceAuthorizationSchema = z5.object({
+  device_code: z5.string().min(1),
+  expires_in: z5.number().int().positive().optional(),
+  interval: z5.number().int().positive().optional(),
+  user_code: z5.string().min(1),
+  verification_uri: z5.url(),
+  verification_uri_complete: z5.url().optional()
 });
-var tokenResponseSchema = z4.object({
-  access_token: z4.string().min(1),
-  expires_in: z4.number().int().positive().optional(),
-  refresh_token: z4.string().min(1),
-  token_type: z4.string().optional()
+var tokenResponseSchema = z5.object({
+  access_token: z5.string().min(1),
+  expires_in: z5.number().int().positive().optional(),
+  refresh_token: z5.string().min(1),
+  token_type: z5.string().optional()
 });
-var tokenErrorSchema = z4.object({
-  error: z4.string().min(1),
-  error_description: z4.string().optional()
+var tokenErrorSchema = z5.object({
+  error: z5.string().min(1),
+  error_description: z5.string().optional()
 });
-var accessTokenClaimsSchema = z4.object({
-  org_id: z4.string().min(1).optional(),
-  sid: z4.string().min(1).optional(),
-  sub: z4.string().min(1)
+var accessTokenClaimsSchema = z5.object({
+  org_id: z5.string().min(1).optional(),
+  sid: z5.string().min(1).optional(),
+  sub: z5.string().min(1)
 });
 function createWorkosAuthClient({
   fetchFn = fetch,
@@ -1971,7 +2222,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
     case "number": {
       const parsedNumber = Number(rawValue);
       if (Number.isNaN(parsedNumber)) {
-        throw new InvalidArgumentError(
+        throw new InvalidArgumentError2(
           `Expected a number for --${optionSpec.flagName}.`
         );
       }
@@ -1984,7 +2235,7 @@ function parseCommandOptionValue(rawValue, optionSpec) {
       try {
         return JSON.parse(rawValue);
       } catch {
-        throw new InvalidArgumentError(
+        throw new InvalidArgumentError2(
           `Expected valid JSON for --${optionSpec.flagName}.`
         );
       }
@@ -2038,7 +2289,7 @@ function requireLoggedInState(state) {
   }
   return state;
 }
-function writeJsonOutput(io, value) {
+function writeJsonOutput3(io, value) {
   io.info(JSON.stringify(value, null, 2));
 }
 function collectOperationVariables(operationSpec, options) {
@@ -2094,69 +2345,6 @@ async function withOrgScopedAccessToken({
     accessToken: tokenResponse.access_token
   };
 }
-async function handleAuthLogin(dependencies, options) {
-  const clientId = requireWorkosClientId(dependencies.runtimeConfig);
-  const deviceAuthorization = await dependencies.authClient.startDeviceAuthorization({ clientId });
-  const verificationUrl = deviceAuthorization.verification_uri_complete ?? deviceAuthorization.verification_uri;
-  const promptWriter = options.json ? dependencies.io.error : dependencies.io.info;
-  promptWriter(
-    formatAuthLoginPrompt({
-      userCode: deviceAuthorization.user_code,
-      verificationUrl
-    })
-  );
-  await dependencies.openExternalUrl(verificationUrl).catch(() => {
-    promptWriter(formatBrowserOpenFallback());
-  });
-  const tokenResponse = await dependencies.authClient.pollForDeviceTokens({
-    clientId,
-    deviceCode: deviceAuthorization.device_code,
-    ...deviceAuthorization.expires_in ? { expiresInSeconds: deviceAuthorization.expires_in } : {},
-    ...deviceAuthorization.interval ? { intervalSeconds: deviceAuthorization.interval } : {}
-  });
-  const accessTokenClaims = dependencies.authClient.decodeAccessTokenClaims(
-    tokenResponse.access_token
-  );
-  const [user, organizations] = await Promise.all([
-    dependencies.apiClient.fetchUser({
-      accessToken: tokenResponse.access_token,
-      userId: accessTokenClaims.sub
-    }),
-    dependencies.apiClient.fetchOrganizations({
-      accessToken: tokenResponse.access_token
-    })
-  ]);
-  const defaultOrgId = accessTokenClaims.org_id ?? organizations[0]?.id ?? null;
-  const nextState = {
-    account: {
-      clientId,
-      email: user.email,
-      userId: user.id
-    },
-    defaultOrgId,
-    lastUsedOrgId: defaultOrgId,
-    organizations
-  };
-  await Promise.all([
-    dependencies.refreshTokenStore.save(
-      nextState.account,
-      tokenResponse.refresh_token
-    ),
-    dependencies.stateStore.save(nextState)
-  ]);
-  const defaultOrganization = organizations.find((organization) => organization.id === defaultOrgId) ?? null;
-  if (options.json) {
-    writeJsonOutput(dependencies.io, nextState);
-    return;
-  }
-  dependencies.io.info(
-    formatAuthLoginSuccess({
-      account: nextState.account,
-      defaultOrganization,
-      organizationCount: organizations.length
-    })
-  );
-}
 async function handleAuthLogout(dependencies, options) {
   const state = await dependencies.stateStore.load();
   if (state) {
@@ -2164,7 +2352,7 @@ async function handleAuthLogout(dependencies, options) {
   }
   await dependencies.stateStore.clear();
   if (options.json) {
-    writeJsonOutput(dependencies.io, { loggedOut: true });
+    writeJsonOutput3(dependencies.io, { loggedOut: true });
     return;
   }
   dependencies.io.info(formatLogoutSuccess());
@@ -2172,7 +2360,7 @@ async function handleAuthLogout(dependencies, options) {
 async function handleOrgList(dependencies, options) {
   const state = requireLoggedInState(await dependencies.stateStore.load());
   if (options.json) {
-    writeJsonOutput(dependencies.io, state.organizations);
+    writeJsonOutput3(dependencies.io, state.organizations);
     return;
   }
   dependencies.io.info(
@@ -2196,7 +2384,7 @@ async function handleOrgUse(dependencies, organizationSelector, options) {
   };
   await dependencies.stateStore.save(nextState);
   if (options.json) {
-    writeJsonOutput(dependencies.io, {
+    writeJsonOutput3(dependencies.io, {
       defaultOrgId: organization.id,
       organization
     });
@@ -2211,7 +2399,7 @@ async function handleSelfUpdate(dependencies, options) {
   }
   const updateResult = await selfUpdateCli();
   if (options.json) {
-    writeJsonOutput(dependencies.io, {
+    writeJsonOutput3(dependencies.io, {
       installPrefix: updateResult.installPrefix,
       packageSpecifier: updateResult.packageSpecifier,
       registryUrl: updateResult.registryUrl,
@@ -2246,7 +2434,7 @@ async function handleOperationCommand(dependencies, operationSpec, commandOption
     lastUsedOrgId: organization.id
   });
   if (commandOptions.json) {
-    writeJsonOutput(dependencies.io, result);
+    writeJsonOutput3(dependencies.io, result);
     return;
   }
   dependencies.io.info(formatHumanReadableOutput(result));
@@ -2294,7 +2482,7 @@ function addRegistryOperationCommand({
 }
 function configureOperationalCommand(command, dependencies, operationSpec) {
   command.description(operationSpec.cli.description).addOption(
-    new Option(
+    new Option2(
       "--org <org>",
       "Organization ID or exact organization name to use."
     ).helpGroup("Shared options:")
@@ -2309,7 +2497,7 @@ ${formatExamples(
   for (const optionSpec of operationSpec.cli.options) {
     const optionFlags = optionSpec.valueType === "boolean" ? `--${optionSpec.flagName}` : `--${optionSpec.flagName} <value>`;
     const optionDescription = optionSpec.valueHint ? `${optionSpec.description} (${optionSpec.valueHint})` : optionSpec.description;
-    const nextOption = new Option(optionFlags, optionDescription).helpGroup(
+    const nextOption = new Option2(optionFlags, optionDescription).helpGroup(
       operationSpec.kind === "query" ? "Query options:" : "Mutation options:"
     );
     if (optionSpec.valueType === "boolean") {
@@ -2347,13 +2535,17 @@ function createConsoleIo() {
 }
 function createDefaultDependencies() {
   const runtimeConfig = getRuntimeConfig();
+  const settingsStore = createFileSettingsStore(runtimeConfig.stateFilePath);
   const selfUpdateOptions = {
     ...runtimeConfig.cliDistTag ? { distTag: runtimeConfig.cliDistTag } : {},
     ...runtimeConfig.npmRegistryUrl ? { registryUrl: runtimeConfig.npmRegistryUrl } : {}
   };
   return {
     apiClient: createMagicalApiClient({
-      apiBaseUrl: runtimeConfig.magicalApiUrl
+      apiBaseUrl: async () => resolveConfiguredApiBaseUrl({
+        defaultApiBaseUrl: runtimeConfig.magicalApiUrl,
+        settings: await settingsStore.load()
+      })
     }),
     authClient: createWorkosAuthClient({
       workosApiUrl: runtimeConfig.workosApiUrl
@@ -2364,15 +2556,16 @@ function createDefaultDependencies() {
       runtimeConfig.keychainServiceName
     ),
     runtimeConfig,
+    settingsStore,
     selfUpdateCli: async () => selfUpdateInstalledCli(selfUpdateOptions),
     stateStore: createFileStateStore(runtimeConfig.stateFilePath)
   };
 }
 function buildProgram(dependencies) {
   const program2 = configureCommandPresentation(
-    new Command().name("mgcl").description("Run Magical operations from the command line.")
-  ).addOption(new Option("--json", "Render JSON output.")).addOption(
-    new Option(
+    new Command2().name("mgcl").description("Run Magical operations from the command line.")
+  ).addOption(new Option2("--json", "Render JSON output.")).addOption(
+    new Option2(
       "--update",
       "Update mgcl to the latest published npm release."
     )
@@ -2398,14 +2591,11 @@ ${formatOutputModesNote()}`
     this.outputHelp();
   });
   const authCommand = configureCommandPresentation(
-    new Command("auth").description("Manage CLI authentication.")
+    new Command2("auth").description("Manage CLI authentication.")
   ).helpGroup("Workspace:").addHelpText(
     "after",
     `
-${formatExamples("Examples", [
-      "mgcl auth login",
-      "mgcl auth logout"
-    ])}`
+${formatExamples("Examples", ["mgcl auth login", "mgcl auth logout"])}`
   );
   authCommand.command("login").description("Authenticate with Magical and load organization memberships.").action(async function() {
     await handleAuthLogin(dependencies, this.optsWithGlobals());
@@ -2414,8 +2604,9 @@ ${formatExamples("Examples", [
     await handleAuthLogout(dependencies, this.optsWithGlobals());
   });
   program2.addCommand(authCommand);
+  program2.addCommand(createSettingsCommand(dependencies));
   const orgCommand = configureCommandPresentation(
-    new Command("org").description("Manage organization selection.")
+    new Command2("org").description("Manage organization selection.")
   ).helpGroup("Workspace:").addHelpText(
     "after",
     `
@@ -2436,7 +2627,7 @@ ${formatExamples("Examples", [
   });
   program2.addCommand(orgCommand);
   const updateCommand = configureCommandPresentation(
-    new Command("update").description(
+    new Command2("update").description(
       "Update mgcl to the latest published npm release."
     )
   ).helpGroup("Workspace:").addHelpText(