feat(cli): add volume and secret management subcommands

.changeset/cli-volume-secret-commands.md

@@ -0,0 +1,5 @@
+---
+'@e2b/cli': patch
+---
+
+Add `e2b volume` and `e2b secret` subcommands exposing the volume and secret management the SDK already provides. `e2b volume` supports `create`, `list`, `info`, and `delete` (`rm`); `e2b secret` supports `create` (with `--value` and `--metadata`), `list`, `info`, `update` (rotate the value into a new version), and `delete` (`rm`). Both follow the existing `e2b sandbox` command style (`--format json|pretty`, kubectl-style tables, `ensureAPIKey`).

packages/cli/src/commands/index.ts

@@ -4,6 +4,8 @@ import { asPrimary } from 'src/utils/format'
 import { templateCommand } from './template'
 import { sandboxCommand } from './sandbox'
 import { authCommand } from './auth'
+import { volumeCommand } from './volume'
+import { secretCommand } from './secret'
 
 export const program = new commander.Command()
   // Fixed so help reads `e2b` however the entrypoint is invoked (npm bin
@@ -23,3 +25,5 @@ Visit ${asPrimary(
   .addCommand(authCommand)
   .addCommand(templateCommand)
   .addCommand(sandboxCommand)
+  .addCommand(volumeCommand)
+  .addCommand(secretCommand)

packages/cli/src/commands/secret/commands.ts

@@ -0,0 +1,223 @@
+import * as commander from 'commander'
+import { Secret } from 'e2b'
+
+import { ensureAPIKey } from 'src/api'
+import { asBold } from 'src/utils/format'
+import { renderTable } from 'src/utils/table'
+import { parseMetadata } from '../sandbox/utils'
+
+const DEFAULT_LIMIT = 1000
+const PAGE_LIMIT = 100
+
+// Secret values are write-only — never returned by the API — so they are
+// never printed. Only the secret's ID/name/version/metadata/timestamps are.
+export function formatSecretRow(secret: {
+  secretId: string
+  name: string
+  version: number
+  metadata: Record<string, string>
+  createdAt: Date
+  updatedAt: Date
+}) {
+  return {
+    ...secret,
+    createdAt: new Date(secret.createdAt).toLocaleString(),
+    updatedAt: new Date(secret.updatedAt).toLocaleString(),
+    metadata: JSON.stringify(secret.metadata),
+  }
+}
+
+export const createCommand = new commander.Command('create')
+  .description('create a new secret')
+  .argument(
+    '<name>',
+    `name for the secret, unique within the project, eg. ${asBold('API_KEY')}`
+  )
+  .requiredOption(
+    '-v, --value <value>',
+    'secret value (write-only — never returned by the API)'
+  )
+  .option(
+    '-m, --metadata <metadata>',
+    'metadata to store with the secret, eg. key1=value1',
+    (value, prev: string[]) => [...(prev ?? []), value],
+    []
+  )
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(
+    async (
+      name: string,
+      options: {
+        value: string
+        metadata?: string[]
+        format?: string
+      }
+    ) => {
+      try {
+        const apiKey = ensureAPIKey()
+        const metadata = parseMetadata(options.metadata?.join(','))
+
+        const info = await Secret.create(name, options.value, {
+          apiKey,
+          metadata,
+        })
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify(info, null, 2))
+        } else {
+          console.log(
+            `Created secret ${asBold(info.name)} (ID: ${asBold(info.secretId)}, version ${info.version})`
+          )
+        }
+      } catch (err: any) {
+        console.error(err)
+        process.exit(1)
+      }
+    }
+  )
+
+export const listCommand = new commander.Command('list')
+  .description('list all secrets')
+  .alias('ls')
+  .option(
+    '-l, --limit <limit>',
+    `limit the number of secrets returned (default: ${DEFAULT_LIMIT}, 0 for no limit)`,
+    (value: string) => parseInt(value)
+  )
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(async (options: { limit?: number; format?: string }) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const format = options.format || 'pretty'
+      const limit =
+        options.limit === 0 ? undefined : (options.limit ?? DEFAULT_LIMIT)
+
+      let pageLimit = limit
+      if (!limit || limit > PAGE_LIMIT) {
+        pageLimit = PAGE_LIMIT
+      }
+
+      const secrets: Awaited<ReturnType<typeof Secret.getInfo>>[] = []
+      const paginator = Secret.list({ apiKey, limit: pageLimit })
+
+      while (paginator.hasNext && (!limit || secrets.length < limit)) {
+        const batch = await paginator.nextItems()
+        secrets.push(...batch)
+      }
+
+      const trimmed = limit ? secrets.slice(0, limit) : secrets
+
+      if (format === 'json') {
+        console.log(JSON.stringify(trimmed, null, 2))
+      } else {
+        if (!trimmed.length) {
+          console.log('No secrets found')
+          return
+        }
+
+        renderTable(trimmed.map(formatSecretRow), [
+          { header: 'Secret ID', value: (row) => row.secretId },
+          { header: 'Name', value: (row) => row.name },
+          { header: 'Version', value: (row) => String(row.version) },
+          { header: 'Created at', value: (row) => row.createdAt },
+          { header: 'Updated at', value: (row) => row.updatedAt },
+          { header: 'Metadata', value: (row) => row.metadata },
+        ])
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+
+export const infoCommand = new commander.Command('info')
+  .description('show details for a secret (by ID or name)')
+  .argument('<secret>', `the secret ${asBold('<secretID>')} or name`)
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(async (secret: string, options: { format?: string }) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const info = await Secret.getInfo(secret, { apiKey })
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify(info, null, 2))
+      } else {
+        console.log(`Secret ID:  ${asBold(info.secretId)}`)
+        console.log(`Name:       ${asBold(info.name)}`)
+        console.log(`Version:    ${info.version}`)
+        console.log(`Created at: ${new Date(info.createdAt).toLocaleString()}`)
+        console.log(`Updated at: ${new Date(info.updatedAt).toLocaleString()}`)
+        console.log(`Metadata:   ${JSON.stringify(info.metadata)}`)
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+
+export const updateCommand = new commander.Command('update')
+  .description("update a secret's value, storing it as a new version")
+  .argument('<secret>', `the secret ${asBold('<secretID>')} or name`)
+  .requiredOption(
+    '-v, --value <value>',
+    'new secret value (write-only — never returned by the API)'
+  )
+  .option(
+    '-m, --metadata <metadata>',
+    'metadata to replace the stored metadata, eg. key1=value1',
+    (value, prev: string[]) => [...(prev ?? []), value],
+    []
+  )
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(
+    async (
+      secret: string,
+      options: {
+        value: string
+        metadata?: string[]
+        format?: string
+      }
+    ) => {
+      try {
+        const apiKey = ensureAPIKey()
+        const metadata = parseMetadata(options.metadata?.join(','))
+
+        const info = await Secret.update(secret, options.value, {
+          apiKey,
+          metadata,
+        })
+
+        if (options.format === 'json') {
+          console.log(JSON.stringify(info, null, 2))
+        } else {
+          console.log(
+            `Updated secret ${asBold(info.name)} (ID: ${asBold(info.secretId)}, version ${info.version})`
+          )
+        }
+      } catch (err: any) {
+        console.error(err)
+        process.exit(1)
+      }
+    }
+  )
+
+export const deleteCommand = new commander.Command('delete')
+  .description('delete a secret, making all its versions inaccessible')
+  .argument('<secret>', `the secret ${asBold('<secretID>')} or name to delete`)
+  .alias('rm')
+  .action(async (secret: string) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const destroyed = await Secret.destroy(secret, { apiKey })
+
+      if (destroyed) {
+        console.log(`Secret ${asBold(secret)} has been deleted`)
+      } else {
+        console.error(`Secret ${asBold(secret)} wasn't found`)
+        process.exit(1)
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })

packages/cli/src/commands/secret/index.ts

@@ -0,0 +1,19 @@
+import * as commander from 'commander'
+
+import {
+  createCommand,
+  deleteCommand,
+  infoCommand,
+  listCommand,
+  updateCommand,
+} from './commands'
+
+export const secretCommand = new commander.Command('secret')
+  .description(
+    'manage secrets — values stored server-side and injected into sandboxes'
+  )
+  .addCommand(createCommand)
+  .addCommand(listCommand)
+  .addCommand(infoCommand)
+  .addCommand(updateCommand)
+  .addCommand(deleteCommand)

packages/cli/src/commands/volume/commands.ts

@@ -0,0 +1,106 @@
+import * as commander from 'commander'
+import { Volume } from 'e2b'
+
+import { ensureAPIKey } from 'src/api'
+import { asBold } from 'src/utils/format'
+import { renderTable } from 'src/utils/table'
+
+export const createCommand = new commander.Command('create')
+  .description('create a new volume')
+  .argument('<name>', `name for the volume, eg. ${asBold('my-volume')}`)
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(async (name: string, options: { format?: string }) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const volume = await Volume.create(name, { apiKey })
+
+      const info = {
+        volumeId: volume.volumeId,
+        name,
+      }
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify(info, null, 2))
+      } else {
+        console.log(
+          `Created volume ${asBold(info.name)} (ID: ${asBold(info.volumeId)})`
+        )
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+
+export const listCommand = new commander.Command('list')
+  .description('list all volumes')
+  .alias('ls')
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(async (options: { format?: string }) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const volumes = await Volume.list({ apiKey })
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify(volumes, null, 2))
+      } else {
+        if (!volumes.length) {
+          console.log('No volumes found')
+          return
+        }
+
+        renderTable(volumes, [
+          { header: 'Volume ID', value: (row) => row.volumeId },
+          { header: 'Name', value: (row) => row.name },
+        ])
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+
+export const infoCommand = new commander.Command('info')
+  .description('show details for a volume')
+  .argument('<volumeID>', `the volume ${asBold('<volumeID>')}`)
+  .option('-f, --format <format>', 'output format, eg. json, pretty')
+  .action(async (volumeID: string, options: { format?: string }) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const info = await Volume.getInfo(volumeID, { apiKey })
+
+      if (options.format === 'json') {
+        console.log(JSON.stringify(info, null, 2))
+      } else {
+        console.log(`Volume ID:  ${asBold(info.volumeId)}`)
+        console.log(`Name:       ${asBold(info.name)}`)
+        if (info.domain) {
+          console.log(`Domain:     ${info.domain}`)
+        }
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+
+export const deleteCommand = new commander.Command('delete')
+  .description('delete a volume')
+  .argument('<volumeID>', `the volume ${asBold('<volumeID>')} to delete`)
+  .alias('rm')
+  .action(async (volumeID: string) => {
+    try {
+      const apiKey = ensureAPIKey()
+      const destroyed = await Volume.destroy(volumeID, { apiKey })
+
+      if (destroyed) {
+        console.log(`Volume ${asBold(volumeID)} has been deleted`)
+      } else {
+        console.error(`Volume ${asBold(volumeID)} wasn't found`)
+        process.exit(1)
+      }
+    } catch (err: any) {
+      console.error(err)
+      process.exit(1)
+    }
+  })

packages/cli/src/commands/volume/index.ts

@@ -0,0 +1,17 @@
+import * as commander from 'commander'
+
+import {
+  createCommand,
+  deleteCommand,
+  infoCommand,
+  listCommand,
+} from './commands'
+
+export const volumeCommand = new commander.Command('volume')
+  .description(
+    'manage volumes — persistent storage that can be mounted into sandboxes'
+  )
+  .addCommand(createCommand)
+  .addCommand(listCommand)
+  .addCommand(infoCommand)
+  .addCommand(deleteCommand)