lim 0.45.1 → 0.46.1

package/JSON_OUTPUT.md

@@ -0,0 +1,123 @@
+# CLI JSON contract
+
+Use `--json` for automation on commands whose help lists that flag. JSON output is a public CLI interface. Preserve existing field names, types, and meanings when changing a command. Additive fields are allowed; consumers should ignore fields they do not use. Removing or renaming a field requires a documented compatibility change.
+
+## Transport and exit status
+
+- Non-streaming commands write one JSON value to stdout. List commands return arrays, including `[]` for no results. Resource commands retain their API/SDK response fields, rather than rendering table cells as strings.
+- Log streams, foreground builds and app launches, `sync --watch`, `tunnel run`, and `xcode test` write newline-delimited JSON. Each line is a complete JSON value. Newlines inside strings are escaped.
+- Commands that hold a connection, such as `android connect`, device tunnels, reverse tunnels, and RBE, write their readiness result and stay running. Creation with `--rm` also stays running after its instance response. JSON changes output, not lifecycle.
+- Human messages and SDK diagnostics never go to stdout in JSON mode. Diagnostics may appear on stderr. `--quiet --json` has the same JSON result as `--json`.
+- Check the process exit status. Nonzero means failure. Execution commands can return a structured result with a nonzero `exitCode` or `code`; receiving JSON alone does not mean success. A failed mutation does not emit a success acknowledgement.
+- CLI, validation, and API errors emit `{"error":{"code":"CLI_ERROR","message":"..."}}` on stderr. A specific error code replaces `CLI_ERROR` when available; HTTP errors also include numeric `status`. stderr may also contain diagnostics, so do not parse the whole stream as one JSON document. Explicit process exits after an execution result preserve the exit status without adding another result.
+- Pass the CLI's `--json` before `--`. Flags after `--` belong to the invoked tool. Interactive commands that do not advertise JSON, including `login` and the onboarding `run`, reject it.
+
+## Instance and asset resources
+
+| Commands                                                        | JSON result                                                                                                                               |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `android create`, `ios create`, `xcode create`, `gradle create` | The created instance resource, including `metadata`, `spec`, and `status`. Existing attachment fields on iOS/Xcode creation are retained. |
+| `android get`, `ios get`, `gradle get`                          | The instance resource. With no explicit or remembered instance, the existing fallback returns the corresponding list.                     |
+| `xcode get`                                                     | The existing resolved Xcode target fields plus `simulator` status.                                                                        |
+| Instance `list` commands                                        | Array of instance resources.                                                                                                              |
+| Instance `delete`, `asset delete`, `tunnel delete`              | `{"ok":true,"id":"..."}`. The ID identifies the resource deleted. Instance deletion remains idempotent for an already-missing instance.   |
+| `asset push`                                                    | The uploaded asset resource, including `id`, `name`, and any API-provided expiry and URLs.                                                |
+| `asset list`                                                    | Array of asset resources.                                                                                                                 |
+| `asset pull`                                                    | `{"localPath":"/absolute/path","bytes":123}`.                                                                                             |
+
+`assets` aliases use the same contract as `asset`.
+
+Android creation returns the same instance resource with or without `--connect`. The default still starts a background ADB tunnel. `--no-connect` skips it; JSON mode already suppresses browser opening. Foreground connection modes return the resource after starting the tunnel, before waiting for shutdown.
+
+```sh
+lim android create --hard-timeout=10m --json > instance.json
+jq -r '.metadata.id' instance.json
+
+# Create without starting a local ADB tunnel.
+lim android create --hard-timeout=10m --no-connect --json > instance.json
+lim android connect --id "$(jq -r '.metadata.id' instance.json)"
+
+lim asset push ./app.apk --json | jq -r .id
+```
+
+Instance responses include access credentials. Store them with the same care as API responses.
+
+## Device actions and files
+
+Existing JSON-enabled device commands keep their existing response shapes. In particular, element trees, selectors, device info, app lists, microphone operations, proxy operations, and file operations retain their API/SDK fields.
+
+| Commands                          | JSON result                                                                                                                                                                                              |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| iOS/Android `tap`                 | `{ok:true, instanceId, x, y}`; iOS adds `display` when explicitly selected.                                                                                                                              |
+| iOS/Android `type`                | `{ok:true, instanceId, textLength}`; iOS adds `enter` and `requireFocus`, Android adds `target` when selected. `textLength` counts UTF-16 code units; input text is not echoed.                          |
+| iOS/Android `press-key`           | `{ok:true, instanceId, key, modifiers}`. `modifiers` is an array, empty when none were requested.                                                                                                        |
+| iOS/Android `scroll`              | `{ok:true, instanceId, direction, amount}`; iOS adds requested `momentum`, `coordinate: [x,y]`, and `display`. Android adds `target` when selected.                                                      |
+| iOS/Android `open-url`            | `{ok:true, instanceId, url}`.                                                                                                                                                                            |
+| iOS/Android `terminate-app`       | `{ok:true, instanceId, bundleId}` on iOS; `packageName` on Android.                                                                                                                                      |
+| Detached iOS/Android `launch-app` | `{ok:true, instanceId, bundleId, mode}` on iOS; `packageName` on Android. `mode` is the effective launch mode, including defaults. iOS adds `runtime` when requested. Environment values are not echoed. |
+| iOS `swipe`                       | `{ok:true, instanceId, from:[x,y], to:[x,y], durationMs}`; adds `display` when explicitly selected.                                                                                                      |
+| iOS `toggle-keyboard`             | `{ok:true, instanceId}`. The API does not report the resulting keyboard visibility.                                                                                                                      |
+| Android `install-app`             | `{ok:true, instanceId, source}`. `source` is the supplied path or URL; local uploads also include `assetId`. Acknowledges sending the asset to the instance.                                             |
+| `ios install-app`                 | Existing installation result, including the bundle ID when supplied by the SDK.                                                                                                                          |
+| `android set-wifi-bandwidth`      | `{ok:true, instanceId, downKbps:0, upKbps:1000}`. Only requested directions are included; zero clears that limit.                                                                                        |
+| iOS/Android `record start`        | `{ok:true, instanceId, recording:true, quality, persist}`. Explicit retention adds `persistTtlSeconds`. iOS adds `touchIndicators` and, when requested, `display`.                                       |
+| iOS/Android `record stop`         | `{ok:true, instanceId, recording:false, localPath, uploaded}`. `uploaded` is true after a requested presigned upload completes.                                                                          |
+| `ios keychain generate-key`       | `{"key":"base64-encoded-key"}`.                                                                                                                                                                          |
+| `android connect`                 | `{"instanceId":"...","address":{"address":"127.0.0.1","port":12345}}` from the local tunnel. The command stays running.                                                                                  |
+
+Camera `play` on both platforms returns `{ok:true, instanceId, action:"play", localPath, loop}`. Camera `clear` returns `{ok:true, instanceId, action:"clear"}`. Existing `ok` and `loop` fields are retained.
+
+These action results identify the resolved instance, including when the CLI selected a remembered instance. Parameters describe the submitted action after it succeeds, not a separate observation of device state. Optional targeting fields are omitted when no override was supplied. Android `target` uses the SDK shape: `{x,y}` or `{selector:{resourceId, text, ...}}`.
+
+Direct WebSocket connections and background session connections have the same command output contract.
+
+## Builds, execution, sync, and logs
+
+| Commands                                                                       | JSON result                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Foreground `xcode build`, `gradle build`                                       | NDJSON `{type:"stdout",line}` and `{type:"stderr",line}` events, followed by `{type:"result",instanceId,...SDK execution result}`. The result retains `execId`, `status`, `exitCode`, artifact/store fields, `timedOut`, and `incomplete`. |
+| `xcode build --detach`, `gradle build --detach`                                | Existing `instanceId`, `execId`, `consoleUrl`, `logsCommand`, and optional `webhookUrl`. Acceptance does not mean completion.                                                                                                              |
+| Xcode/Gradle `run`, `tools`, `tools install`, mise `use`                       | SDK execution result plus captured `stdout` and `stderr` strings. Mixed `xcode use xcode@... node@...` adds the Xcode selection under `xcode`. Xcode-only selection keeps its existing selection response.                                 |
+| iOS `simctl`, `xcrun`, `xcodebuild`, `defaults`, `notify`; Android `adb-shell` | Existing tool execution response, with stdout, stderr, and the tool's `code` or `exitCode`.                                                                                                                                                |
+| `ios maestro`                                                                  | `{"exitCode":0}`; Maestro output goes to stderr.                                                                                                                                                                                           |
+| iOS/Android/Xcode/Gradle `sync`                                                | SDK sync result, such as `bytesSent`, and optional installed app fields. No watcher function is serialized.                                                                                                                                |
+| `sync --watch`                                                                 | One SDK sync event per line, including `bytesSent`, `durationMs`, and optional installed app fields, for the initial sync and each update.                                                                                                 |
+| Android `app-log` without `--follow`                                           | Shell result containing `stdout`, `stderr`, and `exitCode`.                                                                                                                                                                                |
+| iOS `app-log` without `--follow`                                               | `{"stdout":"..."}`.                                                                                                                                                                                                                        |
+| Android `app-log --follow`                                                     | One API app-log capture record per line.                                                                                                                                                                                                   |
+| iOS `app-log --follow`, Android `logcat`, iOS `syslog`                         | One `{"line":"..."}` record per line.                                                                                                                                                                                                      |
+| Foreground iOS/Android `launch-app`                                            | The detached launch fields with `type:"launched"` instead of `ok`; iOS log events use `{type:"log",line}`. Exit events use `type:"exit"` and the SDK app-exit fields; Android includes its log tail in `logs`.                             |
+| `xcode test`                                                                   | Existing XCTest event records followed by the existing terminal `{exitCode, timedOut?, incomplete?}` record.                                                                                                                               |
+| Xcode/Gradle `logs`                                                            | Existing collected execution-log response.                                                                                                                                                                                                 |
+
+Foreground build output events preserve the order received from the SDK and identify the original stream. Lines are not buffered until the build ends. Empty lines remain empty strings, and embedded newlines are escaped. Once execution returns, exactly one `result` event ends the stream, including for failed and timed-out executions. A CLI/API failure before an execution result is available emits an error on stderr instead. `--detach` retains its single acknowledgement object.
+
+A `timedOut` execution result means the client stopped waiting. The remote execution may still be running. Inspect `incomplete` and follow its logs instead of assuming that retrying is harmless.
+
+```sh
+lim gradle build . --json > build.ndjson 2> diagnostics.log
+jq 'select(.type == "result")' build.ndjson
+jq -r 'select(.type == "stdout" or .type == "stderr") | .line' build.ndjson
+lim ios syslog --json | jq --unbuffered -r .line
+lim xcode sync . --watch --json | jq --unbuffered .bytesSent
+```
+
+## Sessions and tunnels
+
+| Commands                                                                  | JSON result                                                                                                                                       |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `session start`                                                           | `{"instanceId":"...","running":true,"alreadyRunning":false}`.                                                                                     |
+| `session stop`                                                            | `{"stopped":["instance-id"]}`. Empty if nothing was running; `--all` produces one array, not one response per session. Ambiguous selection fails. |
+| `session status`                                                          | Existing array of session status objects.                                                                                                         |
+| Device tunnel start/status/stop, `ios reverse`                            | Existing readiness/status/stop responses.                                                                                                         |
+| `tunnel run`                                                              | One SDK connector event per line.                                                                                                                 |
+| Private tunnel create/list/update/rotate                                  | Existing API tunnel responses and token fields.                                                                                                   |
+| `xcode rbe`                                                               | Existing readiness result. An already-running tunnel returns its stored process fields plus `running: true`.                                      |
+| `xcode rbe --stop`                                                        | `{"stopped":false}` if none is running; otherwise `{stopped:true, forced, instanceId, pid}`.                                                      |
+| `xcode rbe upload`, version selection, set-instance, and `skills install` | Existing structured results are unchanged.                                                                                                        |
+
+## Maintaining the contract
+
+Changes must keep JSON stdout free of human text on success, failure, empty results, daemon and direct connections, and foreground and detached paths. Use `outputJson` for finite results, `outputEvent` for streams, and `outputResult` for data with a human-readable alternative. Do not use plain logging or inherited child stdout for JSON results. Configure SDK clients so their informational logging cannot reach stdout.
+
+The CLI tests exercise response shapes, stream framing, both device transports, default Android creation, foreground and detached behavior, failures, and the executable's error handling. Add a contract test when adding a new JSON branch or changing a response.

