Metadata-Version: 2.4
Name: spectackl
Version: 0.0.1
Summary: CLI for the Spectackl Public REST API — for AI agents and operators
Author-email: Spectackl Engineering <engineering@spectackl.ai>
License: MIT
Project-URL: Homepage, https://spectackl.ai
Project-URL: Documentation, https://docs.spectackl.ai
Keywords: spectackl,cli,ai,agents
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"

# spectackl

Command-line interface to the [Spectackl](https://spectackl.ai) 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.

```bash
pip install spectackl
```

## Quick start

```bash
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

| Command | Purpose |
|---|---|
| `spectackl search <query>` | Hybrid full-text + semantic search across a project's content |
| `spectackl artifact` | Get, list, create and update artifacts |
| `spectackl relation` | Manage the artifact graph (`INCLUDES`, `DOCUMENTS`, `DEPENDS_ON`, …) |
| `spectackl context` | Inspect scenes (work contexts) and the artifacts they scope |
| `spectackl task` | Claim, progress and complete task executions |
| `spectackl assets sync` | Materialize the project's agents and skills into `./.claude/` |
| `spectackl rsync` | Reconcile artifact content with local files, in both directions |
| `spectackl daemon` | Run agent sessions on this machine |

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
