Playbooks

Find and read

epismo playbook search --query "release review" --category operations
epismo -w acme playbook search "release review" --output table
epismo playbook search --category operations
epismo playbook resource list --kind cli
epismo playbook list --resource-kind cli --resource-ref github:epismoai/cli
epismo playbook get <playbook-id-or-reference>
epismo playbook version list <playbook-id>
epismo playbook version get <playbook-id> <version-id>
epismo playbook version archive <playbook-id> <version-id>

playbook get accepts a UUID or a playbook reference such as pb:alias and pb:handle/alias, and returns the playbook together with its open suggestions in the same read—free for a public playbook, one playbook get otherwise. Search supports text, category, page size, and cursor. Omit --query for a plain catalog listing ordered by most recent update. Use playbook resource list to discover resource references, then filter playbook list with --resource-kind and --resource-ref; do not combine those filters with a text query. Equivalent GitHub and npm URL and provider-specific forms are grouped together. Read the full definition—especially input schema, resource hints, and expected outputs—before using a result.

Create and publish

Create a definition file, then pass it to playbook create:

For workspace creation, including a saved default workspace, choose exactly one of --private, --team-ids "$TEAM_ID" (comma-separated IDs or a JSON array), or --access with complete settings. The same choices are private, teamIds, and access in --request JSON; do not combine them. Personal creation may omit sharing. Team selection grants editor access without adding redundant direct creator access.

{
	"ownerId": "<account-id>",
	"access": { "visibility": "restricted", "grants": { "<user-or-team-uuid>": "editor" } },
	"definition": {
		"schemaVersion": 1,
		"title": "Release review",
		"description": "Review a release before publication.",
		"category": "operations",
		"inputSchema": {
			"type": "object",
			"required": ["repository"],
			"properties": { "repository": { "type": "string" } }
		},
		"steps": [
			{
				"title": "Inspect the change",
				"instructions": "Review scope, tests, risks, and rollback plan.",
				"resourceHints": [
					{ "kind": "document", "ref": "https://example.com/release-policy" }
				],
				"expectedOutputs": [{ "title": "Decision and evidence", "format": "markdown" }]
			}
		]
	}
}

epismo playbook create --request @playbook.json
epismo playbook version publish <playbook-id> \
  --base-version-id <latest-version-id> --request @next-version.json

Omit IDs for new steps. Preserve an existing four-character ID only for the same logical step. Publication creates an immutable version; after a base-version conflict, fetch latest and merge your intent instead of changing only the base ID.

Archive a historical version when it should no longer be visible or available for new cases. Version numbers are not renumbered or reused, and the latest version cannot be archived. Existing cases pinned to an archived version continue to operate.

Draft

epismo playbook draft get <playbook-id>
epismo playbook draft save <playbook-id> --base-revision 0 --request @draft.json
epismo playbook draft publish <playbook-id>
epismo playbook draft discard <playbook-id>

A playbook has at most one draft, and only an existing playbook can have one—use playbook create for the first version. --base-revision is the revision you last read (0 for a new draft); a stale value is rejected, the same as a base-version conflict on publish. Anyone with playbook edit access can read and edit its draft; public readers and share links cannot. draft publish mints a version from the draft and discards it in the same step; draft discard throws it away instead.

Access and references

epismo playbook access get <playbook-id>
epismo playbook access set <playbook-id> --access '{"visibility":"public","grants":{"<user-or-team-uuid>":"editor"}}'
epismo playbook owner transfer <playbook-id> --owner-id <workspace-or-user-id>
epismo playbook alias set <playbook-id> <alias> [--owner-id <account-id>]
epismo playbook alias list <playbook-id> [--owner-id <account-id>]
epismo playbook alias delete <alias> [--owner-id <account-id>]
epismo playbook share "$PLAYBOOK_ID"
epismo playbook archive <playbook-id>

Playbooks and cases have an owning user or workspace account (ownerId), which is also the billing home. A personal owner has full rights; current owners and admins exercise ownership rights for a workspace. Other members need explicit user or team grants, or public visibility for published reads. Workspace membership alone grants no resource access. Removing a workspace member clears their direct grants on items owned by that workspace, including archived and completed items. If removal would leave any affected item without an explicit editor, add another user or team editor first, including on completed and archived items. Personal and other-workspace shares remain unchanged. Team and management authority follow current membership. Required SSO applies to members; non-member direct shares use normal Epismo authentication. Cross-workspace team sharing verifies the participation workspace's SSO. Lists use explicit access and supported public visibility; ownership alone does not include an item.