package/README.md

@@ -498,16 +498,31 @@ lim xcode version list    # Xcode versions the sandbox can build with
 
 ### Disk snapshots
 
-Restore and save build state across Xcode instances with a snapshot key:
+New Xcode instances automatically restore and save a disk snapshot using the
+Git origin host/repository and project subdirectory, for example
+`github.com/acme/monorepo/apps/ios`. SSH and HTTPS origins produce the same key;
+branches and commits share it. The key alone controls both restore and save.
+Discovery reads repository-local Git metadata directly, including worktree and
+submodule pointers, so it does not require the Git executable. Global Git
+settings and URL rewrites are not used; config includes require an explicit key.
+
+`build`, `test`, and `sync` use their project path; `create` uses the current
+directory. `lim run` uses its detected project, and `lim ios create --xcode`
+uses the current directory. Existing instances keep their original snapshot settings. Without
+a usable Git origin, pass `--snapshot-key` explicitly. Use `--no-snapshot` to
+create an uncached instance.
+
+From the project directory:
 
 ```bash
-XCODE_ID=$(lim xcode create --snapshot-key myapp-main --quiet)
+XCODE_ID=$(lim xcode create --quiet)
 lim xcode build . --id "$XCODE_ID" --scheme MyApp
 lim xcode delete "$XCODE_ID" --wait-snapshot
 ```
 
 The first build starts cold. Termination publishes the workspace, and the next
