# @stackbone/cli

The CLI for [Stackbone](https://stackbone.ai) — the marketplace and runtime for containerized AI agents.

> **Status:** `alpha`. The contract may break between releases. Pin a version or rely on the `alpha` dist-tag.

## Quick start

No install required — invoke the CLI through `npx`:

```bash
npx @stackbone/cli@alpha init my-agent
cd my-agent
npx @stackbone/cli@alpha dev
```

That's it. `init` scaffolds a new agent project (templates + Claude skill); `dev` runs a local control-plane emulator with Stackbone Studio at `http://localhost:4242` so you can iterate without publishing.

## Commands

| Command                      | What it does                                                           |
| ---------------------------- | ---------------------------------------------------------------------- |
| `stackbone init [name]`      | Scaffold a new Stackbone project from a template.                      |
| `stackbone dev`              | Run the local control-plane emulator + Stackbone Studio.               |
| `stackbone publish`          | Build, push, and publish the current agent to Stackbone runtime.       |
| `stackbone login` / `logout` | Authenticate the CLI via the device-code flow (RFC 8628).              |
| `stackbone whoami`           | Show the active user and organization.                                 |
| `stackbone current`          | Print the organization currently linked to this session.               |
| `stackbone link`             | Link the current directory to an existing organization + agent.        |
| `stackbone list`             | List organizations the current user owns.                              |
| `stackbone metadata`         | Agent-friendly snapshot of the workspace state.                        |
| `stackbone db <subcmd>`      | Manage the local emulator database (migrations, queries).              |
| `stackbone docs <topic>`     | Print Stackbone documentation inline. Run with no args to list topics. |

Run any command with `--help` for the full flag reference, or `npx @stackbone/cli@alpha docs cli` for the inline documentation.

## Requirements

- Node.js `>= 20.18.0`
- Docker (only required for `stackbone dev` — the emulator runs Postgres + Redis + MinIO locally)

## Links

- Documentation: <https://docs.stackbone.ai>
- Marketplace: <https://stackbone.ai>
- Issues & feedback: report via `stackbone docs feedback` once authenticated, or contact the team directly.

## License

Proprietary. © Stackbone.
