tilebox-cli

Tilebox CLI の使用

tilebox コマンドラインツールを操作する際は、必ずこのスキルを使用してください。自動化の堅牢性を保つため、機械可読な出力とコマンドスキーマの確認を優先してください。

エージェント向けの基本ルール

• コマンドが対応している場合、エージェントのワークフローでは必ず --json を指定してください。--interactive は指定しないでください。
• コマンドの出力形式を前提とする前に、tilebox agent-context <command path> --output-schema を使用してください。
• ユーザーが明示的に --api-key の使用を求めた場合を除き、認証には TILEBOX_API_KEY を渡してください。
• --api-url は、デフォルト以外の API 環境を対象にする場合にのみ使用してください。
• ページネーションのあるコマンドでは、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 出力

エージェントのワークフローでは、対応しているコマンドに必ず --json を使用してください。

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

--json は、疑似ターミナル上でも、コンパクトでスタイルのないページネーションなしの出力を生成します。人間向けの出力にはターミナルの装飾が含まれることがあり、--interactive はページャーを起動する場合があるため、エージェントはいずれも使用しないでください。

JSON 出力と jq の組み合わせ

フィールドの抽出、フィルタリング、シェルパイプラインには jq を使用してください。構造化出力は 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

1 つのコマンドを説明します。

tilebox agent-context job list --output-schema

一般的なワークフロー：

1. tilebox agent-context <command path> --output-schema を実行します。
2. 必須の引数／フラグと JSON 出力スキーマを確認します。
3. --json を指定してコマンドを実行します。
4. スキーマに従ってフィールドを解析します。

Tilebox ドキュメントの検索

tilebox docs search を使用すると、CLI を離れることなく docs.tilebox.com を閲覧し、関連する抜粋を取得できます。コマンドのフラグや実装の詳細を選ぶ前に、最新の製品ドキュメント、概念的なガイダンス、例、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	シェルコマンドを複数回並列に実行します。	tilebox parallel -n <count> -- <command> [args...]
upgrade	Tilebox CLI をアップグレードまたは再インストールします。	tilebox upgrade、tilebox upgrade --version <version>、tilebox upgrade --force
agent-context	エージェント向けにコマンドのメタデータと出力スキーマを説明します。	tilebox agent-context、tilebox agent-context job list --output-schema

安全性と確認

• cluster delete などの破壊的な操作では、ユーザーから明示的に依頼されていない限り、実行の意図を確認してください。
• コマンドが失敗した場合は、まずエラーメッセージを確認してください。検証エラーには通常、修正が必要なフラグまたは引数が明記されています。それ以外の場合は、そのコマンドの agent-context を参照してください。