-instance restores it. Use `--snapshot-restore-keys "myapp-pr51,myapp-main"` at
+instance restores it. Override with `--snapshot-key` when separate branches or
+Xcode versions need independent saved state. Use `--snapshot-restore-keys "myapp-pr51,myapp-main"` at
 creation for ordered exact-key and literal-prefix fallbacks. Leave
 `--snapshot-paths` unset to save the whole workspace. On existing instances,
 restore keys and paths stay fixed; `build --snapshot-key` only binds a publication
@@ -994,7 +1009,7 @@ journey remains continuous. Set `LIM_DISABLE_TELEMETRY=1` to disable collection.
 
 ## JSON Output
 
-All commands support `--json` for machine-readable output, making the CLI suitable for scripting and AI agent automation:
+Commands that advertise `--json` provide a machine-readable CLI contract. Finite commands return one JSON value; streams and watch modes use newline-delimited JSON. Human-readable diagnostics go to stderr. Always check the exit status. See [the JSON output contract](./JSON_OUTPUT.md) for response shapes, stream framing, and errors:
 
 ```bash
 # Get instance details as JSON
@@ -1213,7 +1228,21 @@ lim gradle run --env APP_ENV=staging -- npm run generate
 lim gradle build . --env APP_ENV=staging
 ```
 
