spectackl

Command-line interface to the Spectackl Public REST API — built for AI agents and operators who need programmatic access to artifacts, scenes and task executions without going through the web UI.

pipx install spectackl   # isolated venv, binary on PATH
# or
pip install spectackl

Upgrading

pipx install --force spectackl

--force rather than pipx upgrade, and rather than a bare pipx install. A bare install leaves an existing app untouched (pip inside its venv reports "Requirement already satisfied"), and pipx upgrade re-resolves whatever spec the app was first installed from — so an app installed once from a local path or a pin will keep reinstalling that, however many releases have been published since. --force discards the venv and resolves the latest release from PyPI. Under pip, the equivalent is pip install --upgrade spectackl.

Check what landed with spectackl --version. If it still reports the old number, pip's index cache is stale — add --pip-args="--no-cache-dir".

Quick start

spectackl init --api-key spc_… --backend-url https://api.spectackl.ai --project my-project
spectackl artifact list --json

API keys are managed in the Spectackl Admin Console. init writes .spectackl/settings.yaml in the current directory and a user-global ~/.config/spectackl/settings.yaml; both are created 0600 and neither should be committed.

What it does

Every command accepts --json for machine-readable output, and every command returns a documented exit code — 0 success, 10 auth required, 20 validation, 30 not found, 40 upstream unavailable, and so on — so scripts can branch on failures precisely rather than parsing text.

Designed for agents

Output is stable and parseable, errors are structured, and the exit-code scheme is part of the public contract. spectackl assets sync writes agent and skill definitions in the exact layout Claude Code reads, built from the same artifacts the platform provisions into a sandbox — so an agent invoked on a workstation is the one that runs in production.

Requirements

• Python 3.10+
• A Spectackl tenant and an API key (spc_ prefix)

Documentation

Full guide: https://docs.spectackl.ai

License

MIT