@project-ajax/cli 0.0.17 → 0.0.18

package/dist/config.d.ts

@@ -20,22 +20,76 @@ declare const LocalConfig: z.ZodObject<{
     workerId: z.ZodNullable<z.ZodString>;
 }, z.z.core.$strip>;
 export type LocalConfig = z.infer<typeof LocalConfig>;
+declare const GlobalConfig: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    defaultSpaceId: z.ZodNullable<z.ZodString>;
+}, z.z.core.$strip>;
+export type GlobalConfig = z.infer<typeof GlobalConfig>;
 export declare class NoSuitableConfigFileError extends Error {
     constructor();
 }
 /**
- * Manages configuration for the command line interface.
+ * Manages configuration for the Workers CLI.
+ *
+ * ## Configuration Sources
+ *
+ * The CLI uses three configuration files:
+ *
+ * 1. **Global user config** (`config.json`) - Stores user preferences like
+ *    `defaultSpaceId`. Located in `$NOTION_HOME/`, `$XDG_CONFIG_HOME/notion/`,
+ *    `$HOME/.config/notion/`, or `$HOME/.notion/`. This file is always created
+ *    when the CLI runs.
+ *
+ * 2. **Global space cache** (`spaces.json`) - Stores authenticated spaces and
+ *    their metadata. Located in the same directory as `config.json`.
+ *
+ * 3. **Local project config** (`workers.json`) - Stores project-specific settings
+ *    like which space and worker the project is associated with. Located in the
+ *    current working directory.
+ *
+ * ## Configuration Precedence
+ *
+ * Values are resolved in this order (highest to lowest priority):
+ * - Environment variables (WORKERS_ENVIRONMENT, WORKERS_BASE_URL, WORKERS_TOKEN)
+ * - Command-line flags (--env, --base-url, --token, --space)
+ * - Local config file (workers.json)
+ * - Global user config (config.json) for `defaultSpaceId`
+ * - Defaults
+ *
+ * Space ID specifically follows: --space > WORKERS_SPACE_ID > workers.json > config.json
  *
- * Order of precedence: Command-line flags, environment variables, local config
- * files, where appropriate.
+ * ## Lazy workers.json Creation
+ *
+ * The `workers.json` file is only written when the CLI detects it's running in
+ * a worker project directory. A directory is considered a worker project if it
+ * contains a `package.json` with any `@project-ajax/*` package in dependencies
+ * or devDependencies.
+ *
+ * This design allows users to run commands like `workers auth login` from their
+ * home directory without creating an unwanted `workers.json` file there. The
+ * authentication still succeeds—the token is stored in the system keychain and
+ * the space is cached in `spaces.json`—but no local config file is created.
+ *
+ * When running in a worker project directory, operations like `login()`,
+ * `switchToSpace()`, and `setWorker()` will create or update `workers.json`
+ * to persist the project's space and worker associations.
+ *
+ * ## Token Storage
+ *
+ * Tokens are stored in the system keychain (via the `cross-keychain` package),
+ * keyed by space ID. This keeps sensitive credentials out of config files and
+ * allows multiple spaces to be authenticated simultaneously.
  */
 export declare class Config {
     #private;
     constructor(opts: {
+        globalConfigPath: string;
+        globalConfig: GlobalConfig;
         spaceCachePath: string;
         spaceCache: SpaceCache;
         localConfigPath: string;
         localConfig: LocalConfig;
+        isInWorkerDirectory: boolean;
         environment: Environment;
         baseURL: string;
         spaceId: string | null;
@@ -46,6 +100,24 @@ export declare class Config {
     get baseURL(): string;
     get spaceId(): string | null;
     get workerId(): string | null;
+    /**
+     * Get the default space ID from global user config.
+     *
+     * This is the space that will be used when no local config exists and
+     * no --space flag is provided.
+     *
+     * @returns The default space ID, or null if not set.
+     */
+    get defaultSpaceId(): string | null;
+    /**
+     * Set the default space ID in global user config.
+     *
+     * This updates the `config.json` file to persist the default space
+     * preference across CLI invocations.
+     *
+     * @param spaceId The space ID to set as default, or null to clear.
+     */
+    setDefaultSpaceId(spaceId: string | null): void;
     /**
      * Get the list of cached spaces.
      *
@@ -104,31 +176,66 @@ export declare class Config {
      * @throws Error if the space is not in the cache.
      */
     switchToSpace(spaceId: string): void;
+    /**
+     * Resolve the global config directory path.
+     *
+     * This is a shared helper used by both `resolveGlobalConfigPath` and
+     * `resolveSpaceCachePath` to determine the directory for global config files.
+     *
+     * Priority order:
+     * 1. `$NOTION_HOME` (if set and is a directory)
+     * 2. `$XDG_CONFIG_HOME/notion` (if XDG_CONFIG_HOME is set)
+     * 3. `$HOME/.config/notion` (if $HOME/.config exists)
+     * 4. `$HOME/.notion` (fallback)
+     *
+     * @param env The environment variables.
+     * @returns The directory path, or undefined if no suitable directory found.
+     */
+    static resolveGlobalDir(env: NodeJS.ProcessEnv): string | undefined;
+    /**
+     * Resolve the global config path.
+     *
+     * The global config file (`config.json`) stores user preferences like
+     * `defaultSpaceId`. It uses the same directory resolution as `spaces.json`.
+     *
+     * @param opts Options for resolving the global config path.
+     * @param opts.env The environment variables.
+     * @param opts.create Whether to create the file if it doesn't exist.
+     * @returns The path to the global config file.
+     */
+    static resolveGlobalConfigPath(opts: {
+        env: NodeJS.ProcessEnv;
+        create?: boolean;
+    }): string;
     /**
      * Resolve the space cache path.
      *
      * @param opts Options for resolving the space cache path.
      * @param opts.filePath The path to the space cache file.
      * @param opts.env The environment variables.
+     * @param opts.create Whether to create the file if it doesn't exist.
      * @returns The path to the space cache file.
      */
     static resolveSpaceCachePath(opts: {
         filePath?: string;
         env: NodeJS.ProcessEnv;
+        create?: boolean;
     }): string;
     /**
      * Resolve the local config path.
      *
      * @param opts Options for resolving the local config path.
      * @param opts.filePath The path to the local config file.
-     * @returns
+     * @param opts.create Whether to create the file if it doesn't exist.
+     * @returns The path to the local config file.
      */
     static resolveLocalConfigPath(opts?: {
         filePath?: string;
+        create?: boolean;
     }): string;
     /**
-     * Load config from space cache and local config files, then resolve them to
-     * a final config for this execution of the command line interface.
+     * Load config from global config, space cache, and local config files, then
+     * resolve them to a final config for this execution of the command line interface.
      *
      * If the local config is v0, it will be upgraded to v1.
      *
@@ -137,16 +244,19 @@ export declare class Config {
      * - Environment: WORKERS_ENVIRONMENT or --env flag
      * - Token: WORKERS_TOKEN or --token flag
      * - Base URL: WORKERS_BASE_URL or --base-url flag
+     * - Space: --space flag > WORKERS_SPACE_ID > workers.json > config.json defaultSpaceId
      *
      * @param opts The options to load the config from.
+     * @param opts.globalConfigPath The path to the global config file.
      * @param opts.spaceCachePath The path to the space cache file.
      * @param opts.localPath The path to the local config file.
      * @param opts.env The process environment.
-     * @param opts.processEnv The process environment.
      * @param opts.flags The global flags.
+     * @param opts.spaceOverride Optional space ID override (from --space flag).
      * @returns The resolved config.
      */
     static load(opts: {
+        globalConfigPath: string;
         spaceCachePath: string;
         localPath: string;
         env: NodeJS.ProcessEnv;
@@ -160,6 +270,10 @@ export declare class Config {
      * The empty space cache.
      */
     static get emptySpaceCache(): SpaceCache;
+    /**
+     * The empty global config.
+     */
+    static get emptyGlobalConfig(): GlobalConfig;
 }
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -30,6 +30,10 @@ const LocalConfigV0 = z.object({
   token: z.string().nullable(),
   workerId: z.string().nullable()
 }).partial();
+const GlobalConfig = z.object({
+  version: z.literal("1"),
+  defaultSpaceId: z.string().nullable()
+});
 class NoSuitableConfigFileError extends Error {
   constructor() {
     super("No suitable config file found");
@@ -37,20 +41,26 @@ class NoSuitableConfigFileError extends Error {
   }
 }
 class Config {
+  #globalConfigPath;
+  #globalConfig;
   #spaceCachePath;
   #spaceCache;
   #localConfigPath;
   #localConfig;
+  #isInWorkerDirectory;
   #baseURL;
   #environment;
   #spaceId;
   #workerId;
   #token = null;
   constructor(opts) {
+    this.#globalConfigPath = opts.globalConfigPath;
+    this.#globalConfig = opts.globalConfig;
     this.#spaceCachePath = opts.spaceCachePath;
     this.#spaceCache = opts.spaceCache;
     this.#localConfigPath = opts.localConfigPath;
     this.#localConfig = opts.localConfig;
+    this.#isInWorkerDirectory = opts.isInWorkerDirectory;
     this.#baseURL = opts.baseURL;
     this.#spaceId = opts.spaceId;
     this.#workerId = opts.workerId;
@@ -69,6 +79,29 @@ class Config {
   get workerId() {
     return this.#workerId;
   }
+  /**
+   * Get the default space ID from global user config.
+   *
+   * This is the space that will be used when no local config exists and
+   * no --space flag is provided.
+   *
+   * @returns The default space ID, or null if not set.
+   */
+  get defaultSpaceId() {
+    return this.#globalConfig.defaultSpaceId;
+  }
+  /**
+   * Set the default space ID in global user config.
+   *
+   * This updates the `config.json` file to persist the default space
+   * preference across CLI invocations.
+   *
+   * @param spaceId The space ID to set as default, or null to clear.
+   */
+  setDefaultSpaceId(spaceId) {
+    this.#globalConfig.defaultSpaceId = spaceId;
+    this.#writeGlobalConfig();
+  }
   /**
    * Get the list of cached spaces.
    *
@@ -163,31 +196,123 @@ class Config {
     this.#localConfig.spaceId = spaceId;
     this.#writeLocalConfig();
   }
+  /**
+   * Write the space cache to disk.
+   *
+   * The space cache is always written, regardless of the current directory,
+   * since it's a global user-level file.
+   */
   #writeSpaceCache() {
     fs.writeFileSync(
       this.#spaceCachePath,
       JSON.stringify(this.#spaceCache, null, 2)
     );
   }
+  /**
+   * Write the local config to disk.
+   *
+   * This is a no-op if the current directory is not a worker project (i.e.,
+   * does not contain a package.json with @project-ajax/* dependencies). This
+   * prevents creating workers.json files in unintended locations like the
+   * user's home directory when running `workers auth login`.
+   *
+   * @see isWorkerDirectory for the detection logic
+   */
   #writeLocalConfig() {
+    if (!this.#isInWorkerDirectory) {
+      return;
+    }
     fs.writeFileSync(
       this.#localConfigPath,
       JSON.stringify(this.#localConfig, null, 2)
     );
   }
+  /**
+   * Write the global config to disk.
+   *
+   * The global config is always written since it's a user-level file.
+   */
+  #writeGlobalConfig() {
+    fs.writeFileSync(
+      this.#globalConfigPath,
+      JSON.stringify(this.#globalConfig, null, 2)
+    );
+  }
+  /**
+   * Resolve the global config directory path.
+   *
+   * This is a shared helper used by both `resolveGlobalConfigPath` and
+   * `resolveSpaceCachePath` to determine the directory for global config files.
+   *
+   * Priority order:
+   * 1. `$NOTION_HOME` (if set and is a directory)
+   * 2. `$XDG_CONFIG_HOME/notion` (if XDG_CONFIG_HOME is set)
+   * 3. `$HOME/.config/notion` (if $HOME/.config exists)
+   * 4. `$HOME/.notion` (fallback)
+   *
+   * @param env The environment variables.
+   * @returns The directory path, or undefined if no suitable directory found.
+   */
+  static resolveGlobalDir(env) {
+    const home = env.HOME;
+    const xdgConfigHome = env.XDG_CONFIG_HOME;
+    const notionHome = env.NOTION_HOME;
+    if (notionHome && isDir(notionHome)) {
+      return notionHome;
+    } else if (xdgConfigHome && isDir(xdgConfigHome)) {
+      return path.join(xdgConfigHome, "notion");
+    } else if (home && isDir(path.join(home, ".config"))) {
+      return path.join(home, ".config", "notion");
+    } else if (home && isDir(home)) {
+      return path.join(home, ".notion");
+    }
+    return void 0;
+  }
+  /**
+   * Resolve the global config path.
+   *
+   * The global config file (`config.json`) stores user preferences like
+   * `defaultSpaceId`. It uses the same directory resolution as `spaces.json`.
+   *
+   * @param opts Options for resolving the global config path.
+   * @param opts.env The environment variables.
+   * @param opts.create Whether to create the file if it doesn't exist.
+   * @returns The path to the global config file.
+   */
+  static resolveGlobalConfigPath(opts) {
+    const configDir = Config.resolveGlobalDir(opts.env);
+    if (!configDir) {
+      throw new NoSuitableConfigFileError();
+    }
+    const configFilePath = path.join(configDir, "config.json");
+    debug("%o", { configDir, configFilePath });
+    if (opts.create && !fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+    }
+    if (fs.existsSync(configDir) && !isDir(configDir)) {
+      throw new NoSuitableConfigFileError();
+    }
+    if (opts.create && !fs.existsSync(configFilePath)) {
+      fs.writeFileSync(
+        configFilePath,
+        JSON.stringify(Config.emptyGlobalConfig, null, 2)
+      );
+    }
+    if (fs.existsSync(configFilePath) && !isFile(configFilePath)) {
+      throw new NoSuitableConfigFileError();
+    }
+    return configFilePath;
+  }
   /**
    * Resolve the space cache path.
    *
    * @param opts Options for resolving the space cache path.
    * @param opts.filePath The path to the space cache file.
    * @param opts.env The environment variables.
+   * @param opts.create Whether to create the file if it doesn't exist.
    * @returns The path to the space cache file.
    */
   static resolveSpaceCachePath(opts) {
-    const env = opts.env;
-    const home = env.HOME;
-    const xdgConfigHome = env.XDG_CONFIG_HOME;
-    const notionHome = env.NOTION_HOME;
     let configFileDir;
     let configFilePath;
     if (opts.filePath) {
@@ -195,37 +320,29 @@ class Config {
       configFileDir = path.dirname(absPath);
       configFilePath = absPath;
     } else {
-      if (notionHome && isDir(notionHome)) {
-        configFileDir = notionHome;
-        configFilePath = path.join(configFileDir, "spaces.json");
-      } else if (xdgConfigHome && isDir(xdgConfigHome)) {
-        configFileDir = path.join(xdgConfigHome, "notion");
-        configFilePath = path.join(configFileDir, "spaces.json");
-      } else if (home && isDir(path.join(home, ".config"))) {
-        configFileDir = path.join(home, ".config", "notion");
-        configFilePath = path.join(configFileDir, "spaces.json");
-      } else if (home && isDir(home)) {
-        configFileDir = path.join(home, ".notion");
-        configFilePath = path.join(configFileDir, "spaces.json");
+      const configDir = Config.resolveGlobalDir(opts.env);
+      if (configDir) {
+        configFileDir = configDir;
+        configFilePath = path.join(configDir, "spaces.json");
       }
     }
     debug("%o", { configFileDir, configFilePath });
     if (!(configFileDir && configFilePath)) {
       throw new NoSuitableConfigFileError();
     }
-    if (!fs.existsSync(configFileDir)) {
+    if (opts.create && !fs.existsSync(configFileDir)) {
       fs.mkdirSync(configFileDir, { recursive: true });
     }
-    if (!isDir(configFileDir)) {
+    if (fs.existsSync(configFileDir) && !isDir(configFileDir)) {
       throw new NoSuitableConfigFileError();
     }
-    if (!fs.existsSync(configFilePath)) {
+    if (opts.create && !fs.existsSync(configFilePath)) {
       fs.writeFileSync(
         configFilePath,
         JSON.stringify(Config.emptySpaceCache, null, 2)
       );
     }
-    if (!isFile(configFilePath)) {
+    if (fs.existsSync(configFilePath) && !isFile(configFilePath)) {
       throw new NoSuitableConfigFileError();
     }
     return configFilePath;
@@ -235,27 +352,28 @@ class Config {
    *
    * @param opts Options for resolving the local config path.
    * @param opts.filePath The path to the local config file.
-   * @returns
+   * @param opts.create Whether to create the file if it doesn't exist.
+   * @returns The path to the local config file.
    */
   static resolveLocalConfigPath(opts = {}) {
     const absPath = path.resolve(
       process.cwd(),
       opts.filePath ?? "./workers.json"
     );
-    if (!fs.existsSync(absPath)) {
+    if (opts.create && !fs.existsSync(absPath)) {
       fs.writeFileSync(
         absPath,
         JSON.stringify(Config.emptyLocalConfig, null, 2)
       );
     }
-    if (!isFile(absPath)) {
+    if (fs.existsSync(absPath) && !isFile(absPath)) {
       throw new NoSuitableConfigFileError();
     }
     return absPath;
   }
   /**
-   * Load config from space cache and local config files, then resolve them to
-   * a final config for this execution of the command line interface.
+   * Load config from global config, space cache, and local config files, then
+   * resolve them to a final config for this execution of the command line interface.
    *
    * If the local config is v0, it will be upgraded to v1.
    *
@@ -264,43 +382,60 @@ class Config {
    * - Environment: WORKERS_ENVIRONMENT or --env flag
    * - Token: WORKERS_TOKEN or --token flag
    * - Base URL: WORKERS_BASE_URL or --base-url flag
+   * - Space: --space flag > WORKERS_SPACE_ID > workers.json > config.json defaultSpaceId
    *
    * @param opts The options to load the config from.
+   * @param opts.globalConfigPath The path to the global config file.
    * @param opts.spaceCachePath The path to the space cache file.
    * @param opts.localPath The path to the local config file.
    * @param opts.env The process environment.
-   * @param opts.processEnv The process environment.
    * @param opts.flags The global flags.
+   * @param opts.spaceOverride Optional space ID override (from --space flag).
    * @returns The resolved config.
    */
   static load(opts) {
-    const { spaceCachePath, localPath, env, flags } = opts;
+    const { globalConfigPath, spaceCachePath, localPath, env, flags } = opts;
+    let globalConfig;
+    if (fs.existsSync(globalConfigPath)) {
+      const globalJson = fs.readFileSync(globalConfigPath, "utf-8");
+      const globalRaw = JSON.parse(globalJson);
+      globalConfig = GlobalConfig.parse(globalRaw);
+    } else {
+      globalConfig = Config.emptyGlobalConfig;
+    }
     const cacheJson = fs.readFileSync(spaceCachePath, "utf-8");
     const cacheRaw = JSON.parse(cacheJson);
     const spaceCache = SpaceCache.parse(cacheRaw);
-    const localJson = fs.readFileSync(localPath, "utf-8");
-    const localRaw = JSON.parse(localJson);
     let localConfig;
-    const v1Result = LocalConfig.safeParse(localRaw);
-    if (v1Result.success) {
-      localConfig = v1Result.data;
+    if (fs.existsSync(localPath)) {
+      const localJson = fs.readFileSync(localPath, "utf-8");
+      const localRaw = JSON.parse(localJson);
+      const v1Result = LocalConfig.safeParse(localRaw);
+      if (v1Result.success) {
+        localConfig = v1Result.data;
+      } else {
+        const v0Config = LocalConfigV0.parse(localRaw);
+        localConfig = upgradeV0ToV1(v0Config, localPath);
+      }
     } else {
-      const v0Config = LocalConfigV0.parse(localRaw);
-      localConfig = upgradeV0ToV1(v0Config, localPath);
+      localConfig = Config.emptyLocalConfig;
     }
     const environment = Environment.parse(
       env.WORKERS_ENVIRONMENT ?? flags.env ?? localConfig.environment
     );
     const baseURLOverride = env.WORKERS_BASE_URL ?? flags["base-url"] ?? localConfig.baseURL;
     const baseURL = baseURLOverride ?? baseUrlForEnvironment(environment);
-    const spaceId = localConfig.spaceId;
+    const spaceId = flags.space ?? env.WORKERS_SPACE_ID ?? localConfig.spaceId ?? globalConfig.defaultSpaceId;
     const workerId = localConfig.workerId;
     const token = env.WORKERS_TOKEN ?? flags.token ?? null;
     return new Config({
+      globalConfigPath,
+      globalConfig,
       spaceCachePath,
       spaceCache,
       localConfigPath: localPath,
       localConfig,
+      isInWorkerDirectory: isWorkerDirectory(path.dirname(localPath)),
       environment,
       baseURL,
       spaceId,
@@ -320,6 +455,12 @@ class Config {
   static get emptySpaceCache() {
     return { version: "1", spaces: {} };
   }
+  /**
+   * The empty global config.
+   */
+  static get emptyGlobalConfig() {
+    return { version: "1", defaultSpaceId: null };
+  }
 }
 function isDir(path2) {
   try {
@@ -328,9 +469,25 @@ function isDir(path2) {
     return false;
   }
 }
-function isFile(path2) {
+function isFile(filePath) {
   try {
-    return fs.statSync(path2).isFile();
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+function isWorkerDirectory(dir) {
+  const packageJsonPath = path.join(dir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return false;
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies
+    };
+    return Object.keys(allDeps).some((dep) => dep.startsWith("@project-ajax/"));
   } catch {
     return false;
   }

package/dist/flags.d.ts

@@ -7,14 +7,19 @@ export interface GlobalFlags {
     env?: Environment;
     token?: string;
     "base-url"?: string;
+    space?: string;
 }
 export declare const globalFlags: {
     [K in keyof Required<GlobalFlags>]: TypedFlagParameter<GlobalFlags[K], LocalContext>;
 };
 export interface FormatFlags {
     plain: boolean;
+    human: boolean;
+    json: boolean;
 }
 export declare const formatFlags: {
     [K in keyof Required<FormatFlags>]: TypedFlagParameter<FormatFlags[K], LocalContext>;
 };
+export type OutputFormat = "human" | "plain" | "json";
+export declare function resolveFormat(flags: FormatFlags, process: NodeJS.Process): OutputFormat;
 //# sourceMappingURL=flags.d.ts.map

package/dist/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,EAAE;KACxB,CAAC,IAAI,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,kBAAkB,CACrD,WAAW,CAAC,CAAC,CAAC,EACd,YAAY,CACZ;CA+BD,CAAC;AAEF,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,WAAW,EAAE;KACxB,CAAC,IAAI,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,kBAAkB,CACrD,WAAW,CAAC,CAAC,CAAC,EACd,YAAY,CACZ;CAOD,CAAC"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../src/flags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,WAAW,EAAE;KACxB,CAAC,IAAI,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,kBAAkB,CACrD,WAAW,CAAC,CAAC,CAAC,EACd,YAAY,CACZ;CAsCD,CAAC;AAEF,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACd;AAED,eAAO,MAAM,WAAW,EAAE;KACxB,CAAC,IAAI,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,kBAAkB,CACrD,WAAW,CAAC,CAAC,CAAC,EACd,YAAY,CACZ;CAiBD,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEtD,wBAAgB,aAAa,CAC5B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,MAAM,CAAC,OAAO,GACrB,YAAY,CAoBd"}

package/dist/flags.js

@@ -28,6 +28,12 @@ const globalFlags = {
     parse: String,
     brief: "The base URL to use for all API requests",
     optional: true
+  },
+  space: {
+    kind: "parsed",
+    parse: String,
+    brief: "Space ID to use. Overrides local config and global default. Triggers login if not authenticated.",
+    optional: true
   }
 };
 const formatFlags = {
@@ -35,9 +41,36 @@ const formatFlags = {
     kind: "boolean",
     brief: "Output the results in plain text format",
     default: false
+  },
+  human: {
+    kind: "boolean",
+    brief: "Output the results in a human-friendly format",
+    default: false
+  },
+  json: {
+    kind: "boolean",
+    brief: "Output the results as JSON",
+    default: false
   }
 };
+function resolveFormat(flags, process) {
+  const flagCount = Number(flags.plain) + Number(flags.human) + Number(flags.json);
+  if (flagCount > 1) {
+    throw new Error("Only one of --plain, --human, or --json can be used.");
+  }
+  if (flags.json) {
+    return "json";
+  }
+  if (flags.plain) {
+    return "plain";
+  }
+  if (flags.human) {
+    return "human";
+  }
+  return process.stdout.isTTY ? "human" : "plain";
+}
 export {
   formatFlags,
-  globalFlags
+  globalFlags,
+  resolveFormat
 };