disk 0.8.11 → 0.8.13

package/README.md

@@ -82,6 +82,80 @@ await archil.createApiKey({ name: "ci-bot", description: "GitHub Actions" });
 await archil.deleteApiKey("key-abc123");
 ```
 
+### Reading and writing objects
+
+A `Disk` doubles as an S3-compatible bucket: read, write, delete, and list its
+files by key without mounting it. These methods talk to Archil's S3 endpoint
+using your same API key (no separate S3 credentials or SigV4 signing on your
+part).
+
+```ts
+const d = await archil.getDisk("dsk-abc123");
+
+// Write — accepts a string, Uint8Array/Buffer, or ArrayBuffer. Returns the etag.
+const { etag } = await d.putObject("reports/2026-01/data.json", JSON.stringify(report), "application/json");
+
+// Read — returns the bytes (a Uint8Array).
+const bytes = await d.getObject("reports/2026-01/data.json");
+const text = new TextDecoder().decode(bytes);
+
+// Metadata / existence without downloading the body
+const meta = await d.headObject("reports/2026-01/data.json"); // null if absent
+if (await d.objectExists("reports/2026-01/data.json")) { /* … */ }
+
+// Delete (idempotent — deleting a missing key succeeds)
+await d.deleteObject("reports/2026-01/data.json");
+```
+
+`listObjects` auto-paginates by default, returning every matching key. The first
+argument is a key prefix; a non-recursive listing (the default) returns the
+immediate level as `objects` plus subdirectory `commonPrefixes`:
+
+```ts
+const { objects, commonPrefixes } = await d.listObjects("reports/");      // one level
+const all = await d.listObjects("reports/", { recursive: true });          // whole subtree
+const first100 = await d.listObjects("reports/", { limit: 100 });          // cap the total
+
+// Stream pages instead of buffering everything (large listings):
+for await (const page of d.listObjectsPages("reports/")) {
+  for (const obj of page.objects) console.log(obj.key, obj.size, obj.lastModified);
+}
+
+// Or drive pagination yourself:
+const page = await d.listObjects("reports/", { singlePage: true });
+if (page.isTruncated) {
+  const next = await d.listObjects("reports/", { singlePage: true, continuationToken: page.nextContinuationToken });
+}
+```
+
+Failures throw `ArchilS3Error` with `status` (HTTP status), `code` (the S3 error
+code, e.g. `"NoSuchKey"`), `requestId`, and the raw body on `raw`. `getObject`
+on a missing key throws a 404 — use `headObject`/`objectExists` to probe without
+catching. All SDK errors extend `ArchilError`, so `catch (e) { if (e instanceof
+ArchilError) … }` handles control-plane and S3 failures uniformly.
+
+The S3 endpoint is derived from your region automatically. To target a custom
+environment, set `s3BaseUrl` on the `Archil` constructor (or the
+`ARCHIL_S3_BASE_URL` env var).
+
+### Sharing files
+
+`share` mints a signed, time-limited link to a single file. Anyone with the link
+can download that file — no API key, no mounting. The link carries a
+cryptographically signed token (disk + key + expiry); when it expires it stops
+working.
+
+```ts
+const d = await archil.getDisk("dsk-abc123");
+
+// Default lifetime is 24 hours.
+const { url, expiresIn } = await d.share("reports/2026-01/summary.pdf");
+console.log(url); // https://control.…/api/shared/<token>
+
+// Set the lifetime in seconds (any positive integer, up to 604800 = 7 days):
+const weekLink = await d.share("reports/2026-01/summary.pdf", { expiresIn: 604800 });
+```
+
 ### Named imports
 
 If you prefer named imports over the namespace style, they work the same way:

package/dist/cli.js

@@ -1,23 +1,83 @@
 #!/usr/bin/env node
 
 // bin/cli.ts
-import { createRequire as createRequire2 } from "module";
+import { createRequire } from "module";
 import { Command, Option } from "commander";
 
 // src/client.ts
-import createClient from "openapi-fetch";
+import createClientDefault from "openapi-fetch";
+
+// src/s3xml.ts
+import { XMLParser } from "fast-xml-parser";
+var parser = new XMLParser({
+  isArray: (name) => name === "Contents" || name === "CommonPrefixes",
+  parseTagValue: false,
+  trimValues: true,
+  ignoreAttributes: true
+});
+function parseXml(xml) {
+  if (!xml.trim()) return {};
+  return parser.parse(xml);
+}
 
 // src/errors.ts
-var ArchilApiError = class extends Error {
+var ArchilError = class extends Error {
+  /** HTTP status code associated with the failure. */
   status;
+  /** Machine-readable error code (e.g. an S3 code like "NoSuchKey"), if known. */
   code;
   constructor(message, status, code) {
     super(message);
-    this.name = "ArchilApiError";
+    this.name = "ArchilError";
     this.status = status;
     this.code = code;
   }
 };
+var ArchilApiError = class extends ArchilError {
+  constructor(message, status, code) {
+    super(message, status, code);
+    this.name = "ArchilApiError";
+  }
+};
+var ArchilS3Error = class extends ArchilError {
+  /** S3 request id, if the gateway returned one. */
+  requestId;
+  /** Raw response body (the XML document), for debugging. */
+  raw;
+  constructor(opts) {
+    const detail = opts.message ?? opts.statusText ?? "";
+    const codePart = opts.code ? ` ${opts.code}` : "";
+    super(
+      `S3 ${opts.operation} failed: ${opts.statusCode}${codePart}${detail ? ` \u2014 ${detail}` : ""}`,
+      opts.statusCode,
+      opts.code
+    );
+    this.name = "ArchilS3Error";
+    this.requestId = opts.requestId;
+    this.raw = opts.raw;
+  }
+};
+function tagString(obj, tag) {
+  const value = obj[tag];
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+function parseS3Error(operation, statusCode, statusText, body) {
+  let err = {};
+  try {
+    err = parseXml(body).Error ?? {};
+  } catch {
+    err = {};
+  }
+  return new ArchilS3Error({
+    operation,
+    statusCode,
+    statusText,
+    code: tagString(err, "Code"),
+    message: tagString(err, "Message"),
+    requestId: tagString(err, "RequestId"),
+    raw: body
+  });
+}
 
 // src/regions.ts
 var REGION_URLS = {
@@ -35,14 +95,32 @@ function resolveBaseUrl(region) {
   }
   return url;
 }
+function deriveS3BaseUrl(controlBaseUrl) {
+  try {
+    const u = new URL(controlBaseUrl);
+    u.hostname = u.hostname.replace(/^control\./, "s3.");
+    return u.toString().replace(/\/$/, "");
+  } catch {
+    return void 0;
+  }
+}
+
+// src/version.ts
+var VERSION = true ? "0.8.13" : "0.0.0-dev";
+var USER_AGENT = `archil-js/${VERSION}`;
 
 // src/client.ts
+var createClient = typeof createClientDefault === "function" ? createClientDefault : createClientDefault.default;
 function createApiClient(opts) {
   const baseUrl = opts.baseUrl ?? resolveBaseUrl(opts.region);
   return createClient({
     baseUrl,
     headers: {
-      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`
+      Authorization: `key-${opts.apiKey.replace(/^key-/, "")}`,
+      // Identifies the JS SDK (and its version) to the control plane. Honored
+      // by Node's fetch; browsers treat User-Agent as a forbidden header and
+      // drop it, which is fine — the SDK's primary use is server-side.
+      "User-Agent": USER_AGENT
     }
   });
 }
