# Tilebox CLI

> Use the Tilebox CLI for datasets, workflows, docs search, automations, parallel task runners. Use when a task involves tilebox commands. How to handle authentication, JSON output, agent-context schemas, pagination, installation, or upgrades.

- Skill: `tilebox/tilebox-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tilebox/tilebox-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tilebox/tilebox-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: tilebox (https://skillmd.com/u/tilebox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tilebox/tilebox-cli

---


# Using Tilebox CLI

Use this skill whenever interacting with the `tilebox` command-line tool. Prefer machine-readable output and command schema discovery so automation remains robust.

## Core Rules For Agents

- Always pass `--json` in agent workflows when the command supports it; never pass `--interactive`.
- Use `tilebox agent-context <command path> --output-schema` before relying on a command's output shape.
- Pass authentication via `TILEBOX_API_KEY` unless the user explicitly asks to use `--api-key`.
- Use `--api-url` only when targeting a non-default API environment.
- For paginated commands, read `next_cursor` from JSON output and pass it back as `--cursor` until it is empty.
- Use `tilebox agent-context <command>` when behavior is unclear.

## Authentication And API URL

The CLI authenticates with either:

```bash
export TILEBOX_API_KEY=...
tilebox account get --json
```

or per command:

```bash
tilebox account get --api-key "$TILEBOX_API_KEY" --json
```

The default API is `https://api.tilebox.com`. Override it for staging or local environments:

```bash
# a staging env
tilebox --api-url https://api.tilebox.dev account get --json
```

If auth is missing, commands return a validation-style usage error. After installation, or when investigating authentication failures, use `tilebox account get --json` to verify the API endpoint and active credential. Do not print or log API keys.

## JSON Output

Always use `--json` for supported commands in agent workflows:

```bash
tilebox dataset list --json
tilebox job list --last 7d --json
tilebox job get <job-id> --json
```

`--json` emits compact, unstyled, non-paginated output even under a pseudo-terminal. Human output may contain terminal styling, and `--interactive` may start a pager, so agents should not use either.

## Combine JSON Output With `jq`

Use `jq` for quick field extraction, filtering, and shell pipelines. Keep `tilebox` responsible for structured output and `jq` responsible for selecting the fields you need. Prefer keeping intermediate and final output as JSON objects or arrays.

Examples:

```bash
# List dataset slugs
tilebox dataset list --json | jq '[.[].slug]'

# Extract a submitted job ID
JOB_ID=$(tilebox job submit --name <job-name> --task <task-name> --input '{}' --json | jq -r '.id')

# Initialize a workflow project and extract its server-side workflow slug
WORKFLOW_SLUG=$(tilebox workflow init --name "Scene QA" --json | jq -r '.workflow_slug')

# Inspect failed jobs from a query response
tilebox job list --last 7d --state failed --json | jq '{jobs: [.jobs[] | {id, state, name}]}'

# Page through commands manually by reading next_cursor
tilebox job logs <job-id> --limit 100 --json | jq -r '.next_cursor'

# Read automation storage location IDs and locations
tilebox automation storage-locations --json | jq '{storage_locations: [.storage_locations[] | {id, type, location}]}'
```

Use `jq -e` when a script should fail if a required value is missing:

```bash
tilebox job get <job-id> --json | jq -e '.state == "completed"'
```

## Discovering Commands And Output Schemas

Use `agent-context` to inspect available commands, arguments, flags, descriptions, and output schemas.
It always returns JSON; do not add `--json` to `agent-context` commands.

Describe the whole CLI:

```bash
tilebox agent-context
```

Describe one command:

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

Typical workflow:

1. Run `tilebox agent-context <command path> --output-schema`.
2. Read required args/flags and the JSON output schema.
3. Run the command with `--json`.
4. Parse fields according to the schema.

## Searching Tilebox Docs

Use `tilebox docs search` to browse and retrieve relevant excerpts from `docs.tilebox.com` without leaving the CLI. It is useful when you need current product documentation, conceptual guidance, examples, or SDK/API details before choosing command flags or implementation details.

```bash
tilebox docs search "dataset schema custom fields"
tilebox docs search "query datasets temporal extent spatial extent"
tilebox docs search "workflow job retry logs spans"
```

Search with natural-language phrases that include the product area and the exact concept, command, SDK type, or error you care about. Prefer a focused query over a broad one:

```bash
# Good: scoped to a feature and expected terminology
tilebox docs search "dataset query spatial extent GeoJSON Polygon"

# Too broad: likely to return mixed concepts
tilebox docs search "query"
```

Use docs search when:

