Skip to main content
PRE-RELEASE: Sandbox commands are not GA yet. Their arguments, flags, and output may change.
Images are what sandboxes are created from. Push one from a directory with a Dockerfile, or import one from a registry, then create sandboxes with —image name:latest.

​
list

Lists the team’s images, up to —limit.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
INTEGER
default:"1000"
Most images to list. 0 lists all.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID to list images of. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

List images

​
Filter output with --jq

Print every built image’s name

​
Output

Text mode (--output text): Table with columns: NAME, STATUS, TAGS, SIZE, CREATED. Prints “No sandbox images found.” to stderr when the list is empty, and a note to stderr when —limit left some out. JSON mode (--output json): Go output type cmd.SandboxImageList.

​
describe

Retrieves one image’s record: status, tag count, and size.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

Describe an image

​
Filter output with --jq

Print the image’s status

​
Output

Text mode (--output text): One field per line describing the image. Empty fields are left out. JSON mode (--output json): Go output type managementapi.SandboxImage.

​
push

Pushes a new version of an image, from exactly one source: —dir builds the directory, which must have a Dockerfile at its root, and —registry-image imports an image from a registry. Paths in —dir are left out as a .dockerignore at its root says. Without one, these are left out, as if the .dockerignore were: **/.blaxel **/.env.build **/.docker **/.git **/dist **/.venv **/venv **/node_modules */.env .env **/.next **/pycache A .dockerignore replaces these defaults, so copy any you still want into it. By default the command returns once the push is accepted and the build runs on; —wait waits until the image is built.

​
Options

​
TEXT
Directory to build the image from, with a Dockerfile at its root.Mutually exclusive with other flags in group image-source.
​
TEXT
Path to a Docker config.json with credentials for pulling —registry-image from a private registry.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Registry image reference to import, such as registry.example.com/app:v1.Mutually exclusive with other flags in group image-source.
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Wait until the image is built. Exits non-zero if the build fails. Does not stop the build if interrupted.
​
BOOL
Enable verbose logging

​
Examples

Build an image from the current directory and wait for it
Import an image from a private registry

​
Filter output with --jq

Push from a directory and print the image’s status

​
Output

Text mode (--output text): One field per line describing the image. Empty fields are left out. JSON mode (--output json): Go output type managementapi.SandboxImage.

​
delete

Deletes an image and every version of it. This cannot be undone.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Skip the interactive confirmation prompt. Required when stdin is not a terminal.
​
BOOL
Enable verbose logging

​
Examples

Delete an image without the confirmation prompt

​
Filter output with --jq

Delete an image and print its status

​
Output

Text mode (--output text): A confirmation line on stderr. JSON mode (--output json): Go output type managementapi.SandboxImage. The image’s record as deletion starts.

​
logs

Prints an image’s build logs, oldest first. At most the newest 11,000 lines in the time range are printed. Lines may take a short time to appear after they are written.

​
Options

​
TEXT
Latest log time to print, such as 2026-10-05T15:04:05Z.
​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Earliest log time to print, such as 2026-10-05T15:04:05Z.
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

Print an image’s build logs

​
Filter output with --jq

Print only the messages

​
Output

Text mode (--output text): One line per log entry: timestamp and message. JSON mode (--output json): Go output type managementapi.SandboxImageBuildLog.

​
list-tags

Lists every tag of an image, one per pushed version. Create a sandbox from a specific version with —image name:tag.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
required
Name of the image.
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
TEXT
Team name or ID the image belongs to. Defaults to your only team; required if you belong to more than one. Run ‘baseten org team list’ to see teams.
​
BOOL
Enable verbose logging

​
Examples

List an image’s tags

​
Filter output with --jq

Print every tag

​
Output

Text mode (--output text): Table with columns: TAG, SIZE, CREATED. Prints “No tags found.” to stderr when the list is empty. JSON mode (--output json): Go output type cmd.SandboxImageTagList.

​
list-library

Lists the platform’s starter images, which any sandbox can be created from without pushing anything. Pass an entry’s image as —image to ‘sandbox create’.

​
Options

​
TEXT
Filter JSON output with a jq expression; implies —output json (or jsonl for streamed commands)
​
TEXT
default:"text"
Output formatOne of: text, json, jsonl, none
​
TEXT
Use a specific stored profile for this command, overriding BASETEN_PROFILE and the current profile
​
BOOL
Enable verbose logging

​
Examples

List the starter images

​
Filter output with --jq

Print every starter image

​
Output

Text mode (--output text): Table with columns: NAME, IMAGE, MEMORY, CATEGORIES. Prints “No starter images found.” to stderr when the list is empty. JSON mode (--output json): Go output type cmd.SandboxImageLibraryList.