Template Commands

Complete reference for managing environment templates with the ScaleBox CLI. Templates define the images, resource defaults, ports, and runtime settings used to create sandbox environments.

Table of Contents

• Template name rules
• Choose the right creation flow
• Template documentation commands
• Command reference
• Command configuration notes
• Permissions and visibility
• Troubleshooting

Template Name Rules

Template names are validated by the API.

• Length: 4 to 32 characters
• Allowed characters: lowercase letters (a-z), numbers (0-9), hyphens (-), underscores (_)
• Must start and end with an alphanumeric character
• Cannot start with a number
• Cannot start with tpl-
• Cannot contain consecutive separators such as --, __, -_, or _-

Examples:

• Invalid: My Nginx, ng, 1-python, tpl-demo
• Valid: my-nginx, python-data-science

Choose the Right Creation Flow

Template Documentation Commands

Long-form Markdown documentation is stored separately from the short template description. Use scalebox-cli template document for Markdown docs.

template document get [template-id-or-name]

Fetch template documentation as JSON by default, or print raw Markdown with --raw.

scalebox-cli template document get tpl-abc123
scalebox-cli template document get my-template --raw
scalebox-cli template document get tpl-abc123 --raw -o ./GUIDE.md

template document download [template-id-or-name]

Download template Markdown as a file. The server rejects empty documents.

scalebox-cli template document download tpl-abc123
scalebox-cli template document download tpl-abc123 -o ./README.md
scalebox-cli template document download tpl-abc123 -o -

template document set [template-id-or-name]

Upload Markdown from a file or stdin.

scalebox-cli template document set tpl-abc123 -f ./guide.md
cat guide.md | scalebox-cli template document set tpl-abc123

template document clear [template-id-or-name]

Remove stored Markdown documentation.

scalebox-cli template document clear tpl-abc123

Command Reference

template build

Build or publish a template: derive from a ScaleBox template, use a local build context, pull an external image with Docker, or load a local OCI tar. Use at most one of --base / --base-template-id, --external-image-url, or --image-file. If none is provided, the CLI performs a local Docker build and registers a custom template.

External image pull: the CLI calls validate-custom-image, then pulls with --username / --password when provided (public images omit credentials). Harbor push uses ScaleBox-managed credentials from the API.

Local copy vs import: when you have Docker on your machine, use template build --external-image-url or --image-file instead of template import.

# Derive from an existing ScaleBox template
scalebox-cli template build --name "my-python-env" --base "python-base"

# Use a custom Dockerfile with inheritance
scalebox-cli template build --name "my-custom-python" --base "python-base" --dockerfile "./Dockerfile"

# Local build only (no base / external image flag)
scalebox-cli template build --name "my-app" --path . --cpu 2 --memory 2048

# Copy a public external image locally, then push to Harbor
scalebox-cli template build --name "my-ubuntu-app" --external-image-url "docker.io/library/ubuntu:22.04" --cpu 2 --memory 2048

# Private registry
scalebox-cli template build --name "my-app" \
  --external-image-url "registry.example.com/myapp:v1" \
  --username myuser --password mypass --cpu 2 --memory 2048

# Build from a local OCI tar file
scalebox-cli template build --name "custom-jupyter" --image-file "jupyter.tar" --cpu 4 --memory 8192

# Custom startup and readiness commands
scalebox-cli template build --name "web-server" --base "python-base" --cmd "python app.py" --ready-cmd "curl -f http://localhost:8000/health"

template create-custom

Register an external Docker image directly as a custom template. This path does not import the image into Harbor first.

Provide either --external-image-url or --image. If the image does not already define an Entrypoint or Cmd, you must supply --custom-command. --base only supports inheriting from another custom template, not from a ScaleBox family template.

scalebox-cli template create-custom \
  --name "official-nginx" \
  --external-image-url docker.io/library/nginx:latest \
  --cpu 1 --memory 512 \
  --ports '[{"port":8888,"name":"sandbox","is_protected":true},{"port":80,"name":"http"}]'

scalebox-cli template create-custom \
  --name "my-app" \
  --image registry.example.com/myapp:v1.0 \
  --username myuser \
  --password mypass \
  --cpu 2 --memory 2048

scalebox-cli template create-custom \
  --name "my-app-v2" \
  --base tpl-custom-v1 \
  --image registry.example.com/myapp:v2.0 \
  --cpu 4

template import

Copy an external Docker image into ScaleBox Harbor using a backend import job (POST /v1/templates/import). No local Docker is required. The result is always a custom template (sidecar agent deployment).

Unlike template create-custom, template import requires the source image to define an Entrypoint or Cmd (or you pass --custom-command). It does not accept --base. Track jobs with template import-jobs.

When you have Docker locally, use template build --external-image-url or --image-file instead.