-`--additional-file localPath=remotePath` adds a file outside the source tree; its remote path is relative to the workspace.
+`lim gradle build`, `sync`, and `run` accept `--additional-file localPath=remotePath`
+to add files outside the source tree. Repeat the flag for multiple files. Remote
+paths starting with `~/` target the sandbox home used by builds and tool commands;
+other paths are relative to the workspace.
+For private npm dependencies, copy an existing registry configuration:
+
+```bash
+lim gradle build . \
+  --additional-file "$HOME/.npmrc=~/.npmrc" \
+  --additional-file "$HOME/.netrc=~/.netrc"
+```
+
+Pass the flag on each sync that needs the file; omitting it removes the previously
+synced file. Home files are shared by projects on the instance. If the configuration references
+an environment variable, pass it with `--env` as well.
 
 `run` syncs the current directory first. Add `--no-sync` to use the existing
 remote workspace. Its optional positional directory is relative to that

package/bin/dev.js

@@ -9,8 +9,12 @@ require('ts-node').register({ project });
 const oclif = require('@oclif/core');
 
 oclif.settings.debug = true;
+process.env.NODE_ENV = 'development';
+const { handleJsonError } = require('./json-errors.cjs');
 
 oclif
-  .execute({ development: true, dir: __dirname, args: process.argv.slice(2) })
+  .run(process.argv.slice(2), __dirname)
   .then(oclif.flush)
-  .catch(oclif.Errors.handle);
+  .catch(async (error) => {
+    if (!(await handleJsonError(error))) return oclif.Errors.handle(error);
+  });

package/bin/json-errors.cjs

