> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptingcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Playbooks

> Find playbook candidates, start and inspect runs, and configure automation for a product.

# Playbooks

Playbooks turn detected opportunities into steps such as detect, execute, review,
ship, and measure. Each run activates one intelligent-action candidate. Your
organization must have Playbooks enabled.

Every command requires `--scope <org-slug>/<product-slug>` (a dashboard URL also
works). Authenticate with `tpc auth login` first. Output defaults to a text table;
pass `--format json` for API data.

## Catalog and settings

```bash theme={null}
tpc playbooks list --scope acme/my-product
tpc playbooks set content-refresh --enabled=true --scope acme/my-product
tpc playbooks set content-refresh --auto-run=false --scope acme/my-product
tpc playbooks set content-refresh --autopilot=true --scope acme/my-product
```

`list` shows every playbook's ID, name, category, availability (`built` or `coming
soon`), enabled, auto-run, and Autopilot settings, and active run count. Missing settings show
`unset`; this does not imply a server default. Counts cover **only the latest 50
runs**, not all historical runs.

`set <playbook-id>` accepts `--enabled=true|false`, `--auto-run=true|false`, and
`--autopilot=true|false`. Provide at least one. Omitted fields stay unchanged;
explicit `false` is sent to the API. Enabling auto-run allows the server to start
runs automatically when eligible candidates appear. Autopilot publishes waiting
drafts without review, up to 3 pages a day per playbook; drafts over that limit,
and every draft while the product has no connected domain, wait for your review.
Coming-soon playbooks cannot execute yet.

## Find candidates and start a run

```bash theme={null}
tpc playbooks suggestions --scope acme/my-product
tpc playbooks run start --playbook content-refresh --candidate <candidate-id> --scope acme/my-product
```

`suggestions` reads the intelligent-actions bootstrap and lists available
candidates whose action type maps to a playbook. The text table includes the
candidate ID, playbook ID, action type, and title. An empty table means no matching
candidate was returned; detection may still be materializing.

`run start` executes the selected candidate. Use the playbook and candidate IDs
from `suggestions`. The server validates eligibility and rejects duplicate live
runs for the same activation with HTTP 409. Inspect existing runs before retrying.

## Inspect runs

```bash theme={null}
tpc playbooks runs --scope acme/my-product
tpc playbooks runs --playbook content-refresh --status needs_review --scope acme/my-product
tpc playbooks run get <run-id> --scope acme/my-product
```

`runs` returns the overview's latest 50 runs, newest first. `--playbook <id>` and
`--status <status>` filter that window locally; they do not fetch older runs.

Statuses are `running`, `needs_review`, `shipping`, `measuring`, `recovered`,
`not_recovered`, `completed`, `failed`, and `cancelled`. The first four are active.

`run get` shows the status, steps, measurement checkpoints, and errors. At review,
it links to the existing draft review page when the run resource identifies a
draft; otherwise it links to the product's review queue. Approve or reject there.
Playbooks has no separate CLI approval command. The engine observes draft review
and publication state.

Measured playbooks capture a baseline at start and checkpoints at day 7 and day 14
after shipping. They end `recovered` or `not_recovered`. Other runs can end
`completed`, `failed`, or `cancelled`.

## Cancel a run

```bash theme={null}
tpc playbooks run cancel <run-id> --scope acme/my-product
```

This requests cancellation of the playbook run. It does not promise to undo work
that has already executed or published.

## JSON output

```bash theme={null}
tpc playbooks list --scope acme/my-product --format json
tpc playbooks suggestions --scope acme/my-product --format json
tpc playbooks run get <run-id> --scope acme/my-product --format json
```

JSON unwraps the API's `data` without adding display fields:

* `list`: the overview object with `settings` and `runs`. The static catalog is in
  the text table; it is not added to the API response.
* `runs`: the filtered run array, preserving all run fields.
* `suggestions`: the filtered candidate array, preserving all candidate fields.
* `run get`, `run start`, `run cancel`: the run object, including steps and measurements.
* `set`: the saved setting object.

Review links are generated for text output. In JSON, a draft resource has
`resource.type = "agentic_document_draft"` and `resource.id` identifies the draft at
`/<org-slug>/p/<product-slug>/docs/review/<draft-id>`.

## Errors

HTTP 404 can mean Playbooks is not enabled for the organization or the scoped
resource does not exist. Check scope and IDs with `list` / `runs`, and ask your
organization administrator about access. HTTP 409 means the request conflicts
with current state; inspect runs before retrying. Authentication and permission
errors retain the server's explanation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.