CLI

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

Installation

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

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

Authenticate

Create an API key in the Tilebox Console, then export it in your shell:

export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"

Check which user and organization your key belongs to:

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:

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

Start with read-only commands to inspect your resources:

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

You can also search the documentation without leaving your terminal:

tilebox docs search "query datasets by spatial extent"

Query open data

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

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:

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.

tilebox job list --last 7d --interactive

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.

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.

tilebox dataset create --schema-file schema.json

# 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:

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.

tilebox agent-context

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

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.

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:

curl -fsSL https://install.tilebox.com/skills.sh | sh

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.