Agent workflow

Use this workflow when an agent owns the OpenPMM task through the CLI.

The CLI is the boundary for this workflow. Do not read credentials.json, extract its API key, or call /v1 with that key. The credential store is an internal CLI implementation detail.

Agent rules

Use only the openpmm command for OpenPMM operations in this workflow.
Never read or export the CLI credential store.
Do not call /v1 with the CLI credential.
Use --file and --json for deterministic automation.
After a successful publish command, stop or use the CLI next command. Do not add HTTP polling or send the publish command again.

These rules do not remove the public API. A direct API integration uses its own least-privilege credential from a secret manager.

1. Authorize the CLI

openpmm auth login --no-wait --json

Pause for browser approval. Then resume:

openpmm auth login --resume --json
openpmm doctor --json

doctor is read-only. Confirm that API compatibility is ready, authentication is valid, a Workspace is selected, and at least one Destination is ready.

2. Discover IDs

openpmm workspaces list --json
openpmm destinations list --json

Use the selected Workspace from doctor. Copy a Destination id from destinations list for the publication file.

3. Create approved drafts

Save this complete request as approved-drafts.json:

{
  "when": "draft",
  "group": "launch-2026-08",
  "posts": [
    {
      "channel": "x",
      "headline": null,
      "body": ["A release update from OpenPMM."],
      "media": [],
      "destination_options": null
    }
  ]
}

Create the drafts:

openpmm posts create \
  --file approved-drafts.json \
  --json

The result contains data.posts. Copy each Post id and version. Keep every Post in the group together for the publish request.

4. Publish the same Posts

Save this complete request as approved-publication.json. Replace the example values with the Post and Destination IDs that you discovered:

{
  "confirmed": true,
  "when": "now",
  "time_zone": "UTC",
  "posts": [
    {
      "id": "send_01JABCDEF",
      "version": 1,
      "destination_id": "dest_01JABCDEF"
    }
  ]
}

Publish and let the CLI handle bounded status checks:

openpmm posts publish \
  --file approved-publication.json \
  --yes \
  --wait \
  --json

The command waits for immediate Posts until they are terminal or need action. It waits for up to 300 seconds by default. The result includes meta.publication.wait_complete.

If wait_complete is true, stop. Read receipts from the returned Posts.
If it is false, the work is still accepted. Use the returned next_command, such as openpmm posts wait send_... --json.
If meta.publication.action_required_post_ids is not empty, stop and inspect each Post’s available_actions. The command exits with code 11.
Read top-level outcome: success, partial_failure, or failure.
Never send posts publish again for accepted work.

For a scheduled or queued publication, omit --wait. A successful response means that OpenPMM stored the schedule or queue choice.

Existing HTTP clients

If the repository contains a custom OpenPMM HTTP client, do not give it the CLI credential. Keep this agent workflow on CLI request files. If the project needs a direct API workflow, create a separate scoped credential and follow API authentication.

Get started

Workflows

Automation

Agent rules

1. Authorize the CLI

2. Discover IDs

3. Create approved drafts

4. Publish the same Posts

Existing HTTP clients

​Agent rules

​1. Authorize the CLI

​2. Discover IDs

​3. Create approved drafts

​4. Publish the same Posts

​Existing HTTP clients

Agent rules

1. Authorize the CLI

2. Discover IDs

3. Create approved drafts

4. Publish the same Posts

Existing HTTP clients