Playbooks

Find and read

epismo playbook search --query "release review" --category operations
epismo -w acme playbook search "release review" --output table
epismo playbook search --query "release review" --lang ja,fr
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>
epismo playbook starred

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, cursor, and preferred content languages. Pass comma-separated two-letter language codes to --lang in priority order. This ranks matching languages first rather than filtering other results out; Epismo adds English as a fallback when it is not already listed. Omit --query for a plain catalog listing. Without --lang, that listing is ordered by most recent update; with it, language rank comes first. 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

Start with a minimal Definition when you do not already have a file:

epismo playbook init --title "Release review" > playbook.json
epismo playbook create --definition @playbook.json

Use a file for a complete Definition:

{
	"ownerId": "<account-id>",
	"access": { "visibility": "private", "editors": ["<user-or-team-id>"] },
	"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 --input @playbook.json
epismo playbook version publish <playbook-id> \
  --base-version-id <latest-version-id> --input @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 --input @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. Editors and owner managers 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, references, and saving

epismo playbook access get <playbook-id>
epismo playbook access set <playbook-id> --visibility public --editors <user-or-team-ids>
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 star <playbook-id>
epismo playbook unstar <playbook-id>
epismo playbook archive <playbook-id>

visibility public permits anyone to read published content only. editors are active User Account or Team IDs that may read and edit content; the owner is implicit and never appears in that list. Owner managers (including Workspace Owners and Admins for a Workspace-owned Playbook) alone manage access and archive Playbooks or historical Versions. An alias provides a readable name, a share token provides token-based read access, and a star is personal. These mechanisms are independent. Archiving removes a Playbook from normal use without rewriting its Versions.

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>

The author can edit an open Suggestion; the Playbook owner resolves it. Top-level suggestion list defaults to Suggestions sent by the current user. Pass --view inbox to list Suggestions on Playbooks you manage. applied requires the Version published from the proposal. Resolve as declined when it should not be adopted and archived when it is withdrawn.

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.