- `agent-context` tells you the CLI shape, but you need conceptual docs or examples.
- You need SDK or API behavior that may not be obvious from CLI help.
- You want to confirm current docs terminology before writing user-facing documentation.

Do not use docs search for command output schemas; use `tilebox agent-context <command path> --output-schema` for that.

## Pagination

Some commands return paginated results with a `next_cursor` field. Pass this as `--cursor` to fetch the next page of results. Loop until `next_cursor` is empty. For example:

```bash
tilebox job list --last 7d --limit 100 --json
tilebox job list --last 7d --limit 100 --cursor <next_cursor> --json
```

Keep the same filters and sort order across pages. Only change `--cursor`.

## Installing The CLI

The public installer downloads a released binary, verifies checksums, and installs to `$HOME/.local/bin` by default:

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

Customize the install directory:

```bash
curl -fsSL https://cli.tilebox.com/install.sh | TILEBOX_INSTALL_DIR="$HOME/bin" sh
```

Install a specific version:

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

Ensure the install directory is on `PATH`, set `TILEBOX_API_KEY`, then verify the installation and authentication:

```bash
tilebox account get --json
```

## Updating The CLI

Use the built-in upgrade command for released binaries installed on `PATH`:

```bash
tilebox upgrade --json
```

Install a specific release:

```bash
tilebox upgrade --version 0.3.1 --json
```

Force reinstall:

```bash
tilebox upgrade --force --json
```

Notes:

- `tilebox upgrade` requires `sh` and `curl`.
- It is not supported for dev builds or Windows.
- If the binary was installed in a custom directory, set `TILEBOX_INSTALL_DIR` when needed.

## Useful Command Families

The current CLI exposes these top-level command families. Run `tilebox agent-context` after CLI changes to refresh the list.

| Family | Purpose | Useful Commands |
| --- | --- | --- |
| `account` | Inspect the active account, usage overages, and subscription tier. | `tilebox account get`, `tilebox account subscription`, `tilebox account usage`, `tilebox whoami` |
| `automation` | Inspect workflow automations and storage locations. | `tilebox automation list`, `tilebox automation get <automation-id>`, `tilebox automation storage-locations` |
| `cluster` | Manage workflow compute clusters. | `tilebox cluster list`, `tilebox cluster get <cluster-slug>`, `tilebox cluster create <name>`, `tilebox cluster delete <cluster-slug>` |
| `dataset` | Create, update, inspect, query, find datapoints, and generate types for datasets. | `tilebox dataset list`, `tilebox dataset get <dataset-slug>`, `tilebox dataset create`, `tilebox dataset update <dataset-slug>`, `tilebox dataset query <dataset-slug>`, `tilebox dataset find <dataset-slug> <datapoint-id>`, `tilebox dataset generate --slug <dataset-slug>` |
| `dataset collection` | Manage collections within a dataset. | `tilebox dataset collection list --dataset <dataset-slug>`, `tilebox dataset collection get <name> --dataset <dataset-slug>`, `tilebox dataset collection create <name> --dataset <dataset-slug>`, `tilebox dataset collection delete <name> --dataset <dataset-slug>` |
| `job` | Submit, monitor, debug, retry, wait for, and cancel workflow jobs. | `tilebox job submit`, `tilebox job list`, `tilebox job get <job-id>`, `tilebox job wait <job-id>`, `tilebox job retry <job-id>`, `tilebox job cancel <job-id>`, `tilebox job logs <job-id>`, `tilebox job spans <job-id>` |
| `workflow` | Initialize, create, inspect, build, publish, deploy, and undeploy workflow releases. | `tilebox workflow init`, `tilebox workflow create`, `tilebox workflow list`, `tilebox workflow get`, `tilebox workflow build-release`, `tilebox workflow publish-release`, `tilebox workflow deploy-release`, `tilebox workflow undeploy-release` |
| `docs` | Search Tilebox documentation from the CLI. | `tilebox docs search "<query>"` |
| `parallel` | Run a shell command multiple times in parallel. | `tilebox parallel -n <count> -- <command> [args...]` |
| `upgrade` | Upgrade or reinstall the Tilebox CLI. | `tilebox upgrade`, `tilebox upgrade --version <version>`, `tilebox upgrade --force` |
| `agent-context` | Describe command metadata and output schemas for agents. | `tilebox agent-context`, `tilebox agent-context job list --output-schema` |

## Safety And Verification

- For destructive actions, such as `cluster delete`, confirm intent unless the user explicitly asked for the action.
- When a command fails, read the error text first. Validation errors usually name the exact flag or argument to fix. Otherwise refer to the `agent-context` for the command.