@@ -81,8 +159,6 @@ async function unwrapEmpty(promise) {
 }
 
 // src/disk.ts
-import { createRequire } from "module";
-import { pathToFileURL } from "url";
 var Disk = class {
   id;
   name;
@@ -104,8 +180,10 @@ var Disk = class {
   _client;
   /** @internal */
   _archilRegion;
+  /** Base URL for the S3-compatible API (port 9000 ingress). Empty if unset. */
+  _s3BaseUrl;
   /** @internal */
-  constructor(data, client, archilRegion) {
+  constructor(data, client, archilRegion, s3BaseUrl) {
     this.id = data.id;
     this.name = data.name;
     this.organization = data.organization;
@@ -124,6 +202,7 @@ var Disk = class {
     this.allowedIps = data.allowedIps;
     this._client = client;
     this._archilRegion = archilRegion;
+    this._s3BaseUrl = s3BaseUrl ?? "";
   }
   toJSON() {
     return {
@@ -223,6 +302,244 @@ var Disk = class {
       })
     );
   }
+  /**
+   * Constant-time parallel grep across files on this disk. Listing and
+   * matching are fanned out across ephemeral exec containers; the request
+   * finishes within the supplied time budget regardless of dataset size.
+   *
+   * The returned `stoppedReason` says whether the search ran to completion
+   * or short-circuited on `maxResults` / `maxDurationSeconds`. When
+   * stopping early, the matches returned are a sample (whichever workers
+   * reported first), not the lexicographically first N.
+   */
+  async grep(opts) {
+    return unwrap(
+      this._client.POST("/api/disks/{id}/grep", {
+        params: { path: { id: this.id } },
+        body: {
+          directory: opts.directory,
+          pattern: opts.pattern,
+          recursive: opts.recursive ?? false,
+          maxDurationSeconds: opts.maxDurationSeconds ?? 30,
+          concurrency: opts.concurrency ?? 50,
+          maxResults: opts.maxResults ?? 1e3
+        }
+      })
+    );
+  }
+  /**
+   * Create a signed, time-limited URL that lets anyone download a single file
+   * from this disk without authentication. The returned URL embeds a
+   * cryptographically signed token carrying the disk, the file's key, and an
+   * expiry — share it directly; no API key is needed to redeem it.
+   *
+   * @param key   Path to the file on the disk (e.g. "reports/2026-01/data.pdf").
+   * @param opts  `expiresIn` sets the URL lifetime in seconds (any positive
+   *              integer, max 604800 = 7 days). Defaults to 24h.
+   */
+  async share(key, opts = {}) {
+    const body = { key };
+    if (opts.expiresIn !== void 0) body.expiresIn = opts.expiresIn;
+    const call = this._client.POST;
+    return unwrap(call(`/api/disks/${this.id}/share`, { body }));
+  }
+  /**
+   * Read an object from the disk via the S3-compatible GetObject API and return
+   * its full contents as bytes. Throws `ArchilS3Error` if the object does not
+   * exist (status 404, code "NoSuchKey") or the request is rejected; use
+   * `headObject`/`objectExists` to check existence without throwing.
+   *
+   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+   */
+  async getObject(key) {
+    const resp = await this._s3Request("GET", key);
+    if (!resp.ok) {
+      throw parseS3Error("GetObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return resp.body;
+  }
+  /**
+   * Fetch an object's metadata (size, etag, content type, last-modified) without
+   * downloading its contents, via the S3-compatible HeadObject API. Returns
+   * `null` if the object does not exist.
+   *
+   * @param key  Path on the disk (e.g. "reports/2026-01/data.json")
+   */
+  async headObject(key) {
+    const resp = await this._s3Request("HEAD", key);
+    if (resp.status === 404) return null;
+    if (!resp.ok) {
+      throw parseS3Error("HeadObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    const lastModified = resp.headers.get("last-modified");
+    return {
+      size: Number(resp.headers.get("content-length") ?? 0),
+      etag: resp.headers.get("etag") ?? void 0,
+      contentType: resp.headers.get("content-type") ?? void 0,
+      lastModified: lastModified ? new Date(lastModified) : void 0
+    };
+  }
+  /** Whether an object exists on the disk (a HeadObject that maps 404 → false). */
+  async objectExists(key) {
+    return await this.headObject(key) !== null;
+  }
+  /**
+   * Write an object to the disk using the S3-compatible PutObject API. Faster
+   * than exec for large files — no container overhead, no command-length limits.
+   * Returns the entity tag the server assigned.
+   *
+   * @param key          Path on the disk (e.g. "reports/2026-01/data.json")
+   * @param body         Contents as a string, Uint8Array/Buffer, or ArrayBuffer
+   * @param contentType  MIME type (default: "application/octet-stream")
+   */
+  async putObject(key, body, contentType = "application/octet-stream") {
+    const resp = await this._s3Request("PUT", key, { body, contentType });
+    if (!resp.ok) {
+      throw parseS3Error("PutObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return { etag: resp.headers.get("etag") ?? void 0 };
+  }
+  /**
+   * Delete an object from the disk via the S3-compatible DeleteObject API.
+   * Idempotent: deleting a key that doesn't exist resolves successfully, per
+   * S3 semantics.
+   *
+   * @param key  Path on the disk (e.g. "project/dist/server.cjs")
+   */
+  async deleteObject(key) {
+    const resp = await this._s3Request("DELETE", key);
+    if (!resp.ok && resp.status !== 404) {
+      throw parseS3Error("DeleteObject", resp.status, resp.statusText, decodeText(resp.body));
+    }
+  }
+  /**
+   * List objects on the disk via the S3-compatible ListObjectsV2 API. By
+   * default this follows continuation tokens until the listing is exhausted and
+   * returns every matching key. Use `limit` to cap the total, `singlePage` for a
+   * single request, or {@link listObjectsPages} to stream pages without loading
+   * everything into memory.
+   *
+   * @param prefix  Only return keys beginning with this prefix (omit for all).
+   * @param opts    Listing and pagination options.
+   */
+  async listObjects(prefix, opts = {}) {
+    if (opts.singlePage) {
+      return this._listObjectsPage(prefix, opts);
+    }
+    const objects = [];
+    const commonPrefixes = [];
+    const seenPrefixes = /* @__PURE__ */ new Set();
+    let echoedPrefix;
+    let truncated = false;
+    outer: for await (const page of this.listObjectsPages(prefix, opts)) {
+      echoedPrefix = page.prefix;
+      for (const cp of page.commonPrefixes) {
+        if (!seenPrefixes.has(cp)) {
+          seenPrefixes.add(cp);
+          commonPrefixes.push(cp);
+        }
+      }
+      for (const obj of page.objects) {
+        if (opts.limit !== void 0 && objects.length >= opts.limit) {
+          truncated = true;
+          break outer;
+        }
+        objects.push(obj);
+      }
+    }
+    return { objects, commonPrefixes, isTruncated: truncated, keyCount: objects.length, prefix: echoedPrefix };
+  }
+  /**
+   * Yield ListObjectsV2 pages lazily, following continuation tokens. A
+   * memory-friendly way to process a large listing without materializing it:
+   *
+   * ```ts
+   * for await (const page of disk.listObjectsPages("logs/")) {
+   *   for (const obj of page.objects) process(obj);
+   * }
+   * ```
+   *
+   * @param prefix  Only return keys beginning with this prefix (omit for all).
+   * @param opts    Listing options (`limit` / `singlePage` are ignored here —
+   *                control your own loop).
+   */
+  async *listObjectsPages(prefix, opts = {}) {
+    const seenTokens = /* @__PURE__ */ new Set();
+    let continuationToken = opts.continuationToken;
+    for (; ; ) {
+      const page = await this._listObjectsPage(prefix, { ...opts, continuationToken });
+      yield page;
+      const next = page.isTruncated ? page.nextContinuationToken : void 0;
+      if (!next || seenTokens.has(next)) break;
+      seenTokens.add(next);
+      continuationToken = next;
+    }
+  }
+  /** Fetch a single ListObjectsV2 page. @internal */
+  async _listObjectsPage(prefix, opts) {
+    const query = { "list-type": 2 };
+    if (prefix !== void 0) query.prefix = prefix;
+    if (!opts.recursive) query.delimiter = "/";
+    if (opts.continuationToken !== void 0) query["continuation-token"] = opts.continuationToken;
+    if (opts.startAfter !== void 0) query["start-after"] = opts.startAfter;
+    const resp = await this._s3Request("GET", "", { query });
+    if (!resp.ok) {
+      throw parseS3Error("ListObjectsV2", resp.status, resp.statusText, decodeText(resp.body));
+    }
+    return parseListObjectsResult(decodeText(resp.body));
+  }
+  /**
+   * Send a single request to the disk's S3-compatible endpoint. This reuses the
+   * control-plane client purely for its credential and transport — the same
+   * `Authorization` header is sent and verified by the same code server-side —
+   * pointed at the S3 host. Returns the response status and fully-buffered body
+   * so callers can inspect both regardless of the verb used.
+   *
+   * The S3 routes (`/{diskId}/{key}` for objects, `/{diskId}` for the bucket)
+   * are not part of the typed control-plane API, so the path and per-request
+   * options are passed untyped. An empty `key` targets the bucket itself (used
+   * by listObjects).
+   *
+   * @internal
+   */
+  async _s3Request(method, key, opts = {}) {
+    if (!this._s3BaseUrl) {
+      throw new Error(
+        "S3 base URL not configured. Pass s3BaseUrl to new Archil({...}) or set ARCHIL_S3_BASE_URL."
+      );
+    }
+    const call = this._client[method];
+    const trimmedKey = key.replace(/^\//, "");
+    const encodedKey = trimmedKey.split("/").map(encodeURIComponent).join("/");
+    const path = encodedKey ? `/${this.id}/${encodedKey}` : `/${this.id}`;
+    const { error, response } = await call(path, {
+      baseUrl: this._s3BaseUrl,
+      parseAs: "stream",
+      ...opts.query ? { params: { query: opts.query } } : {},
+      // fetch accepts string / Uint8Array / ArrayBuffer bodies directly; pass it
+      // through unchanged (no Node Buffer in the data path).
+      ...opts.body !== void 0 ? { body: opts.body, bodySerializer: (b) => b } : {},
+      ...opts.contentType ? { headers: { "Content-Type": opts.contentType } } : {}
+    });
+    if (!response.ok) {
+      const message = typeof error === "string" ? error : error ? JSON.stringify(error) : "";
+      return {
+        ok: false,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        body: new TextEncoder().encode(message)
+      };
+    }
+    const bytes = method === "GET" ? new Uint8Array(await response.arrayBuffer()) : new Uint8Array(0);
+    return {
+      ok: true,
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+      body: bytes
+    };
+  }
   /**
    * Connect to this disk's data plane via the native ArchilClient.
    *
@@ -231,13 +548,15 @@ var Disk = class {
   async mount(opts) {
     let ArchilClient;
     try {
-      const base = typeof import.meta !== "undefined" && import.meta.url ? import.meta.url : pathToFileURL(__filename).href;
-      const nativeRequire = createRequire(base);
-      const native = nativeRequire("@archildata/native");
-      ArchilClient = native.ArchilClient;
+      const nativeSpecifier = "@archildata/native";
+      const native = await import(nativeSpecifier);
+      ArchilClient = native.ArchilClient ?? native.default?.ArchilClient;
+      if (!ArchilClient) {
+        throw new Error("@archildata/native did not export ArchilClient");
+      }
     } catch {
       throw new Error(
-        "Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly."
+        "Native client not available. Install @archildata/native (platform-specific binary) or use ArchilClient.connect() directly. mount() is not supported in browsers."
       );
     }
     return ArchilClient.connect({
@@ -250,6 +569,34 @@ var Disk = class {
     });
   }
 };
+function optionalString(value) {
+  return value === void 0 || value === null ? void 0 : String(value);
+}
+function optionalDate(value) {
+  return value === void 0 || value === null ? void 0 : new Date(String(value));
+}
+function decodeText(bytes) {
+  return new TextDecoder().decode(bytes);
+}
+function parseListObjectsResult(xml) {
+  const root = parseXml(xml).ListBucketResult ?? {};
+  const contents = root.Contents ?? [];
+  const objects = contents.map((c) => ({
+    key: String(c.Key ?? ""),
+    size: Number(c.Size ?? 0),
+    etag: optionalString(c.ETag),
+    lastModified: optionalDate(c.LastModified)
+  }));
+  const commonPrefixes = (root.CommonPrefixes ?? []).map((cp) => optionalString(cp.Prefix)).filter((p) => p !== void 0);
+  return {
+    objects,
+    commonPrefixes,
+    isTruncated: root.IsTruncated === "true" || root.IsTruncated === true,
+    nextContinuationToken: optionalString(root.NextContinuationToken),
+    keyCount: root.KeyCount !== void 0 ? Number(root.KeyCount) : objects.length,
+    prefix: optionalString(root.Prefix)
+  };
+}
 
 // src/disks.ts
 var Disks = class {
@@ -258,9 +605,12 @@ var Disks = class {
   /** @internal */
   _region;
   /** @internal */
-  constructor(client, region) {
+  _s3BaseUrl;
+  /** @internal */
+  constructor(client, region, s3BaseUrl) {
     this._client = client;
     this._region = region;
+    this._s3BaseUrl = s3BaseUrl;
   }
   async list(opts) {
     const data = await unwrap(
@@ -269,7 +619,7 @@ var Disks = class {
       })
     );
     return data.map(
-      (d) => new Disk(d, this._client, this._region)
+      (d) => new Disk(d, this._client, this._region, this._s3BaseUrl)
     );
   }
   async get(id) {
@@ -278,7 +628,7 @@ var Disks = class {
         params: { path: { id } }
       })
     );
-    return new Disk(data, this._client, this._region);
+    return new Disk(data, this._client, this._region, this._s3BaseUrl);
   }
   /**
    * Create a new disk with an auto-generated mount token.
@@ -338,6 +688,9 @@ var Tokens = class {
 };
 
 // src/archil.ts
+function envVar(name) {
+  return typeof process !== "undefined" && process.env ? process.env[name] : void 0;
+}
 function isExecMountSpec(m) {
   return typeof m === "object" && m !== null && "disk" in m;
 }
@@ -350,21 +703,23 @@ var Archil = class {
   /** @internal */
   _client;
   constructor(opts = {}) {
-    const apiKey = opts.apiKey ?? process.env.ARCHIL_API_KEY;
-    const region = opts.region ?? process.env.ARCHIL_REGION;
+    const apiKey = opts.apiKey ?? envVar("ARCHIL_API_KEY");
+    const region = opts.region ?? envVar("ARCHIL_REGION");
     if (!apiKey) {
       throw new Error("Missing API key: pass apiKey in options or set ARCHIL_API_KEY environment variable");
     }
     if (!region) {
       throw new Error("Missing region: pass region in options or set ARCHIL_REGION environment variable");
     }
+    const controlBaseUrl = opts.baseUrl ?? resolveBaseUrl(region);
     const client = createApiClient({
       apiKey,
       region,
-      baseUrl: opts.baseUrl
+      baseUrl: controlBaseUrl
     });
+    const s3BaseUrl = opts.s3BaseUrl ?? envVar("ARCHIL_S3_BASE_URL") ?? deriveS3BaseUrl(controlBaseUrl);
     this._client = client;
-    this.disks = new Disks(client, region);
+    this.disks = new Disks(client, region, s3BaseUrl);
     this.tokens = new Tokens(client);
   }
   /**
@@ -427,7 +782,7 @@ function deleteApiKey(id) {
 }
 
 // bin/cli.ts
-var pkg = createRequire2(import.meta.url)("../package.json");
+var pkg = createRequire(import.meta.url)("../package.json");
 var program = new Command();
 program.name("disk").description("Manage Archil disks from the command line").version(pkg.version).addOption(new Option("-k, --api-key <key>", "Archil API key").env("ARCHIL_API_KEY")).addOption(new Option("-r, --region <region>", "Archil region").env("ARCHIL_REGION")).addOption(new Option("--base-url <url>", "Override control-plane base URL")).hook("preAction", () => {
   const opts = program.opts();
@@ -607,6 +962,44 @@ program.command("exec <id|name> <command...>").description("Run a command in a c
     fail(err);
   }
 });
+program.command("grep <pattern> <target>").description(
+  "Constant-time parallel server-side grep across a disk. <target> is <id|name>[/<path>] \u2014 the path after the first '/' is the directory to search (defaults to the disk root). Accepts a disk id or name."
+).option("--no-recursive", "Search only the given directory, not its subdirectories (recursive is the default)").option("--max-duration <seconds>", "Wall-clock deadline for the whole search", (v) => parseInt(v, 10)).option("--concurrency <n>", "Max parallel grep workers (clamped to fleet capacity)", (v) => parseInt(v, 10)).option("--max-results <n>", "Stop once this many matches are collected", (v) => parseInt(v, 10)).option("-o, --output <format>", "Output format: text | json", "text").action(
+  async (pattern, target, opts) => {
+    try {
+      const slash = target.indexOf("/");
+      const idOrName = slash === -1 ? target : target.slice(0, slash);
+      const directory = slash === -1 ? "" : target.slice(slash + 1);
+      const d = await resolveDisk(idOrName);
+      const res = await d.grep({
+        directory,
+        pattern,
+        recursive: opts.recursive !== false,
+        maxDurationSeconds: opts.maxDuration,
+        concurrency: opts.concurrency,
+        maxResults: opts.maxResults
+      });
+      if (opts.output === "json") {
+        console.log(JSON.stringify(res, null, 2));
+      } else {
+        for (const m of res.matches) {
+          console.log(`${m.file}:${m.line}:${m.text}`);
+        }
+        console.error(
+          `${res.matches.length} match${res.matches.length === 1 ? "" : "es"} \xB7 ${res.filesScanned} files scanned \xB7 ${res.containersDispatched} containers \xB7 ${res.durationMs}ms \xB7 ${res.stoppedReason}`
+        );
+        if (res.stoppedReason !== "completed") {
+          console.error(
+            `warning: search did not complete (${res.stoppedReason}); results may be partial`
+          );
+        }
+      }
+      process.exit(res.matches.length > 0 ? 0 : 1);
+    } catch (err) {
+      fail(err);
+    }
+  }
+);
 var keys = program.command("api-keys").description("Manage Archil API keys (account-level credentials)");
 keys.command("list").description("List API keys").option("--limit <n>", "Maximum number of keys to return", (v) => parseInt(v, 10)).action(async (opts) => {
   try {
@@ -644,7 +1037,7 @@ keys.command("delete <id>").description("Delete an API key").action(async (id) =
   }
 });
 function rewriteSugar(argv) {
-  const known = /* @__PURE__ */ new Set(["list", "get", "create", "delete", "exec", "api-keys", "help", "--help", "-h", "--version", "-V"]);
+  const known = /* @__PURE__ */ new Set(["list", "get", "create", "delete", "exec", "grep", "api-keys", "help", "--help", "-h", "--version", "-V"]);
   const head = argv[2];
   const next = argv[3];
   if (head && next === "exec" && !known.has(head) && !head.startsWith("-")) {