Viewers can read shared content but cannot edit; playbook drafts require editing. Editors may change content and sharing, retain at least one explicit editor when changing grants, and archive or restore. Ownership is required for affiliation transfer, maintainer changes, permanent case deletion, and historical playbook version archival. assignedTo expresses responsibility and never grants rights. A newly selected assignee or maintainer must already have editing access and, for a workspace-owned resource, belong to that workspace. Reassignment preserves sharing; ownership transfer does not automatically add the former owner as an editor.

Only the playbook's current owner or a manager of its owning workspace can set or rename its alias, and the owner must already have a public handle. Share the qualified pb:handle/alias reference; bare pb:alias is a local lookup form.

Suggestions

epismo playbook suggestion create <playbook-id> \
  --base-version-id <version-id> --title "Clarify evidence" --content "..."
epismo playbook suggestion list <playbook-id> --statuses open
epismo suggestion list
epismo suggestion list --view inbox
epismo suggestion update <suggestion-id> --title "..." --content "..."
epismo suggestion resolve <suggestion-id> --status applied \
  --result-version-id <new-version-id>

Suggestions belong to their live parent playbook and have no separate owner or sharing snapshot. authorId records who created the proposal; baseVersionId preserves the immutable content reference for evaluating it. Reading requires current parent access; an archived parent hides its suggestions until restored. Authors may edit their open proposals while retaining parent access; current playbook editors may adopt or decline proposals. After a transfer, existing proposals follow the parent’s current sharing. Publish the result before marking a proposal applied.

suggestion list --view inbox / suggestion list --view sent

playbook list and UUID-based playbook get work before login for public playbooks and cost 0 credits. Search and every private or mutating operation require authentication and use the prices in Credits.

Explicit creation settings and sharing updates use access: { visibility, grants }: restricted/public visibility and user/team UUID or registered user email keys with viewer/editor values. Emails resolve to user UUIDs before saving; responses contain UUID keys. An unregistered email or conflicting roles for the same resolved user rejects the entire write. Updates replace the whole object; preserve unrelated grants and include your own grant if you want to retain it. Owners retain management independently of grants. Assignees and maintainers receive no implicit access. Editors can inspect and replace sharing, retain at least one explicit editor when changing grants, and archive or restore. Ordinary resource JSON omits private grant maps; editors can retrieve the complete settings with access-get. See Access and identity.

Copy a readable published version to adapt it independently. The copy has its own content and versions; it does not inherit sharing, drafts, cases, suggestions, aliases, stars, or history, and edits never synchronize. Choose sharing explicitly; omit ownerId to use the active workspace or personal home. copiedFrom records the immediate source and immutable source version; sourceAccessible indicates whether the source remains readable. Copy lists show only readable copies. Copying costs the normal playbook creation price.

epismo playbook copy "$PLAYBOOK_ID" --source-version-id "$VERSION_ID" --private
epismo playbook copies list <playbook-id>

Ownership, responsibility, and lifecycle

Omit ownerId on creation or copy to use the active workspace, or your personal account when no workspace is selected. Supplying it explicitly chooses the home subject to authorization. When a workspace is selected, including a saved connection default, creation requires exactly one of private: true, non-empty teamIds, or access. Personal creation may omit sharing. Team editor access covers the creator without adding a redundant direct grant; an explicitly requested creator grant is preserved. Maintenance and assignment do not replace sharing.

Editors and owners may archive and restore the playbook. List archived playbooks without a text query using archived=true (playbook list --archived or epismo_playbook_search), then restore with playbook restore or epismo_playbook_restore. Versions, sharing, and maintenance are preserved. Owners can change responsibility with playbook assign --assigned-to or epismo_playbook_assign; this grants no access. Historical version archival remains ownership-only, and the latest version cannot be archived.

In the Web Archived playbooks view, an owner can permanently delete an archived playbook only when no case references it (including completed or archived cases) and no other playbook was copied from it. This cannot be undone. CLI and MCP archive/restore operations do not perform permanent deletion.

epismo playbook list --archived
epismo playbook restore <playbook-id>
epismo playbook assign <playbook-id> --assigned-to <user-id>

Playbook assignment uses assignedTo, just like case assignment, and uses the same assignedTo field in responses. Use epismo_playbook_assign, playbook assign <playbook-id> --assigned-to <user-id>, or PATCH /v1/playbooks/{playbookId}/assignee. Ownership is required; the target must already be able to edit.

epismo playbook list --sharing-scope shared --assigned-to <user-id>
epismo playbook search --query incident --sharing-scope anyone
epismo playbook resource list --kind cli --sharing-scope shared