# studio

> List the Dev Studio workflows and prepare a read-only context bundle for one of them, so your assistant can run it with the exact instructions that shipped in your project.

Canonical: https://bmad-plus.rochetta.fr/docs/reference/cli-studio/
Language: en
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

BMAD+ documentation › [Reference](https://bmad-plus.rochetta.fr/docs/reference/) › studio

Dev Studio is the pack with six personas (Miriam, Huldah, Yosef, Rachel, Bezalel, Oholiab) and 38 workflows such as `product-brief`, `validate-prd` or `investigate`. A workflow is a Markdown procedure that your assistant follows. `bmad-plus studio` does not run anything: `list` shows the catalog, and `prepare` gathers everything the assistant needs for one workflow (the configuration, the shipped instructions, the files you point to) into one bundle, with a hash for every file. It is for people who want a reproducible start, or a script that hands the bundle to an assistant.

<a id="synopsis"></a>
## Synopsis

**In your project terminal**

```sh
npx bmad-plus studio list [--json] [-d <path>]
npx bmad-plus studio prepare <workflow> [--request <text>] [--input <file> ...] [--json] [-d <path>]
```

**Arguments and options of studio**

| Flag | Argument | Default | What it does |
| --- | --- | --- | --- |
| `<action>` | `list` or `prepare` | required | Anything else fails with `Use studio list or studio prepare WORKFLOW.` |
| `[workflow]` | workflow id or alias | none | Required by `prepare`, refused by `list`. Aliases `bmad-<id>` and `bmad-plus-<id>` also work. |
| `-d, --directory <path>` | folder | current folder | Installed project to read. |
| `--request <text>` | text | empty | Task scope for the assistant, up to 256 KiB. |
| `--input <file>` | project-relative file | none | Repeatable, at most 32 files. Each must be a UTF-8 text file of at most 256 KiB inside the project. |
| `--json` | - | off | Print the complete bundle as JSON instead of the text summary. |

<a id="reads-writes"></a>
## What it reads and writes

- Reads `.agents/skills/pack-dev-studio/` (the catalog `shared/catalog.json`, the persona file, the workflow file and the resources it links to), `_bmad/config.yaml`, your `--input` files, and the previous report if one exists.
- Writes nothing. Not the report, not a cache, not the configuration. The report path it proposes is `<output_folder>/dev-studio/<workflow-id>.md` (by default `_bmad-output/dev-studio/<workflow-id>.md`); your assistant writes it later.
- Opens no network connection and starts no process. The bundle is capped at 2 MiB.
- Needs the Dev Studio pack: `npx bmad-plus install --packs core,dev-studio`.

<a id="input-kinds"></a>
### Input kinds

Each workflow declares what it needs. When that is missing, `prepare` still prints the bundle but reports `needs-input` and exits with code 2, so a script can ask for more before calling the assistant.

**Input kinds in the catalog**

| Kind | Needs | Examples |
| --- | --- | --- |
| `request` | A `--request` text or at least one `--input` file. | `product-brief`, `create-prd`, `create-architecture` |
| `project` | A `--request` text or at least one `--input` file. | `investigate`, `quick-dev`, `code-review` |
| `artifact` | At least one `--input` file. | `validate-prd`, `edit-prd`, `dev-story` |
| `none` | Nothing. | declared by the catalog for workflows that need no input |

<a id="exit-codes"></a>
## Exit codes

**Exit codes of studio**

| Code | Meaning |
| --- | --- |
| 0 | `list` succeeded, or `prepare` status is `ready`. |
| 2 | `prepare` status is `needs-input`: the workflow lacks its request or its input file. |
| 1 | Error: pack not installed, unknown workflow, invalid input, unreadable configuration. With `--json` the error is printed as `{"schemaVersion":1,"status":"error","error":"..."}`. |

<a id="real-output"></a>
## Reading the output

**List the catalog (first lines)**

```text
$ npx bmad-plus studio list
product-brief (analyst-agent; input: request)
prfaq (analyst-agent; input: request)
document-project (tech-writer-agent; input: project)
market-research (analyst-agent; input: request)
domain-research (analyst-agent; input: request)
technical-research (analyst-agent; input: request)
create-prd (pm-agent; input: request)
prd (pm-agent; input: request)
edit-prd (pm-agent; input: artifact)
validate-prd (pm-agent; input: artifact)
...
investigate (dev-agent; input: project)
# The real list has 38 workflows; the lines marked “...” are omitted here.
```

Output captured from a real run. Source: Replayed with the 0.23.0 package (Core and Dev Studio packs) in a throwaway project; lines omitted where marked

**Prepare a workflow that lacks its input**

```text
$ npx bmad-plus studio prepare validate-prd
validate-prd: needs-input — prepared for the host, not executed.
Project: /work/app
Request: (none supplied)
Resolved configuration:
{
  "user_name": "Developer",
  "communication_language": "English",
  "document_output_language": "English",
  "output_folder": "_bmad-output",
  "project_name": "app"
}
Defaulted fields: (none)
Proposed report: _bmad-output/dev-studio/validate-prd.md
Supply a project artifact with --input RELATIVE_FILE.

--- shared/execution.md (b8152ec5057fc79749aa7b0823fa35c241c6a0c3f13d12716fa3aae11bcbf354) ---
...
# Exit code 2. The values shown depend on your _bmad/config.yaml; the long instruction bodies that follow are omitted (“...”).
```

Output captured from a real run. Source: Replayed with the 0.23.0 package (Core and Dev Studio packs) in a throwaway project; the project path is replaced by /work/app and the long instruction bodies are omitted

The text summary prints, in order: the workflow and its status, the project folder, the request, the resolved configuration, which configuration fields fell back to a default, the proposed report path, what is still missing, then each instruction file and each input file with its SHA-256. If a report already exists at the proposed path, its content follows under “Continue existing report”, so the assistant resumes instead of starting over. With `--json`, the same data is one object with `schemaVersion`, `status` (`ready` or `needs-input`), `execution: "host-managed"`, `executed: false`, `catalogSha256`, `instructions`, `inputs` and `missingInputs`.

> **Note · Prepared is not executed** The bundle proves that the instructions were delivered and which bytes they were. It does not prove that the assistant followed them, and nothing in it writes the report or runs tests. Independent agents, browsing and command execution depend on your assistant.

<a id="errors"></a>
## Errors and what to do

Errors are printed as `Dev Studio: <message>` on the error stream.

**studio errors**

| Message | Cause | What to do |
| --- | --- | --- |
| `Dev Studio is not installed. Run bmad-plus install --packs core,dev-studio` | The folder has no `.agents/skills/pack-dev-studio`. | Install the pack, or pass `--directory` for the right project. |
| `Use studio list or studio prepare WORKFLOW.` | Unknown action, `list` with a workflow, or `prepare` without one. | Check the synopsis above. |
| `Unknown Dev Studio workflow: <name>` | The name is neither a workflow id nor an alias. | Run `studio list` and copy an id. |
| `Invalid or oversized workflow inputs` | The request is over 256 KiB or more than 32 `--input` files were given. | Shorten the request, pass fewer files. |
| `Resource is not bounded text: <file>` | An input is missing, binary, or larger than 256 KiB. | Point to a smaller UTF-8 text file inside the project. |
| `Expected a portable relative file path: <file>` | The `--input` path is absolute, has `..`, a drive letter or other unsupported characters. | Use a path relative to the project, with `/` separators. |
| `Prepared context exceeds 2 MiB` | Instructions, inputs and previous report together are too big. | Pass fewer or smaller inputs. |
| `_bmad/config.yaml: <key> must be a nonempty string` | A known key in the configuration is empty or not text. | Fix the value; see the configuration page. |
| `Dev Studio catalog disagrees with registry routes` or `Unsupported Dev Studio catalog` | The installed pack files were edited or are incomplete. | Run `doctor`, then reinstall or update the pack. |

<a id="examples"></a>
## Examples

<a id="example-cli-studio-brief-from-request"></a>
### A product brief from a one-line request

Dev Studio is installed. You want Miriam to start from a precise scope, and you want the exact instructions recorded by hash.

**In your AI assistant**

```text
Miriam, use product-brief to define the smallest useful issue triage tool for our support team. If the CLI is available, run `npx bmad-plus studio prepare product-brief --request "Define the smallest useful issue triage tool" --json` first and work from that bundle.
```

**What you should get** The command prints a bundle with status `ready`, `executed: false`, the proposed report path `_bmad-output/dev-studio/product-brief.md`, and the shipped instructions with their hashes. Miriam then follows the `product-brief` procedure and writes the report at that path; the command itself wrote nothing.

<a id="example-cli-studio-validate-prd"></a>
### Validate a PRD you already have

`validate-prd` is an `artifact` workflow: it needs the file to validate.

**In your AI assistant**

```text
Yosef, validate-prd on docs/prd.md. Prepare the context with `npx bmad-plus studio prepare validate-prd --input docs/prd.md --json` and report findings only when you can point at the text that supports them.
```

**What you should get** Without `--input` the command would print `needs-input` and exit 2. With it, the status is `ready`, the file appears under `inputs` with its SHA-256, and the proposed report is `_bmad-output/dev-studio/validate-prd.md`. Yosef validates against that exact file content.

**See also**

- [CLI overview and exit codes](https://bmad-plus.rochetta.fr/docs/reference/cli-overview/)
- [install: add the dev-studio pack](https://bmad-plus.rochetta.fr/docs/reference/cli-install/)
- [doctor checks the pack resources](https://bmad-plus.rochetta.fr/docs/reference/cli-doctor/)
- [The configuration file](https://bmad-plus.rochetta.fr/docs/reference/config-yaml/)
- [Troubleshooting](https://bmad-plus.rochetta.fr/docs/faq/troubleshooting/)

[BMAD+ documentation](https://bmad-plus.rochetta.fr/docs/) · [Reference](https://bmad-plus.rochetta.fr/docs/reference/)

[Source on GitHub](https://github.com/lrochetta/BMAD-PLUS)