Skip to content
Docs
Console

CLI

Install and authenticate the Tilebox CLI, explore datasets, and manage workflows from your terminal.

Use the Tilebox CLI to explore datasets, manage workflows, submit jobs, and inspect results from your terminal.

Installation

Install the CLI on macOS, Linux, or Windows, on x64 or ARM64. Choose CLI + Skills to also install Tilebox skills for your coding agent. The wizard also installs uv for Python workflow development if it isn’t already installed.

Use curl to download the installer and sh to run it:

bash 
curl -fsSL https://install.tilebox.com/wizard.sh | sh
bash 
curl -fsSL https://install.tilebox.com/cli.sh | sh

In Windows PowerShell 5.1 or PowerShell 7, use irm to download the installer and iex to run it:

powershell 
irm https://install.tilebox.com/wizard.ps1 | iex
powershell 
irm https://install.tilebox.com/cli.ps1 | iex

The installer uses %LOCALAPPDATA%\Tilebox\bin without administrator access and adds it to PATH for the current PowerShell session and future sessions. If you use Command Prompt, open PowerShell to install and continue there.

Shell Autocompletion

The wizard automatically installs shell autocompletion for Bash, Zsh, and fish.

PowerShell completions are optional. Run the following in your normal PowerShell session. If your execution policy blocks local scripts, it prompts to allow them for your user account; this affects all your PowerShell scripts, not only Tilebox. Organization-enforced policies may prevent this change.

powershell 
if ((Get-ExecutionPolicy) -in @('Restricted', 'AllSigned')) {
    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -ErrorAction Stop
}

if (-not (Test-Path -LiteralPath $PROFILE)) {
    New-Item -ItemType File -Path $PROFILE -Force -ErrorAction Stop | Out-Null
}

$completionLine = "tilebox '@completion' pwsh | Out-String | Invoke-Expression"
if ((Get-Content -LiteralPath $PROFILE) -notcontains $completionLine) {
    Add-Content -LiteralPath $PROFILE -Value "`r`n$completionLine" -ErrorAction Stop
}

# Enable completions in this session as well as future sessions.
Invoke-Expression $completionLine

Authenticate

Create an API key in the Tilebox Console, then choose your shell below. Replace YOUR_TILEBOX_API_KEY with your key and run the command in your terminal.

bash 
echo 'export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"' >> ~/.bashrc
source ~/.bashrc

For login shells, including Bash in macOS Terminal by default, use ~/.bash_profile in both commands instead. If you already use ~/.bash_login or ~/.profile instead of ~/.bash_profile, use that file.

zsh 
echo 'export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"' >> "${ZDOTDIR:-$HOME}/.zshrc"
source "${ZDOTDIR:-$HOME}/.zshrc"
fish 
set -gx TILEBOX_API_KEY "YOUR_TILEBOX_API_KEY"
set -Ux TILEBOX_API_KEY "$TILEBOX_API_KEY"
powershell 
$env:TILEBOX_API_KEY = "YOUR_TILEBOX_API_KEY"
[Environment]::SetEnvironmentVariable(
  "TILEBOX_API_KEY", $env:TILEBOX_API_KEY, "User"
)

On Windows, this saves the key in your user environment as well as the current session. Restart Windows Terminal or your editor before opening new terminals there so they pick up the saved value.

These commands save the key for future terminal sessions and make it available immediately. They store the key in plaintext in your shell configuration or Windows user environment and may also save it in shell history. Keep your key private. When replacing a key in Bash or Zsh, edit the existing entry rather than appending another one.

Check which user and organization your key belongs to:

bash 
tilebox account get

You can override the environment variable with --api-key on an individual command. See Authentication for API key management.

Explore commands

Use --help to browse commands and their options:

bash 
tilebox --help
tilebox dataset --help
tilebox job list --help

Start with read-only commands to inspect your resources:

bash 
tilebox dataset list
tilebox workflow list
tilebox job list --last 7d

You can also search the documentation without leaving your terminal:

bash 
tilebox docs search "query datasets by spatial extent"

