tilebox-cli

使用 Tilebox CLI

每当与 tilebox 命令行工具交互时，都使用此技能。优先使用机器可读输出和命令架构发现，以确保自动化稳定可靠。

面向 Agent 的核心规则

• 在 Agent 工作流中，只要命令支持 --json，就始终传入该选项；绝不要传入 --interactive。
• 在依赖命令的输出结构之前，先运行 tilebox agent-context <command path> --output-schema。
• 除非用户明确要求使用 --api-key，否则通过 TILEBOX_API_KEY 传递身份验证信息。
• 仅在面向非默认 API 环境时使用 --api-url。
• 对于分页命令，从 JSON 输出中读取 next_cursor，并将其作为 --cursor 传回，直到该值为空。
• 如果行为不明确，使用 tilebox agent-context <command>。

身份验证和 API URL

CLI 可通过以下方式进行身份验证：

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

也可按命令传入：

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

默认 API 为 https://api.tilebox.com。在面向预发布或本地环境时覆盖此设置：

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

如果缺少身份验证信息，命令会返回类似验证错误的用法错误。安装后，或在调查身份验证失败问题时，使用 tilebox account get --json 验证 API 端点和当前凭据。不要打印或记录 API 密钥。

JSON 输出

在 Agent 工作流中，对支持的命令始终使用 --json：

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

即使在伪终端中，--json 也会输出紧凑、无样式且不分页的内容。人类可读输出可能包含终端样式，而 --interactive 可能会启动分页器，因此 Agent 不应使用这两者。

将 JSON 输出与 jq 结合使用

使用 jq 快速提取字段、筛选内容和构建 Shell 管道。让 tilebox 负责输出结构化内容，让 jq 负责选择所需字段。尽量将中间输出和最终输出保留为 JSON 对象或数组。

示例：

# 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}]}'

如果脚本在缺少必需值时应失败，请使用 jq -e：

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

发现命令和输出架构

使用 agent-context 检查可用命令、参数、标志、说明和输出架构。 它始终返回 JSON；不要在 agent-context 命令中添加 --json。

描述整个 CLI：

tilebox agent-context

描述单个命令：

tilebox agent-context job list --output-schema

典型工作流：

1. 运行 tilebox agent-context <command path> --output-schema。
2. 查看必需的参数/标志以及 JSON 输出架构。
3. 使用 --json 运行命令。
4. 根据架构解析字段。

搜索 Tilebox 文档

使用 tilebox docs search 浏览并检索 docs.tilebox.com 中的相关摘录，无需离开 CLI。当你需要最新的产品文档、概念指导、示例或 SDK/API 详细信息，以便选择命令标志或实现细节时，此命令很有用。

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

使用包含产品领域以及你关注的具体概念、命令、SDK 类型或错误的自然语言短语进行搜索。优先使用范围明确的查询，而不是宽泛的查询：

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

以下情况请使用文档搜索：

• agent-context 告知了 CLI 的结构，但你需要概念文档或示例。
• 你需要了解 CLI 帮助中可能不明显的 SDK 或 API 行为。
• 编写面向用户的文档前，你想确认当前文档中的术语。

不要使用文档搜索查找命令输出架构；请使用 tilebox agent-context <command path> --output-schema。

分页

某些命令会返回包含 next_cursor 字段的分页结果。将其作为 --cursor 传入，以获取下一页结果。循环执行，直到 next_cursor 为空。例如：

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

翻页时保持筛选条件和排序顺序不变。只更改 --cursor。

安装 CLI

设置向导会安装 Tilebox CLI 和 Agent Skills；如果尚未安装 uv，还会提供安装选项：

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

CLI 安装程序会下载已发布的二进制文件、验证校验和，并默认安装到 $HOME/.local/bin。如需仅安装 CLI 并指定自定义安装目录：

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

安装指定版本：

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

确保安装目录位于 PATH 中，设置 TILEBOX_API_KEY，然后验证安装和身份验证：

tilebox account get --json

更新 CLI

对于已发布且安装在 PATH 中的二进制文件，请使用内置的升级命令：

tilebox upgrade --json

安装指定版本：

tilebox upgrade --version 0.3.1 --json

强制重新安装：

tilebox upgrade --force --json

注意：

• tilebox upgrade 需要 sh 和 curl。
• 不支持开发构建版本或 Windows。
• 如果二进制文件安装在自定义目录中，请根据需要设置 TILEBOX_INSTALL_DIR。

常用命令类别

当前 CLI 提供以下顶层命令类别。CLI 变更后运行 tilebox agent-context，以刷新此列表。

类别	用途	常用命令
account	查看当前账户、超额用量和订阅层级。	tilebox account get、tilebox account subscription、tilebox account usage、tilebox whoami
automation	查看工作流自动化和存储位置。	tilebox automation list、tilebox automation get <automation-id>、tilebox automation storage-locations
cluster	管理工作流计算集群。	tilebox cluster list、tilebox cluster get <cluster-slug>、tilebox cluster create <name>、tilebox cluster delete <cluster-slug>
dataset	创建、更新、查看和查询数据集，查找数据点，并为数据集生成类型。	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	管理数据集中的集合。	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	提交、监控、调试、重试、等待和取消工作流任务。	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	初始化、创建、查看、构建、发布、部署和取消部署工作流版本。	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	通过 CLI 搜索 Tilebox 文档。	tilebox docs search "<query>"
parallel	并行运行多次 shell 命令。	tilebox parallel -n <count> -- <command> [args...]
upgrade	升级或重新安装 Tilebox CLI。	tilebox upgrade、tilebox upgrade --version <version>、tilebox upgrade --force
agent-context	为 Agent 描述命令元数据和输出架构。	tilebox agent-context、tilebox agent-context job list --output-schema

安全与验证

• 对于 cluster delete 等破坏性操作，除非用户明确要求执行，否则请先确认其意图。
• 命令失败时，先阅读错误文本。验证错误通常会指出需要修正的具体标志或参数。否则，请参阅该命令的 agent-context。