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:

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

or per command:

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

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

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

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:

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

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:

tilebox agent-context

Describe one command:

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.

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:

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

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:

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

Customize the install directory:

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

Install a specific version:

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:

tilebox account get --json

Updating The CLI

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

tilebox upgrade --json

Install a specific release:

tilebox upgrade --version 0.3.1 --json

Force reinstall:

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.

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.