Multiline examples below use Bash’s \ line continuation. In PowerShell, put the command on one line or replace each trailing \ with a backtick (`).

Query open data

Query Sentinel-2 scenes acquired in the last seven days whose footprints intersect a bounding box around Vienna:

bash 
tilebox dataset query open_data.copernicus.sentinel2_msi \
  --last 7d \
  --spatial-extent 'POLYGON((16.18 48.11,16.58 48.11,16.58 48.33,16.18 48.33,16.18 48.11))' \
  --limit 10

Coordinates are longitude, latitude in degrees. Replace the polygon with your area of interest, or save a GeoJSON Polygon or MultiPolygon to area.geojson and query from the file:

bash 
tilebox dataset query open_data.copernicus.sentinel2_msi \
  --last 7d \
  --spatial-extent-file area.geojson \
  --limit 10

The command returns scene metadata as JSON, not imagery files. It queries all collections unless you specify --collections. To retrieve another page, pass the response’s next_cursor as --cursor, keeping the same filters. See Open data for available datasets.

Browse results with --interactive

Add --interactive when reading results in your terminal. Job lists appear as tables; dataset queries show indented, syntax-highlighted JSON. When the output exceeds the terminal height, a pager lets you browse without scrolling through your shell history.

bash 
tilebox job list --last 7d --interactive
bash 
tilebox dataset query open_data.copernicus.sentinel2_msi \
  --last 7d \
  --spatial-extent 'POLYGON((16.18 48.11,16.58 48.11,16.58 48.33,16.18 48.33,16.18 48.11))' \
  --limit 10 \
  --interactive

Use the arrow keys to move, Page Up and Page Down to page through the output, and q or Escape to quit. The pager only browses the results already returned; use --cursor to fetch another API page. Interactive mode requires a terminal for both input and output. For scripts and agents, omit --interactive and use --json instead.

Scaffold workflow projects

Use the CLI to create a Tilebox workflow and scaffold a Python release project. This requires uv on PATH. Native Windows workflow runners require tilebox-workflows 0.64.0 or newer in the project’s Python dependencies.

bash 
tilebox workflow init --name "Scene QA"

The command creates the remote workflow, writes tilebox.workflow.toml, creates Python project files, adds the tilebox dependency, and runs uv sync. See Project Structure for the generated files and release project layout.

Use files and standard input

For larger inputs, prefer file-based flags instead of long shell-quoted strings. The CLI supports input patterns such as --schema-file, --input-file, --spatial-extent-file, and --description-file. Many file flags also support - for reading from standard input.

bash 
tilebox dataset create --schema-file schema.json
bash 
# Read from stdin.
cat schema.json | tilebox dataset create --schema-file -

Using files avoids shell-quoting issues when passing JSON, geometry, or multiline descriptions.

Update the CLI

Upgrade an installed release to the latest version on macOS, Linux, or Windows:

bash 
tilebox upgrade

Designed for agents too

Coding agents can use the same CLI commands you run in your terminal. Machine-readable command discovery and JSON output let them inspect available operations and use results in follow-up commands.

Discover commands with agent-context

Agents should inspect the CLI instead of guessing command names and flags. The agent-context command returns machine-readable information about the available command tree, arguments, flags, and descriptions.

bash 
tilebox agent-context

Scope discovery to a specific command and include its output schema before parsing results:

bash 
tilebox agent-context job list --output-schema

Prefer JSON output

Use --json when an agent or script needs to parse command output, rather than relying on terminal tables.

bash 
tilebox dataset list --json

agent-context always returns JSON and does not need the --json flag. Avoid --interactive in agent workflows, since it can open a pager.

Use the CLI with Tilebox skills

The Tilebox skills guide agents through tasks such as managing datasets, monitoring jobs, and configuring automations. If you chose CLI + Skills during installation, you already have them. Otherwise, install them separately:

bash 
curl -fsSL https://install.tilebox.com/skills.sh | sh
powershell 
irm https://install.tilebox.com/skills.ps1 | iex

Together, the CLI and skills give agents the tools and context to turn a task described in plain language into a sequence of Tilebox operations.

Docs

Type to search…