CLI

The Tilde CLI (tilde) is a command-line tool for running sandboxed commands on the Tilde runtime. It is designed for scripting, CI/CD pipelines, and agent workflows.

Install

One-liner (macOS & Linux)Manual Install (Windows, macOS, Linux)

curl -fsSL https://tilde.run/install | sh

The installer downloads the latest CLI binary to ~/.tilde/bin/, adds it to your shell PATH (with your confirmation), and opens your browser to authenticate.

Operating System macOS Linux Windows

Architecture arm64 (Apple Silicon / ARM) amd64 (Intel / x86_64)

Download tilde CLI

After downloading, extract the binary and put it on your PATH:

• macOS / Linux: tar -xzf tilde-cli_*.tar.gz && sudo mv tilde /usr/local/bin/
• Windows: extract the .zip and add the directory containing tilde.exe to your PATH

Verify the installation:

tilde --help

Authentication

The CLI supports several authentication methods, resolved in this order:

1. --api-key flag (highest priority)
2. TILDE_API_KEY environment variable
3. ~/.tilde/config.yaml (written by tilde auth login)
4. Sandbox metadata URI (automatic when running inside a Tilde sandbox)

Interactive: tilde auth login

For local/interactive use, run:

tilde auth login

The CLI prints a short user code and a verification URL, and (on macOS and Linux) opens the URL in your browser automatically. Confirm the code in the browser and the CLI completes login on its own, saving credentials to ~/.tilde/config.yaml.

This is the same flow the install script runs at the end. To re-authenticate (for example, after switching accounts) just run tilde auth login again.

To check which identity the CLI is currently using:

tilde auth status

To remove saved credentials:

tilde auth logout

tilde auth logout deletes ~/.tilde/config.yaml. Credentials set via TILDE_API_KEY or --api-key are not affected.

Non-interactive: TILDE_API_KEY

For CI/CD pipelines, scripts, and agent workflows where a browser isn't available, authenticate with an API key. The token is shown only once at creation time, so save it somewhere safe.

Create an API key →

Then expose it to the CLI:

export TILDE_API_KEY="tak-your-agent-key-here"

TILDE_API_KEY takes precedence over the saved interactive credentials when both are present, so you can safely set it in a CI environment without affecting local logins.

Inside a Tilde sandbox

When the CLI runs inside a Tilde sandbox, it automatically authenticates using the sandbox's principal via the TILDE_SANDBOX_CREDENTIALS_URI metadata endpoint. No API key or config file is needed. This enables nested sandbox creation and agent workflows without manually threading credentials.

tilde auth status reports the sandbox principal identity when run in this context.

Quick Start

Execute a command

Use tilde exec to run a command in a sandbox, stream its output, and exit with the sandbox's exit code:

# Run a command and stream output
tilde exec my-team/my-repo -- ls -la

# Use a specific container image
tilde exec my-team/my-repo --image python:3.12 -- python script.py

# Pass environment variables and set a timeout
tilde exec my-team/my-repo --image alpine:3.19 -e FOO=bar --timeout 5m -- ./run.sh

Interactive shell

Use tilde shell to get a fully interactive terminal session inside a sandbox:

# Start a shell
tilde shell my-team/my-repo

# Start with a specific image
tilde shell my-team/my-repo --image ubuntu:22.04

# Run a specific command interactively
tilde shell my-team/my-repo -- /bin/sh -l

Commands

exec — Run a Command

Run a command inside a sandbox, stream its output to your terminal, and exit with the sandbox's exit code. The repository is specified as organization/repository, followed by -- and the command to run.

tilde exec organization/repository [flags] -- command [args...]

Flags:

Flag	Description
--image	Docker image reference, e.g. python:3.12 (default: ubuntu:22.04)
-e, --env	Environment variable in KEY=VALUE format (repeatable)
--timeout	Sandbox timeout duration (30s, 5m, 1h)

shell — Interactive Shell

Open a fully interactive terminal session inside a sandbox. Supports the same flags as exec.

tilde shell organization/repository [flags] [-- command [args...]]

If no command is specified after --, the container's default shell is used.

Flags:

Flag	Description
--image	Docker image reference, e.g. python:3.12 (default: ubuntu:22.04)
-e, --env	Environment variable in KEY=VALUE format (repeatable)
--timeout	Sandbox timeout duration (30s, 5m, 1h)

sandbox run — Advanced Sandbox Control

A lower-level command with full control over sandbox lifecycle, including detached and interactive modes.

tilde sandbox run -r organization/repository [flags] -- command [args...]

Flags:

Flag	Description
-r, --repository	Repository in organization/repository format (required)
--image	Docker image reference, e.g. python:3.12 (required)
-e, --env	Environment variable in KEY=VALUE format (repeatable)
--timeout	Sandbox timeout in seconds (integer, e.g. 30, 300)
-d, --detach	Detached mode — prints the sandbox ID and exits immediately
-i, --interactive	Interactive mode — attaches a terminal to the sandbox
--mountpoint	Mount point inside the container
--path-prefix	Path prefix for mounted data

Examples:

# Run and stream output (like exec)
tilde sandbox run -r my-team/my-repo --image alpine -- echo hello

# Detached mode — prints the sandbox ID and exits immediately
tilde sandbox run -r my-team/my-repo --image alpine -d -- echo hello

# Interactive mode (like shell)
tilde sandbox run -r my-team/my-repo --image alpine -i -- /bin/sh

sandbox logs — View Sandbox Logs

Stream the output of a sandbox.

tilde sandbox logs -r organization/repository [flags] SANDBOX_ID

Flags:

Flag	Description
-r, --repository	Repository in organization/repository format (required)
-f, --follow	Follow logs in real time until the sandbox finishes

sandbox info — Get Sandbox Details

Display metadata about a sandbox, including its status, exit code, and timestamps.

tilde sandbox info -r organization/repository SANDBOX_ID

Flags:

Flag	Description
-r, --repository	Repository in organization/repository format (required)

sandbox cancel — Cancel a Running Sandbox

Cancel a sandbox that is currently queued or running.

tilde sandbox cancel -r organization/repository SANDBOX_ID

Flags:

Flag	Description
-r, --repository	Repository in organization/repository format (required)

version — Print CLI Version

Print the installed CLI version and exit.

tilde version

update — Update the CLI

Download and install the latest CLI binary.

tilde update

repository ls — List Repositories

List all repositories accessible to the authenticated user. Optionally filter by organization.

# List all repositories
tilde repository ls

# List repositories in a specific organization
tilde repository ls my-team

Output format (one per line):

my-team/my-data
my-team/models
other-org/shared-data

Global Flags

These flags are accepted by every tilde command:

Flag	Description
--api-key	Tilde API key. Overrides TILDE_API_KEY and saved credentials.

Environment Variables

Variable	Required	Default	Description
TILDE_API_KEY	No*	—	Tilde API key. Required only if you have not run tilde auth login and are not inside a sandbox.
TILDE_ENDPOINT_URL	No	https://tilde.run	Tilde API endpoint

* See Authentication for the full credential resolution order.

Examples

Run a Python script with dependencies

tilde exec my-team/my-repo --image python:3.12 -- \
  bash -c "pip install pandas && python /sandbox/analyze.py"

Run a detached job and check on it later

# Start the sandbox in detached mode
SANDBOX_ID=$(tilde sandbox run -r my-team/my-repo --image alpine -d -- sleep 300)

# Check its status
tilde sandbox info -r my-team/my-repo $SANDBOX_ID

# Follow its logs
tilde sandbox logs -r my-team/my-repo -f $SANDBOX_ID