From 96509372712f472a75ebbd1691e8478ce1bcb7bb Mon Sep 17 00:00:00 2001
From: AdaAibaby <shaolila@buaa.edu.cn>
Date: Mon, 7 Sep 2026 20:19:47 +0800
Subject: [PATCH] feat(cli): add `template rebuild --refresh-envd`

Old templates bake an old envd into their final snapshot, so a sandbox started
from one resumes the old envd and can't use features gated on a newer envd
(e.g. volume mounts need envd >= 0.5.14). The only fix is a rebuild, which users
have been scripting by hand against the raw API -- easy to get wrong (specs
silently drop to 2 vCPU / 1024 MiB, alias orphaned under a fresh template id).

Add `e2b template rebuild <template> --refresh-envd`: one command that calls the
companion server endpoint, which derives a new build FROM the template's own
latest ready build (base layer cached, only the envd binary swapped) and
inherits the source specs and alias in place. Streams build logs until ready.

The command is CLI-only (raw endpoint via client.api + the public
Template.getBuildStatus for polling), so no js/python SDK public-surface change
and no parity burden.

Preview note: spec/openapi.yml and packages/js-sdk/src/api/schema.gen.ts carry
the new endpoint so this compiles, but spec/ is normally synced from
e2b-dev/infra via Copybara. Once the companion endpoint (e2b-dev/infra#3624)
merges, bump spec/infra-ref and re-run `make codegen` -- that regenerates these
two files identically and the manual preview drops out.

Signed-off-by: AdaAibaby <shaolila@buaa.edu.cn>
---
 .changeset/template-rebuild-refresh-envd.md   |   5 +
 packages/cli/src/commands/template/index.ts   |   2 +
 packages/cli/src/commands/template/rebuild.ts | 101 ++++++++++++++++++
 .../tests/commands/template/rebuild.test.ts   |  36 +++++++
 packages/js-sdk/src/api/schema.gen.ts         |  61 +++++++++++
 spec/openapi.yml                              |  56 ++++++++++
 6 files changed, 261 insertions(+)
 create mode 100644 .changeset/template-rebuild-refresh-envd.md
 create mode 100644 packages/cli/src/commands/template/rebuild.ts
 create mode 100644 packages/cli/tests/commands/template/rebuild.test.ts

diff --git a/.changeset/template-rebuild-refresh-envd.md b/.changeset/template-rebuild-refresh-envd.md
new file mode 100644
index 0000000000..4d713e7d56
--- /dev/null
+++ b/.changeset/template-rebuild-refresh-envd.md
@@ -0,0 +1,5 @@
+---
+'@e2b/cli': minor
+---
+
+Add `e2b template rebuild <template> --refresh-envd`: rebuild an existing template with the host's current envd while keeping its specs and alias. Old templates bake an old envd into their snapshot, which blocks features gated on a newer envd (e.g. volume mounts need envd >= 0.5.14); this rebuilds in place FROM the template's own latest ready build so only the envd binary is swapped. Streams build logs until the new build is ready. Requires the companion `POST /v2/templates/{templateID}/refresh-envd` endpoint (e2b-dev/infra#3624).
diff --git a/packages/cli/src/commands/template/index.ts b/packages/cli/src/commands/template/index.ts
index fc8d336f2f..0942a4784d 100644
--- a/packages/cli/src/commands/template/index.ts
+++ b/packages/cli/src/commands/template/index.ts
@@ -7,6 +7,7 @@ import { initCommand } from './init'
 import { listCommand } from './list'
 import { migrateCommand } from './migrate'
 import { publishCommand, unPublishCommand } from './publish'
+import { rebuildCommand } from './rebuild'
 
 export const templateCommand = new commander.Command('template')
   .description('manage sandbox templates')
@@ -19,3 +20,4 @@ export const templateCommand = new commander.Command('template')
   .addCommand(publishCommand)
   .addCommand(unPublishCommand)
   .addCommand(migrateCommand)
+  .addCommand(rebuildCommand)
diff --git a/packages/cli/src/commands/template/rebuild.ts b/packages/cli/src/commands/template/rebuild.ts
new file mode 100644
index 0000000000..4bbd7277ec
--- /dev/null
+++ b/packages/cli/src/commands/template/rebuild.ts
@@ -0,0 +1,101 @@
+import * as commander from 'commander'
+import { defaultBuildLogger, Template } from 'e2b'
+
+import { client, ensureAPIKey } from 'src/api'
+import { handleE2BRequestError } from '../../utils/errors'
+import {
+  asBold,
+  asFormattedError,
+  asLocal,
+  asPrimary,
+} from '../../utils/format'
+
+const buildStatusPollFrequencyMs = 2_000
+
+/**
+ * Rebuild a template with the host's current envd. This calls the server-side
+ * refresh-envd endpoint, which derives a new build FROM the template's own
+ * latest ready build (base layer cached, only the envd binary swapped) and
+ * inherits the source build's specs and alias in place. Then it streams build
+ * logs until the new build is ready.
+ */
+async function refreshEnvd(templateID: string) {
+  ensureAPIKey()
+
+  const res = await client.api.POST('/v2/templates/{templateID}/refresh-envd', {
+    params: { path: { templateID } },
+  })
+  handleE2BRequestError(res, 'Error requesting envd refresh')
+
+  const { buildID, fromEnvdVersion, aliases } = res.data
+  const name = aliases && aliases.length > 0 ? aliases[0] : templateID
+
+  console.log(
+    `\nRefreshing envd for ${asBold(name)} (from v${fromEnvdVersion}); rebuilding...\n`
+  )
+
+  const onLog = defaultBuildLogger()
+  let logsOffset = 0
+  // Poll the existing build status endpoint until the derived build settles.
+  // The status endpoint returns at most 100 log entries per call, so keep
+  // draining after a terminal status before deciding the outcome.
+  for (;;) {
+    const status = await Template.getBuildStatus(
+      { templateId: templateID, buildId: buildID },
+      { logsOffset }
+    )
+    logsOffset += status.logEntries.length
+    status.logEntries.forEach(onLog)
+
+    if (status.status === 'ready') {
+      if (status.logEntries.length > 0) continue
+      break
+    }
+    if (status.status === 'error') {
+      if (status.logEntries.length > 0) continue
+      console.error(
+        asFormattedError(status.reason?.message ?? 'Template build failed')
+      )
+      process.exit(1)
+    }
+
+    await new Promise((r) => setTimeout(r, buildStatusPollFrequencyMs))
+  }
+
+  console.log(
+    `\n✅ ${asBold(name)} rebuilt with the current envd.\n\n   Confirm the binary changed: start a sandbox from ${asLocal(
+      name
+    )}, then run ${asPrimary('/usr/bin/envd -version')}.`
+  )
+}
+
+export const rebuildCommand = new commander.Command('rebuild')
+  .description(
+    'rebuild a template with the current envd, keeping its specs and alias. Useful for old templates whose baked-in envd is too old for newer features (e.g. volume mounts need envd >= 0.5.14).'
+  )
+  .argument(
+    '<template>',
+    'template id or alias to rebuild. Its specs and alias are inherited from the latest ready build.'
+  )
+  .option(
+    '--refresh-envd',
+    "swap in the host's current envd binary (the only rebuild mode today; required)."
+  )
+  .alias('rb')
+  .action(async (template: string, opts: { refreshEnvd?: boolean }) => {
+    if (!opts.refreshEnvd) {
+      console.error(
+        `Nothing to rebuild. Pass ${asBold(
+          '--refresh-envd'
+        )} to rebuild the template with the current envd.`
+      )
+      process.exit(1)
+    }
+
+    try {
+      await refreshEnvd(template)
+    } catch (err: any) {
+      console.error(asFormattedError(err.message))
+      process.exit(1)
+    }
+  })
diff --git a/packages/cli/tests/commands/template/rebuild.test.ts b/packages/cli/tests/commands/template/rebuild.test.ts
new file mode 100644
index 0000000000..aa7287b91e
--- /dev/null
+++ b/packages/cli/tests/commands/template/rebuild.test.ts
@@ -0,0 +1,36 @@
+import * as path from 'path'
+import { execSync } from 'child_process'
+import { describe, expect, test } from 'vitest'
+
+// Black-box CLI tests (same idiom as publish.test.ts): run the built binary and
+// assert on output up to the network boundary. The --refresh-envd guard and the
+// command registration are deterministic and need no API key or network.
+describe('template rebuild', () => {
+  const cliPath = path.join(process.cwd(), 'dist', 'index.js')
+
+  function run(args: string): string {
+    try {
+      return execSync(`node "${cliPath}" ${args} 2>&1`, {
+        encoding: 'utf-8',
+        stdio: 'pipe',
+        timeout: 10_000,
+      })
+    } catch (err: any) {
+      return (err?.stdout ?? '') + (err?.stderr ?? '')
+    }
+  }
+
+  test('without --refresh-envd it refuses and points at the flag', () => {
+    const output = run('template rebuild some-template')
+    expect(output).toContain('--refresh-envd')
+    expect(output).not.toContain('Refreshing envd')
+  })
+
+  test('is registered and documented under template help', () => {
+    const output = run('template rebuild --help')
+    expect(output).toContain('rebuild')
+    expect(output).toContain('--refresh-envd')
+    // The description explains the old-envd motivation.
+    expect(output).toContain('envd')
+  })
+})
diff --git a/packages/js-sdk/src/api/schema.gen.ts b/packages/js-sdk/src/api/schema.gen.ts
index 4ebca8c6cd..0800be7c81 100644
--- a/packages/js-sdk/src/api/schema.gen.ts
+++ b/packages/js-sdk/src/api/schema.gen.ts
@@ -1731,6 +1731,57 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v2/templates/{templateID}/refresh-envd": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Rebuild a template with the current envd
+         * @description Derives a new build of the template FROM the template's own latest ready
+         *     build, forcing the host's current envd binary to replace the one baked in
+         *     by the original build. Specs (cpu, memory) and the alias are inherited
+         *     from the source build. Returns the new build to poll via the existing
+         *     build status/logs endpoints.
+         *
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    templateID: components["parameters"]["templateID"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The refresh build was requested successfully */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["TemplateRefreshEnvdResponse"];
+                    };
+                };
+                400: components["responses"]["400"];
+                401: components["responses"]["401"];
+                403: components["responses"]["403"];
+                404: components["responses"]["404"];
+                500: components["responses"]["500"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v3/templates": {
         parameters: {
             query?: never;
@@ -2985,6 +3036,16 @@ export interface components {
              */
             updatedAt: string;
         };
+        TemplateRefreshEnvdResponse: {
+            /** @description Aliases of the template (inherited from the source) */
+            aliases?: string[];
+            /** @description Identifier of the new build; poll its status/logs endpoints */
+            buildID: string;
+            /** @description envd version the source build was baked with */
+            fromEnvdVersion: string;
+            /** @description Identifier of the template being refreshed */
+            templateID: string;
+        };
         TemplateRequestResponseV3: {
             /**
              * @deprecated
diff --git a/spec/openapi.yml b/spec/openapi.yml
index bb2747b779..433c537d77 100644
--- a/spec/openapi.yml
+++ b/spec/openapi.yml
@@ -1063,6 +1063,26 @@ components:
         buildStatus:
           $ref: "#/components/schemas/TemplateBuildStatus"
 
+    TemplateRefreshEnvdResponse:
+      required:
+        - templateID
+        - buildID
+        - fromEnvdVersion
+      properties:
+        templateID:
+          type: string
+          description: Identifier of the template being refreshed
+        buildID:
+          type: string
+          description: Identifier of the new build; poll its status/logs endpoints
+        fromEnvdVersion:
+          type: string
+          description: envd version the source build was baked with
+        aliases:
+          type: array
+          description: Aliases of the template (inherited from the source)
+          items:
+            type: string
     TemplateRequestResponseV3:
       required:
         - templateID
@@ -3240,6 +3260,42 @@ paths:
         "500":
           $ref: "#/components/responses/500"
 
+  /v2/templates/{templateID}/refresh-envd:
+    post:
+      summary: Rebuild a template with the current envd
+      description: |
+        Derives a new build of the template FROM the template's own latest ready
+        build, forcing the host's current envd binary to replace the one baked in
+        by the original build. Specs (cpu, memory) and the alias are inherited
+        from the source build. Returns the new build to poll via the existing
+        build status/logs endpoints.
+      tags: [templates]
+      security:
+        - ApiKeyAuth: []
+        - AuthProviderBearerAuth: []
+          AuthProviderTeamAuth: []
+        - AdminApiKeyAuth: []
+          AdminTeamAuth: []
+      parameters:
+        - $ref: "#/components/parameters/templateID"
+      responses:
+        "202":
+          description: The refresh build was requested successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TemplateRefreshEnvdResponse"
+        "400":
+          $ref: "#/components/responses/400"
+        "401":
+          $ref: "#/components/responses/401"
+        "403":
+          $ref: "#/components/responses/403"
+        "404":
+          $ref: "#/components/responses/404"
+        "500":
+          $ref: "#/components/responses/500"
+
   /v2/templates/{templateID}:
     patch:
       summary: Update template (v2)