@@ -0,0 +1,35 @@
+// Keep parser and command errors machine-readable, including failures before flags are parsed.
+async function handleJsonError(error, argv = process.argv.slice(2)) {
+  const delimiter = argv.indexOf('--');
+  if (!argv.slice(0, delimiter < 0 ? argv.length : delimiter).includes('--json')) return false;
+  const exitCode = error?.oclif?.exit ?? error?.exitCode ?? 1;
+  process.exitCode = exitCode;
+  // Explicit exits follow an already-emitted execution result, or a successful early exit.
+  if (error?.code !== 'EEXIT') {
+    process.stderr.write(
+      JSON.stringify({
+        error: {
+          code: typeof error?.code === 'string' ? error.code : 'CLI_ERROR',
+          message: error instanceof Error ? error.message : String(error),
+          ...(typeof error?.status === 'number' ? { status: error.status } : {}),
+        },
+      }) + '\n',
+    );
+  }
+
+  // SDK sockets can outlive a failed command. Flush both streams before forcing exit,
+  // with the same ten-second flush budget as oclif for a stalled output consumer.
+  const deadline = setTimeout(() => process.exit(exitCode), 10_000);
+  deadline.unref();
+  try {
+    await Promise.all(
+      [process.stdout, process.stderr].map((stream) => new Promise((resolve) => stream.write('', resolve))),
+    );
+  } finally {
+    clearTimeout(deadline);
+    process.exit(exitCode);
+  }
+  return true;
+}
+
+module.exports = { handleJsonError };

package/bin/run.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+const { handleJsonError } = require('./json-errors.cjs');
+
 const { flush } = require('@oclif/core');
 const { Config } = require('@oclif/core/config');
 const { handle } = require('@oclif/core/errors');
