Create and publish a playbook

Create a playbook, publish a version, and choose who can read or edit it through team sharing and public visibility settings.

Creating a playbook saves its first version. Publishing an update saves a new, immutable version that people and agents can use with the playbook’s existing access settings. Supply the current latest version as the base when updating.

Choose the operation for your goal:

Goal	Operation	Result
Make a stable version available for use	Publish a version	Save fixed content and retain previous versions. Existing sharing stays in place.
Work with selected people	Share with your team	Grant a team viewer or editor access while keeping visibility restricted.
Let anyone read the playbook	Make public	Set visibility to `public`; anyone can read its published versions.

Prepare the input files

Save the following example as playbook.json in your working directory. It creates a private playbook in the active workspace or personal space. Check the selected workspace before running the command.

{
  "private": true,
  "definition": {
    "schemaVersion": 1,
    "title": "Review an AI pilot",
    "description": "Check the client goal and agree how to evaluate the pilot.",
    "category": "operations",
    "inputSchema": {
      "type": "object"
    },
    "steps": [
      {
        "title": "Confirm the client goal",
        "instructions": "Record the agreed scope, baseline figures, success criteria, and decision-maker."
      }
    ]
  }
}

In a workspace, choose exactly one initial sharing option: private: true for creator access, teamIds for editor access through selected teams, or access for complete visibility and grants. To share this example with your client team at creation, replace "private": true with "teamIds": ["<client-team-id>"]; use the actual team UUID and do not keep both options.

For an update, copy playbook.json to next-version.json, remove the top-level private field, and edit the content inside definition. The update file should contain only the definition object; creation-only fields such as ownerId, private, teamIds, and access do not belong in that file. The command below supplies baseVersionId through --base-version-id. The @ prefix tells the CLI to read the named JSON file.

For input schemas, steps, and resource hints, see Author a playbook.

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

After a conflict, re-read latest and merge your intent into a new definition.

Iterate first with a draft

Publishing directly is fine for a small, confident change. For anything that needs a few passes, save it as a draft instead — it never mints a version, so there is nothing to clean up if you change your mind:

Prepare draft.json in the same format as next-version.json: a top-level definition object containing the complete revised playbook definition. Set --base-revision to the draft revision returned by draft get; use 0 only when no draft exists.

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

--base-revision is the revision you last read (0 for a new draft); a stale value means someone else saved since — re-read and retry. A playbook has one draft, visible only to users who can edit the playbook. draft publish mints a version from the draft's current content and discards it in the same step; draft discard throws it away without publishing anything.

Access: access: { visibility, grants }; viewer/editor grants are separate from public visibility.
Alias: memorable reference; never grants access.
Share URL: redirects to the playbook page, where the current ACL still applies. Current share URLs have no expiry or revoke operation.
Draft: unpublished mutable content that requires edit access. Share URLs do not grant it.

After publishing the version, choose the people who will use it. For client work, keep visibility restricted and grant the team access. First prepare the client team and, for a client-specific method, copy a suitable version.

Read the copy’s existing sharing settings. For example, an internal team can maintain the method while the client team reads it:

epismo playbook access get <client-playbook-id>
epismo playbook access set <client-playbook-id> \
  --access '{"visibility":"restricted","grants":{"<internal-team-id>":"editor","<client-team-id>":"viewer"}}'

This is a complete example grant map, not a merge. Keep other intended collaborators from the read settings and retain at least one explicit editor. Use editor for the client team only when its participants should update the playbook; editors can also read drafts and change sharing. Check the published versions, draft, and resource references against that audience before sharing.

Open the playbook with a client participant to confirm reading or editing as intended. Share the engagement case separately; playbook access is not copied into cases. A URL or alias is a reference, not a substitute for the team grant. See Coordinate a case.

Create and publish a playbook

Prepare the input files

Iterate first with a draft

Share with the client team