# Playbooks CLI Commands > The soat CLI commands for the Playbooks module, with usage and every option, generated from the OpenAPI spec. # Playbooks Commands See [Playbooks module docs](../../modules/playbooks) for permissions and data model. ### `soat list-playbooks` List playbooks - Method: `GET` - Path: `/api/v1/playbooks` #### Usage ```bash soat list-playbooks ``` #### Options ##### `--project-id` Project ID (required if not using project key auth) - Source: `query` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ### `soat create-playbook` Create a playbook - Method: `POST` - Path: `/api/v1/playbooks` #### Usage ```bash soat create-playbook --name --definition ``` #### Options ##### `--project-id` Project ID (required if not using project key auth) - Source: `body` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--name` Human-readable name, unique per project - Source: `body` - Required: yes - Type: `string` - Example: `client-pricing` ##### `--description` What the playbook is for - Source: `body` - Required: no - Type: `string \| null` ##### `--definition` The nodes and how their inputs are sourced - Source: `body` - Required: yes - Type: `object` ##### `--version-label` Optional tag for version 1, e.g. `initial` - Source: `body` - Required: no - Type: `string` - Example: `initial` ### `soat validate-playbook` Validate a playbook definition - Method: `POST` - Path: `/api/v1/playbooks/validate` #### Usage ```bash soat validate-playbook --definition ``` #### Options ##### `--definition` The definition to check - Source: `body` - Required: yes - Type: `object` ### `soat get-playbook` Get a playbook - Method: `GET` - Path: `/api/v1/playbooks/{playbook_id}` #### Usage ```bash soat get-playbook ``` #### Options This command has no options. ### `soat update-playbook` Update a playbook - Method: `PATCH` - Path: `/api/v1/playbooks/{playbook_id}` #### Usage ```bash soat update-playbook ``` #### Options ##### `--name` Human-readable name, unique per project - Source: `body` - Required: no - Type: `string` ##### `--description` What the playbook is for - Source: `body` - Required: no - Type: `string \| null` ##### `--definition` Replaces the whole definition; a change archives a new version - Source: `body` - Required: no - Type: `object` ##### `--version-label` Optional tag for the version this write archives. Ignored when the write changes no definition, since no version is archived. - Source: `body` - Required: no - Type: `string` ##### `--expected-version` Refuses the write unless the playbook is at this version. - Source: `body` - Required: no - Type: `unknown` ### `soat delete-playbook` Delete a playbook - Method: `DELETE` - Path: `/api/v1/playbooks/{playbook_id}` #### Usage ```bash soat delete-playbook ``` #### Options This command has no options. ### `soat list-playbook-versions` List a playbook's versions - Method: `GET` - Path: `/api/v1/playbooks/{playbook_id}/versions` #### Usage ```bash soat list-playbook-versions ``` #### Options This command has no options. ### `soat get-playbook-version` Fetch an archived playbook version - Method: `GET` - Path: `/api/v1/playbooks/{playbook_id}/versions/{version}` #### Usage ```bash soat get-playbook-version ``` #### Options This command has no options. ### `soat restore-playbook-version` Restore an archived playbook version - Method: `POST` - Path: `/api/v1/playbooks/{playbook_id}/versions/{version}/restore` #### Usage ```bash soat restore-playbook-version ``` #### Options ##### `--label` Optional tag for the new version. Defaults to `restored from vN`. - Source: `body` - Required: no - Type: `string` - Example: `rollback` ### `soat create-playbook-case` Create a case - Method: `POST` - Path: `/api/v1/playbooks/{playbook_id}/cases` #### Usage ```bash soat create-playbook-case --subject ``` #### Options ##### `--subject` Who or what the case is about, as you name it - Source: `body` - Required: yes - Type: `string` - Example: `ACME Ltda (CNPJ 12.345.678/0001-90)` ### `soat list-playbook-cases` List playbook cases - Method: `GET` - Path: `/api/v1/playbook-cases` #### Usage ```bash soat list-playbook-cases ``` #### Options ##### `--project-id` Project ID (required if not using project key auth) - Source: `query` - Required: no - Type: `string` - Example: `proj_V1StGXR8Z5jdHi6B` ##### `--playbook-id` Only the cases of this playbook - Source: `query` - Required: no - Type: `string` - Example: `pbk_V1StGXR8Z5jdHi6B` ##### `--automation-status` Only the cases in these automation statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`. - Source: `query` - Required: no - Type: `array` ### `soat get-playbook-case` Get a case - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}` #### Usage ```bash soat get-playbook-case ``` #### Options This command has no options. ### `soat delete-playbook-case` Delete a case - Method: `DELETE` - Path: `/api/v1/playbook-cases/{case_id}` #### Usage ```bash soat delete-playbook-case ``` #### Options This command has no options. ### `soat write-playbook-case-inputs` Write a case's inputs - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/inputs` #### Usage ```bash soat write-playbook-case-inputs --inputs > ``` #### Options ##### `--inputs` The writes, applied all or none - Source: `body` - Required: yes - Type: `array` ##### `--wait` Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away - Source: `body` - Required: no - Type: `boolean` - Default: `false` ### `soat get-playbook-case-missing` List what a node still needs - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/missing` #### Usage ```bash soat get-playbook-case-missing --node-id ``` #### Options ##### `--node-id` The ID of the node to reach, usually a final node - Source: `query` - Required: yes - Type: `string` - Example: `pricing` ### `soat list-playbook-case-entries` List a case's entries - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/entries` #### Usage ```bash soat list-playbook-case-entries ``` #### Options ##### `--node-id` Only the entries of this node - Source: `query` - Required: no - Type: `string` - Example: `revenue` ### `soat run-playbook-case-node` Run a node of a case - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/nodes/{node}/run` #### Usage ```bash soat run-playbook-case-node ``` #### Options ##### `--wait` Answer once the executor settles or parks instead of right away - Source: `body` - Required: no - Type: `boolean` - Default: `false` ### `soat list-playbook-case-executions` List a case's executions - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/executions` #### Usage ```bash soat list-playbook-case-executions ``` #### Options ##### `--node-id` Only the executions of this node - Source: `query` - Required: no - Type: `string` - Example: `revenue` ### `soat get-playbook-case-execution` Get an execution - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/executions/{execution_id}` #### Usage ```bash soat get-playbook-case-execution ``` #### Options This command has no options. ### `soat export-playbook-case-node` Export a final node - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/nodes/{node}/exports` #### Usage ```bash soat export-playbook-case-node ``` #### Options ##### `--transformations` The names of the transformations to render; every one the node declares when omitted - Source: `body` - Required: no - Type: `array` ##### `--revision` The output or confirmation of the node to render; its current output when omitted - Source: `body` - Required: no - Type: `integer` ##### `--wait` Answer once every export settles instead of right away. A tool call, `builtin` or MCP, always waits. - Source: `body` - Required: no - Type: `boolean` - Default: `false` ### `soat list-playbook-case-exports` List a case's exports - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/exports` #### Usage ```bash soat list-playbook-case-exports ``` #### Options ##### `--node-id` Only the exports of this node - Source: `query` - Required: no - Type: `string` - Example: `pricing` ##### `--transformation` Only the exports of this transformation - Source: `query` - Required: no - Type: `string` - Example: `proposal` ### `soat get-playbook-case-export` Get an export - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/exports/{export_id}` #### Usage ```bash soat get-playbook-case-export ``` #### Options This command has no options. ### `soat upgrade-playbook-case` Upgrade a case - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/upgrade` #### Usage ```bash soat upgrade-playbook-case ``` #### Options ##### `--version` The version to move the case to; the playbook's current one when omitted - Source: `body` - Required: no - Type: `integer` - Example: `2` ##### `--wait` Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away - Source: `body` - Required: no - Type: `boolean` - Default: `false` ### `soat list-playbook-case-upgrades` List a case's upgrades - Method: `GET` - Path: `/api/v1/playbook-cases/{case_id}/upgrades` #### Usage ```bash soat list-playbook-case-upgrades ``` #### Options This command has no options. ### `soat pause-playbook-case` Pause a case - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/pause` #### Usage ```bash soat pause-playbook-case ``` #### Options This command has no options. ### `soat resume-playbook-case` Resume a case - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/resume` #### Usage ```bash soat resume-playbook-case ``` #### Options This command has no options. ### `soat confirm-playbook-case-node` Confirm a node of a case - Method: `POST` - Path: `/api/v1/playbook-cases/{case_id}/nodes/{node}/confirmation` #### Usage ```bash soat confirm-playbook-case-node --decision --expected-revisions > ``` #### Options ##### `--decision` Whether the node's inputs, as read, are approved - Source: `body` - Required: yes - Type: `enum("approve", "reject")` ##### `--reason` Why the inputs were rejected; required on a rejection - Source: `body` - Required: no - Type: `string` - Example: `The revenue does not match the filed statement` ##### `--expected-revisions` Each of the node's inputs, by name, mapped to the revision read, or null for one read as unset - Source: `body` - Required: yes - Type: `object` - Example: `\{"revenue":3\}` ##### `--wait` Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away - Source: `body` - Required: no - Type: `boolean` - Default: `false`