@@ -36,6 +38,7 @@ async function inferCommandArgv(argv) {
 }
 
 async function handleError(error) {
+  if (await handleJsonError(error)) return;
   if (!isUsageError(error)) {
     await handle(error);
     return;

package/dist/base-command.d.ts

@@ -39,6 +39,7 @@ export declare abstract class BaseCommand extends Command {
     private _client?;
     protected get client(): Limrun;
     private _parsedFlags?;
+    protected snapshotProjectPath?: string;
     private _lastResolvedInstanceId?;
     private _lastResolvedExpectedType?;
     private _xcodeReplacementIntent?;
@@ -57,7 +58,11 @@ export declare abstract class BaseCommand extends Command {
     /** ` in this workspace (<key>)`, or empty when resolved to the shared global slot. */
     protected scopeSuffix(): string;
     protected info(message?: string): void;
+    log(message?: string, ...args: any[]): void;
     protected output(message?: string): void;
+    protected outputResult(data: unknown, message: string): void;
+    /** Streams use one complete JSON value per line, including embedded newlines. */
+    protected outputEvent(data: unknown): void;
     /** Adapter passed to the shared tunnel command flows in lib/tunnel-command. */
     protected tunnelCommandIO(): TunnelCommandIO;
     protected withAuth<T>(fn: () => Promise<T>, options?: {
@@ -97,8 +102,9 @@ export declare abstract class BaseCommand extends Command {
     private createAndroidInstance;
     /** Whether `id` is a server-side instance THIS invocation auto-created. */
     protected wasCreatedThisRun(id: string | undefined): boolean;
-    /** Build cache configuration from this command's flags, if it has any. */
+    /** Defaults apply only at creation; existing targets keep their snapshot configuration. */
     protected cacheConfigFromFlags(): XcodeCacheConfig | undefined;
+    protected buildSnapshotTip(instanceId: string): Promise<string>;
     /**
      * Blocks while a freshly created instance restores its cache, printing each phase as it
      * happens. A restore that fell back to a cold workspace just prints and returns, because the
@@ -149,7 +155,7 @@ export declare abstract class BaseCommand extends Command {
         status: Limrun.XcodeStatus;
     } | undefined>;
     /** Save the workspace preference and switch its existing sandbox when available. */
-    protected setPreferredXcodeVersion(version: string, providedId?: string): Promise<void>;
+    protected setPreferredXcodeVersion(version: string, providedId?: string, renderJson?: (result: unknown) => void): Promise<void>;
     /** setXcode with the daemon's own refusal message instead of the transport's wrapping. */
     protected selectXcode(xcodeClient: XcodeClient, version: string): Promise<XcodeSelectResult>;
     private readXcodeSelection;

package/dist/base-command.d.ts.map

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

package/dist/base-command.js

@@ -48,6 +48,7 @@ const api_2 = require("@limrun/api");
 const cache_1 = require("./lib/cache");
 const xcode_version_1 = require("./lib/xcode-version");
 const telemetry_1 = require("./lib/telemetry");
+const snapshot_project_1 = require("./lib/snapshot-project");
 const VERSION = require('../package.json').version;
 // Full instance-id shape only: prefix_region_suffix with a long TypeID suffix.
 // TypeIDs are lowercase, so no /i flag; this avoids matching bare prefix words
@@ -79,7 +80,12 @@ class BaseCommand extends core_1.Command {
             // A management call with the placeholder gets a 403 marked
             // "unauthenticated:", which withAuth turns into login guidance or a
             // re-login.
-            this._client = new api_1.default({ apiKey: apiKey || 'unauthenticated', baseURL });
+            this._client = new api_1.default({
+                apiKey: apiKey || 'unauthenticated',
+                baseURL,
+                userAgent: `lim/${VERSION}`,
+                ...(this.shouldSuppressInfo() ? { logLevel: 'warn' } : {}),
+            });
         }
         return this._client;
     }
@@ -133,8 +139,25 @@ class BaseCommand extends core_1.Command {
             super.log(message);
         }
     }
+    // Keep stdout machine-readable even if a human message bypasses info().
+    log(message = '', ...args) {
+        if (this.isJsonEnabled())
+            this.logToStderr(message, ...args);
+        else
+            super.log(message, ...args);
+    }
     output(message = '') {
-        super.log(message);
+        this.log(message);
+    }
+    outputResult(data, message) {
+        if (this.isJsonEnabled())
+            this.outputJson(data);
+        else
+            this.output(message);
+    }
+    /** Streams use one complete JSON value per line, including embedded newlines. */
+    outputEvent(data) {
+        super.log(JSON.stringify(data));
     }
     /** Adapter passed to the shared tunnel command flows in lib/tunnel-command. */
     tunnelCommandIO() {
@@ -225,14 +248,14 @@ class BaseCommand extends core_1.Command {
                 });
                 return obj;
             });
-            this.output(JSON.stringify(objects, null, 2));
+            this.outputJson(objects);
         }
         else {
             this.output((0, formatting_1.renderTable)(headers, rows));
         }
     }
     outputJson(data) {
-        this.output(JSON.stringify(data, null, 2));
+        super.log(JSON.stringify(data, null, 2));
     }
     /**
      * Runs the sibling `list` command (e.g. `ios:list` for `ios get`), forwarding
@@ -268,7 +291,11 @@ class BaseCommand extends core_1.Command {
     async resolveXcodeClient(target) {
         if (target.apiUrl && target.token) {
             try {
-                return await this.client.xcodeInstances.createClient({ apiUrl: target.apiUrl, token: target.token });
+                return await this.client.xcodeInstances.createClient({
+                    apiUrl: target.apiUrl,
+                    token: target.token,
+                    logLevel: this.shouldSuppressInfo() ? 'warn' : 'info',
+                });
             }
             catch (err) {
                 if (this.isCachedXcodeClientNotFound(err)) {
@@ -279,7 +306,10 @@ class BaseCommand extends core_1.Command {
         }
         const instance = await this.client.xcodeInstances.get(target.id);
         (0, config_1.registerCreatedInstance)(instance);
-        return this.client.xcodeInstances.createClient({ instance });
+        return this.client.xcodeInstances.createClient({
+            instance,
+            logLevel: this.shouldSuppressInfo() ? 'warn' : 'info',
+        });
     }
     tryResolveAndroidInstance(providedId) {
         this._lastResolvedExpectedType = 'android';
@@ -617,17 +647,42 @@ class BaseCommand extends core_1.Command {
     wasCreatedThisRun(id) {
         return !!id && this._instancesCreatedThisRun.has(id);
     }
-    /** Build cache configuration from this command's flags, if it has any. */
+    /** Defaults apply only at creation; existing targets keep their snapshot configuration. */
     cacheConfigFromFlags() {
         const flags = this.parsedFlags;
         if (!flags)
             return undefined;
         const asString = (name) => typeof flags[name] === 'string' ? flags[name] : undefined;
-        return (0, cache_1.parseSnapshotConfig)({
+        const explicit = {
+            'no-snapshot': flags['no-snapshot'] === true,
             'snapshot-key': asString('snapshot-key'),
             'snapshot-restore-keys': asString('snapshot-restore-keys'),
             'snapshot-paths': asString('snapshot-paths'),
-        });
+        };
+        const config = (0, snapshot_project_1.projectSnapshotConfig)(explicit, this.snapshotProjectPath ?? process.cwd());
+        if (!(0, cache_1.parseSnapshotConfig)(explicit) && !explicit['no-snapshot']) {
+            this.info(config?.key ?
+                `Disk snapshot key: ${config.key}`
+                : 'Could not derive a disk snapshot key from Git origin. Use --snapshot-key to enable snapshots.');
+        }
+        return config;
+    }
+    async buildSnapshotTip(instanceId) {
+        if (this.isJsonEnabled() || this.parsedFlags?.['no-snapshot'])
+            return '';
+        try {
+            const snapshot = await this.client.xcodeInstances.getCache(instanceId, {
+                timeout: 2000,
+                maxRetries: 0,
+            });
+            if (snapshot.config)
+                return '';
+        }
+        catch {
+            // Unknown snapshot state must not change the build result or suggest a redundant key.
+            return '';
+        }
+        return '\nTip: Use --snapshot-key <project-key> for disk snapshots to build under 60 seconds!';
     }
     /**
      * Blocks while a freshly created instance restores its cache, printing each phase as it
@@ -808,7 +863,7 @@ class BaseCommand extends core_1.Command {
         return status ? { target, client, status } : undefined;
     }
     /** Save the workspace preference and switch its existing sandbox when available. */
-    async setPreferredXcodeVersion(version, providedId) {
+    async setPreferredXcodeVersion(version, providedId, renderJson = (result) => this.outputJson(result)) {
         const previous = (0, config_1.loadXcodeVersionPreference)();
         // Keep the workspace preference on transient failures, but reject versions the node cannot provide.
         const record = () => {
@@ -840,13 +895,13 @@ class BaseCommand extends core_1.Command {
             record();
             if (!target || !result) {
                 if (this.isJsonEnabled())
-                    this.outputJson({ preferred: version });
+                    renderJson({ preferred: version });
                 else
                     this.output(`No sandbox instance found${this.scopeSuffix()}; the next one uses it.`);
                 return;
             }
             if (this.isJsonEnabled()) {
-                this.outputJson({ instanceId: target.id, preferred: version, ...result });
+                renderJson({ instanceId: target.id, preferred: version, ...result });
                 return;
             }
             const verb = result.alreadyBound ? 'already uses' : 'now uses';
@@ -1092,11 +1147,18 @@ class BaseCommand extends core_1.Command {
     }
     async resolveGradleClient(target) {
         if (target.apiUrl && target.token) {
-            return this.client.gradleInstances.createClient({ apiUrl: target.apiUrl, token: target.token });
+            return this.client.gradleInstances.createClient({
+                apiUrl: target.apiUrl,
+                token: target.token,
+                logLevel: this.shouldSuppressInfo() ? 'warn' : 'info',
+            });
         }
         const instance = await this.client.gradleInstances.get(target.id);
         (0, config_1.registerCreatedInstance)(instance);
-        return this.client.gradleInstances.createClient({ instance });
+        return this.client.gradleInstances.createClient({
+            instance,
+            logLevel: this.shouldSuppressInfo() ? 'warn' : 'info',
+        });
     }
     async resolveBuildToolClient(platform, id, mode = 'work') {
         if (platform === 'gradle') {
@@ -1132,7 +1194,7 @@ BaseCommand.baseFlags = {
         env: 'LIM_API_KEY',
     }),
     json: core_1.Flags.boolean({
-        description: 'Output structured JSON instead of human-readable tables or plain text when the command supports it.',
+        description: 'Output JSON for automation. Streams and watch modes emit newline-delimited JSON. Human-readable diagnostics go to stderr.',
         default: false,
     }),
     quiet: core_1.Flags.boolean({