---
title: "CLI"
description: "Install and authenticate the Tilebox CLI, explore datasets, and manage workflows from your terminal."
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

import { Tabs, TabItem } from "@docs/components/ui/tabs";

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

## Installation

### CLI + Skills

Install the CLI and [Tilebox skills](/docs/ai/skills) for your coding agent.

```bash
curl -fsSL https://install.tilebox.com/wizard.sh | sh
```
### Only CLI

Install the CLI without agent skills.

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

## Authenticate

Create an API key in the [Tilebox Console](https://console.tilebox.com/settings/api-keys), then export it in your shell:

```bash
export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"
```

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](/docs/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"
```

## 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](/docs/datasets/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.

```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](/docs/workflows/build-and-deploy/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:

```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](/docs/ai/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
```

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.

Source: https://tilebox.com/docs/cli/index.mdx