--- name: tilebox-quickstart description: Installs or updates the Tilebox CLI and agent skills, configures API access, and verifies authentication. Use when onboarding a coding agent to Tilebox or repairing its setup. --- # Tilebox quickstart Set up Tilebox in the environment where the agent will run commands. Install or update the CLI and the official [Tilebox skills](https://github.com/tilebox/skills), help the user configure authentication, then verify with `tilebox whoami`. ## Before starting This skill requires a coding agent with terminal execution and file-editing tools, such as Amp, Codex, Claude Code, or Cursor. If you are in a chat-only LLM interface such as ChatGPT or claude.ai without these capabilities, **stop**. Tell the user to open this skill in a coding agent such as Codex or Claude Code. Do not suggest MCP or pretend to have run commands. Start with a short checklist: “I'll install or update the Tilebox CLI and skills, check your API key, and verify your connection. I won't create or run any Tilebox resources yet.” If the user already requested setup, proceed without another confirmation. Respect any permissions required by the agent's environment. Reuse choices already established in the conversation, including the target environment, organization, and intended workflow. Ask only for missing information; do not ask the user to repeat or reconfirm an explicit choice unless verification reveals a conflict. Carry these choices into any restart checkpoint and the workflow-skill handoff after the user agrees to proceed. Explain each step briefly and perform the work you can. Pause when the user needs to supply a secret or grant permission, then resume from that step. Never claim success for a step you could not verify. Before a restart or handoff, give the user a brief, secret-free checkpoint: completed steps, verified executable paths, whether skills need reloading, and the next unfinished step. When resuming in the same environment, recheck availability and continue from that step; do not rerun a successful installation just because the agent restarted. Start installation again only for a new setup, an explicit update request, a changed environment, or an incomplete installation. Only local setup changes and read-only Tilebox commands are in scope. Do not create, update, delete, submit, retry, cancel, deploy, or undeploy Tilebox resources. Do not start a workflow until the user agrees. ## 1. Install or update the CLI and skills Inspect the actual command environment: operating system, CPU architecture, shell, writable home directory, and available tools. Do not assume that the agent's shell matches the user's shell or that a remote agent shares the user's computer. The wizard supports macOS and Linux on x86-64 or ARM64. On Windows, run the agent and wizard inside WSL with a supported Linux distribution; Git Bash alone is not enough. For another unsupported system, help the user choose a supported local, remote, or container environment and resume there. Do not claim native support or install into a different environment from the one the agent uses. Check for `sh`, `tar`, `curl` or `wget`, `sha256sum` or `shasum`, and `npx`. Skills installation requires Node.js with npm (`npx`); if missing, use the environment's existing version manager or the official instructions at https://nodejs.org/. Respect package-management policies and request approval if required. Do not use `sudo` by default. For a new setup or update request, run the wizard **even if Tilebox is already installed**. It installs the latest CLI and refreshes the official skills from https://github.com/tilebox/skills. It also installs `uv` for Python workflow development if missing. Use `--yes` to avoid an interactive prompt in agent terminals: ```sh curl -fsSL https://install.tilebox.com/wizard.sh | sh -s -- --yes ``` If only `wget` is available: ```sh wget -qO- https://install.tilebox.com/wizard.sh | sh -s -- --yes ``` Read the output and verify each component; a pipeline exit code alone does not prove installation succeeded. If downloads, permissions, or dependencies fail, address the specific failure and rerun the wizard. Never disable TLS verification. In an offline or locked-down environment, explain the blocker and the required access or supported environment instead of retrying indefinitely. If installer or command behavior differs from this skill, consult the installed CLI's `--help`, `tilebox agent-context`, and the documentation index at https://tilebox.com/docs/llms.txt. Follow links to the relevant installation or authentication documentation rather than inventing commands. For uv installation paths and options, use https://docs.astral.sh/uv/reference/installer/. If these sources are unreachable, report the blocker and the next action needed. The CLI normally installs to `$HOME/.local/bin/tilebox`; `TILEBOX_INSTALL_DIR` overrides this. Check whether `TILEBOX_VERSION` pins an older version or `TILEBOX_DOWNLOAD_BASE_URL` selects a custom source. Do not silently override deliberate pins or organizational configuration; explain if they prevent updating to the latest release. ### Make both executables available An installer runs in a child process and cannot update the agent's current `PATH`. Shell-profile changes also do not necessarily affect its noninteractive command tools. Resolve this for **both `tilebox` and `uv`**, without reinstalling merely because a command is not found: 1. Use the executable locations reported by the installers. For Tilebox, check `${TILEBOX_INSTALL_DIR:-$HOME/.local/bin}/tilebox`. If the wizard reused an existing uv, resolve it with the shell's command lookup (`command -v uv` in POSIX shells). Otherwise use uv's reported install directory; respect `UV_INSTALL_DIR`, `UV_UNMANAGED_INSTALL`, and environment-specific executable directories instead of assuming uv shares Tilebox's directory. 2. Verify the quoted absolute paths directly with `tilebox --help` and `uv --version`, substituting those paths for the command names. Record the paths without credentials. 3. Prepend both verified directories to `PATH` in the environment that actually runs agent commands, preserving the existing `PATH`. If both installed to the default directory, the POSIX-shell command is: ```sh export PATH="$HOME/.local/bin:$PATH" ``` For different directories, prepend each verified directory once. Adapt the syntax to the actual shell. Clear stale command lookup caches if necessary (`hash -r` in Bash, `rehash` in Zsh), then confirm command lookup selects the verified executables rather than older installations or shell aliases. 4. If tool calls use fresh shells, set `PATH` through the agent's supported environment configuration or include the same PATH setup in each command call. Quoted absolute paths are a reliable fallback for direct commands; commands that launch subprocesses may still require both directories on `PATH`. Test lookup in a **new tool call** before relying on bare command names. For persistence, use the agent or hosting environment's PATH configuration. For a local interactive shell, follow the installer's shell-specific instructions and avoid duplicate profile entries. Do not source an entire user profile into an unrelated shell just to pick up PATH changes. A restart is needed only if the agent cannot refresh its command environment; preserve the checkpoint first. Verify: ```sh tilebox --help tilebox agent-context uv --version ``` Confirm that the installed Tilebox `SKILL.md` files are present and readable in the skill directories reported by the installer. Reload skills through the agent's supported mechanism. If the agent only discovers skills at startup, ask the user to restart it and resume this quickstart; do not assume that installed skills are already loaded. Use the installed `tilebox` routing skill and `tilebox-cli` skill for subsequent work. ## 2. Check for an existing API key Check for a nonempty `TILEBOX_API_KEY` **in the agent's command environment**, without displaying its value. In a POSIX shell: ```sh if [ -n "${TILEBOX_API_KEY:-}" ]; then printf 'TILEBOX_API_KEY is set\n' else printf 'TILEBOX_API_KEY is missing\n' fi ``` Adapt the presence check to the shell if necessary. Never print the key, dump the environment, enable shell tracing, or place a real key in tool arguments, chat, logs, or source control. If the key is set, skip key creation and proceed to verification. If the user already configured a key through their agent's secret manager or a private environment file, help them load it into the command environment without reading its value into the conversation. A `.env` file is not automatically loaded by every shell or agent. If no key is available, send the user to: https://console.tilebox.com/settings/api-keys Ask them to sign in or create an account, select the intended organization, and create a key with the smallest permissions needed for their intended work. Keep this browser action with the user, then guide them through the next step. Do not ask them to paste the key into chat. ## 3. Configure the key in the agent's environment Prefer the agent or hosting environment's secret settings when available. For a remote agent, container, CI job, or ephemeral sandbox, configure `TILEBOX_API_KEY` there, not just in the user's local terminal. Explain whether the configuration survives a restart or a rebuilt environment. For a local agent, identify the user's actual shell and give **only the matching instructions**. `$SHELL` is a hint about the login shell, not proof of the shell running an agent tool. The user must enter the key privately in their own terminal; hidden-input examples below keep it out of command history. ### Bash ```bash read -r -s -p 'Tilebox API key: ' TILEBOX_API_KEY printf '\n' export TILEBOX_API_KEY ``` ### Zsh ```zsh read -r -s 'TILEBOX_API_KEY?Tilebox API key: ' printf '\n' export TILEBOX_API_KEY ``` ### Fish ```fish read --silent --prompt-str 'Tilebox API key: ' --global --export TILEBOX_API_KEY ``` For another shell, provide its documented equivalent or use the environment's secret settings. Do not run Bash-specific commands under `sh`, Fish, or PowerShell. On Windows with WSL, set the key inside the WSL environment running the agent. These terminal examples set the key for that shell and its future child processes only. **An already-running agent cannot inherit an environment variable exported later in another terminal.** Have the user restart the agent from the configured terminal, or update its secret settings and restart its command environment. Preserve progress so setup can resume with verification. If the user wants persistence, prefer a secret manager. Alternatively, guide them to privately edit the startup file their shell actually loads: `${ZDOTDIR:-$HOME}/.zshrc` for interactive Zsh, `~/.bashrc` for interactive non-login Bash, or the active login profile (often `~/.bash_profile` on macOS). Add `export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY"`, replacing the placeholder privately. For Fish, a user can use `set -Ux TILEBOX_API_KEY "$TILEBOX_API_KEY"` after the hidden-input command. Explain that these options store the secret in plaintext, protect the file, and avoid duplicate or conflicting definitions. Never put the key in a tracked project file. Reload the configuration in the appropriate shell and restart the agent if needed. Do not assume its noninteractive tools read shell startup files. Repeat the value-free presence check in the agent's actual environment before continuing. ## 4. Verify authentication Run this read-only command in the agent's command environment, using the newly installed CLI: ```sh tilebox whoami ``` Confirm that it succeeds and shows the intended user and organization. Do not use `tilebox dataset list` as the authentication test; a working key need not have dataset-list permissions. If the CLI reports a missing key, return to environment configuration. For an invalid, expired, or revoked key, guide the user to replace it in the Console. For an unexpected organization, ask the user to select the intended organization's key. Distinguish authentication errors from network, proxy, TLS, or service failures; do not replace a key just because a request could not reach Tilebox. If `whoami` is unavailable, check that the updated binary is the one being executed. Before declaring success, report a short checkpoint based on observed results: - CLI: executable path and whether installation/update succeeded or a deliberate version pin was retained. - uv: verified executable and version; the wizard may have reused an existing installation rather than updated it. - Skills: installed/refreshed and available to this agent, or still awaiting a reload. - Authentication: user and organization returned by `tilebox whoami`, without credentials. Only after the CLI, uv, skills, and authentication are verified, congratulate the user briefly: “You're ready to use Tilebox! Your CLI and skills are available, and authentication is verified. Would you like to start building and running your first workflow?” Say “up to date” only when the update was verified; do not use it for an intentionally pinned CLI. Wait for their answer. If they agree, load the installed Tilebox routing skill and follow its workflow guidance. If setup remains blocked, state what is complete and the single next action needed instead of claiming success.