scalebox-cli template import --name "redis-7-2" --image docker.io/library/redis:7.2 --cpu 1 --memory 1024

scalebox-cli template import \
  --name "private-app" \
  --image registry.example.com/myapp:latest \
  --username myuser \
  --password mypass \
  --cpu 2 --memory 4096

template import-jobs

List or inspect template import jobs. By default, only ongoing jobs are shown.

scalebox-cli template import-jobs
scalebox-cli template import-jobs --all
scalebox-cli template import-jobs --template-id tpl-abc123
scalebox-cli template import-jobs --job-id job-xyz789

When you use JSON output, list responses use the canonical nested pagination object.

template list

List all accessible templates with filtering, search, and pagination options.

scalebox-cli template list
scalebox-cli template list --public
scalebox-cli template list --private
scalebox-cli template list --search "python"
scalebox-cli template list --lifecycle active --page 2 --limit 10
scalebox-cli template list --all
scalebox-cli template list --all --max-items 200

Do not combine --all with a non-default --page.

template get [template-id]

Fetch a template by ID. In text mode the CLI prints a concise summary; in JSON output mode it returns the full template payload from the API.

scalebox-cli template get tpl-abc123def456789
scalebox-cli template get tpl-xyz789

template dockerfile [template-id-or-name]

Download a Dockerfile template from an existing template.

scalebox-cli template dockerfile base
scalebox-cli template dockerfile tpl-abc123 --output Dockerfile.base
scalebox-cli template dockerfile base --output -

template update [template-id]

Update template metadata and configuration.

The current CLI still exposes --image-url and --tag in --help, but the command returns an error if you use them. To change the image backing a template, create a new version with template build or template import instead.

scalebox-cli template update tpl-abc123 --name "new-name" --description "Updated description"
scalebox-cli template update tpl-abc123 --cpu 8 --memory 16384
scalebox-cli template update tpl-abc123 --ports '[{"port":8888,"name":"jupyter"}]'
scalebox-cli template update tpl-abc123 --metadata '{"team":"ml"}'
scalebox-cli template update tpl-abc123 --custom-command '{"Entrypoint":["python"],"Cmd":["app.py"]}'
scalebox-cli template update tpl-abc123 --ready-command '{"type":"httpGet","port":8000,"path":"/health"}'

template delete [template-id]

Delete a template permanently.

The current implementation deletes immediately; there is no working --force flag and no confirmation prompt even though the built-in help text still shows stale examples mentioning --force.

scalebox-cli template delete tpl-abc123

template share [template-id]

Share a private template with your account by switching visibility to account_shared.

Only the template owner can share it, and the template must already be active.

scalebox-cli template share tpl-abc123
scalebox-cli template share tpl-abc123 --new-name "my-shared-env"

template unshare [template-id]

Convert an account-shared template back to private.

Only the template owner can unshare it, and the template must already be active.

scalebox-cli template unshare tpl-abc123

Command Configuration Notes

Build-time command flags

template build uses:

• --cmd for the startup command
• --ready-cmd for the readiness probe

The readiness probe accepts either:

• a plain command string, treated as exec
• a JSON object with type set to exec, httpGet, or tcpSocket

Example:

scalebox-cli template build --name "web-server" --base "python-base" --cmd "python app.py" --ready-cmd '{"type":"httpGet","port":8000,"path":"/health"}'

Update and custom-template command flags

template update uses --custom-command and --ready-command, while template create-custom and template import use --custom-command for the custom template start command.

These commands do not use the shorter --cmd / --ready-cmd flag names.

template create-custom accepts a custom command as JSON in the form {"Entrypoint":[...],"Cmd":[...]}. For template update, the accepted format depends on the template source: custom templates use JSON, while scalebox_family templates use plain text.

Permissions and Visibility

• You can list accessible templates, inspect them, derive templates with template build, register external images with template create-custom, import images with template import, and update templates you own.
• Public ScaleBox templates are available as bases; you cannot modify templates you do not own.
• Default visibility for template build, template create-custom, and template import is private.
• Use template share to make a private template visible within your account (account_shared).
• On template import, setting account_shared directly requires an account root user; other users should import as private, then share.

Troubleshooting

"Template not found"

• Verify the template ID or name is correct
• Confirm you have access to the template
• Remember that template IDs use the tpl-... format

Invalid template name

• Use only lowercase letters, numbers, hyphens, and underscores
• Keep the name between 4 and 32 characters
• Do not start with a number or tpl-
• Do not use consecutive separators such as --, __, -_, or _-

Build or import problems

• Check that Docker is installed and running for template build (local pull, build, or docker load)
• For private registries, pass --username and --password to template build or template import (validated before pull or import job start)
• For template import, ensure a healthy cluster is available; check template import-jobs if the job stays pending or fails
• Validate JSON passed to --ports, --metadata, --custom-command, or readiness-probe flags