---
title: 'init'
description: 'Scaffold a new Stackbone workspace and link it to your organization.'
position: 6
---

# stackbone init

> `stackbone init` talks to the control plane, not to a running installation, so
> it takes no `--agent`. You must be signed in with
> [`stackbone login`](/docs/cli/reference/login) first: there is no offline `init`.
> `--json` prints the [standard envelope](/docs/cli/reference/conventions#json-output),
> and the codes at the bottom are the
> [shared exit codes](/docs/cli/reference/conventions#exit-codes).

```sh
stackbone init [dir] [--with empty|agent|workflow|workflow-agent]
```

Scaffold a new workspace. `init` is **workspace-first** and **links the
workspace** to your organization: it registers the workspace's identity in
the control plane and writes a `.stackbone/project.json` (so `dev`,
`link` and the management commands know which org to talk to). Alongside the
link it writes the workspace shell.

The shell is a multi-piece project:

- a `deep-agents/` folder (one agent per subfolder);
- a `workflows/` folder (one durable workflow per file), with its own
  `package.json` and `tsconfig.json`;
- a root `package.json` and `tsconfig.json`, plus a `pnpm-workspace.yaml` that
  installs `workflows/` as a package of the same workspace;
- an `.npmrc` (a hoisted `node_modules` layout so the runtime resolves one
  copy of each shared dependency);
- a `.gitignore`, a `README.md`, and an `AGENTS.md` and `CLAUDE.md` that brief
  your coding agent on the layout;
- the [Stackbone agent skills](/docs/home/get-started/coding-agents) and the docs
  MCP server, for the coding agents you tick in the prompt.

`--with` chooses an optional **first piece** scaffolded on top of the shell:

| `--with` value   | What it adds                                            |
| ---------------- | ------------------------------------------------------- |
| `empty`          | The shell only.                                         |
| `agent`          | One agent under `deep-agents/<name>/`.                  |
| `workflow`       | One durable workflow at `workflows/<name>.workflow.ts`. |
| `workflow-agent` | An agent **and** a workflow already wired to call it.   |

Every kind links the workspace, so all of them need you to be signed in.

| Flag               | Type    | Default | Description                                                                                                                                                                     |
| ------------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[dir]` positional | string  | derived | Target subdirectory for the workspace. Omit it and `init` creates a subdirectory named after the workspace slug.                                                                |
| `--with`           | string  | `empty` | First piece to scaffold: `empty`, `agent`, `workflow`, or `workflow-agent`.                                                                                                     |
| `--name`           | string  | derived | Workspace name (and the default name of the first piece). Lowercased into a slug, capped at 32 characters.                                                                      |
| `--yes` / `-y`     | boolean | `false` | Skip interactive prompts.                                                                                                                                                       |
| `--json`           | boolean | `false` | Emit the structured JSON envelope instead of the pretty UI.                                                                                                                     |
| `--force`          | boolean | `false` | Overwrite existing files in the target directory.                                                                                                                               |
| `--agents`         | string  | prompt  | Comma-separated coding agents to set up, e.g. `claude-code,cursor`. Skips the prompt. `--no-agents` sets nothing up. See [coding agents](/docs/home/get-started/coding-agents). |
| `--install`        | boolean | `true`  | Install the workspace dependencies after scaffolding: `pnpm install` when pnpm is on `PATH`, `npm install` otherwise. `--no-install` skips it.                                  |

> **Starters are gone from `init`.** Passing `--starter` or `--template` now
> prints a migration message and exits non-zero. Templates moved to a per-piece
> flag on [`add`](/docs/cli/reference/add)
> (`stackbone add workflow <name> --template <t>`).

**Interactive prompts**: `init` asks only when stdin is a terminal, `CI` is not
set in the environment, and you passed neither `-y` nor `--json`. It prompts for
the workspace name when you gave neither `[dir]` nor `--name`, shows a picker of
the `--with` kinds (`empty`, `agent`, `workflow`, `workflow-agent`), and ends
with a checklist of coding agents to set up. Any other run takes the derived
name and `--with empty`, and sets up **no** coding agents unless you pass
`--agents`.

**Dependency install**: after the files are written, `init` runs the first
install in the workspace, with `pnpm` when `pnpm --version` answers on `PATH`
and `npm` otherwise. The scaffold works the same with either (its `.npmrc`
pins a hoisted `node_modules` layout). The install is best-effort: a failure
prints the package manager's last lines as a warning, the command still exits
`0`, and the **Next steps** note keeps the `<pm> install` line for you to run.
`--no-install` skips the step, and then the note names `pnpm install`.

**JSON payload**

```jsonc
{
  "schema_version": 1,
  "workspace": { "name": "acme", "dir": "/abs/path" },
  "with": "agent", // the --with value
  "files_written": [
    /* every file written, sorted alphabetically */
  ],
  "agent": { "id": "...", "slug": "...", "name": "..." }, // the workspace's own control-plane identity
  "local_dev_installation": { "id": "...", "organization_slug": "..." },
  "agent_setup": {
    "ok": true,
    "selected": ["cursor"], // the coding agents you ticked, or []
    "steps": {
      "skills": "ok", // "ok" | "failed" | "skipped"
      // One entry for EVERY supported agent, always. The ones you did not tick read "skipped".
      "mcp": { "claude-code": "skipped", "cursor": "written" /* … */ },
    },
  },
  "dependencies": {
    "status": "installed", // "installed" | "failed" | "skipped"
    "package_manager": "pnpm", // "pnpm" | "npm" | null (null when skipped)
    // "error": "…" (present only when status is "failed")
  },
}
```

`agent` and `local_dev_installation` describe the workspace's own
control-plane registration, the single identity every `--with` kind shares.

**Exit codes**: `0` ok, `2` auth (not signed in), `1` generic (a file collision
without `--force`, an unknown `--with` value, or a removed `--starter` /
`--template` flag).

**Next**: grow the workspace with [`stackbone add`](/docs/cli/reference/add), then
run it with [`stackbone dev`](/docs/cli/reference/dev).