openpost-cli

# OpenPost CLI Use the `openpost` executable as an external client of a running OpenPost instance. Keep the instance, workspace, destination accounts, content, and publish time explicit. ## Start safely 1. Confirm the CLI exists: ```sh command -v openpost openpost version ``` If it is missing, stop and point to `https://openpo.st/docs/automate/cli`. Do not install software unless the user asked. 2. Inspect context before a workspace-scoped action: ```sh openpost instance diagnostics --json openpost auth status --json openpost workspace list --json ``` 3. Pass `--profile`, `--instance`, or `--workspace` when the saved context is absent or ambiguous. Prefer the stored keyring token or `OPENPOST_TOKEN`; do not put a token in command output, logs, files, or chat. 4. Use `--json` for reads and automation. Parse IDs and status from JSON instead of scraping tables. 5. When syntax may have changed, run `openpost help` or `openpost <group> <command> --help`. Treat live help as the command source of truth. ## Choose the authoring path - Use `openpost post` for the text-and-thread composer: short text, text with media, and editable drafts. - Use `openpost thread create` when the source is a Markdown file containing two or more `---`-separated posts. - Use `openpost publication` for format-first content: link shares, image posts, carousels, stories, short video, long video, and provider-specific output fields. - Inspect `openpost provider readiness --json` before a new provider workflow. Inspect `openpost provider capabilities --provider <key> --json` before choosing a publication profile or provider setting. Read [references/workflows.md](references/workflows.md) for exact command patterns and format selection. ## Apply mutations deliberately - Default to creating a draft when the user did not ask to schedule or publish. - Treat scheduling, publishing, retrying a rendition, replying, hiding or deleting a comment, disconnecting an account, generating schedule slots, and deletion as state-changing actions. Perform them only when the request authorizes that effect. - Before a publish or schedule action, resolve the exact instance, workspace, destination accounts, content, media, and RFC3339 time or named next slot. - Use account slugs as human-friendly `--accounts` selectors. Use exact account IDs for rendition retry, rendition deletion, and account disconnect; `account rename` accepts a flexible selector (ID, slug, `platform:username`, bare platform, or Fediverse host) plus `--slug`. - Add alt text during upload or with `openpost media update`. - Run `openpost publication validate <id> --json` before publishing a format-first publication. - Pass `--yes` only when the user already authorized the command's confirmation. Interactive confirmations guard `post delete`, `media delete`, `schedule delete`, `schedule suggest`, and `account disconnect`. Pass `--confirm` only for the exact item the user asked to delete: `publication delete`, `publication delete-rendition`, and `publication delete-comment` each require it. - Never add `--force` automatically after a revision conflict. Only `publication update` has `--force`; `post update` has no such flag because it re-reads the current revision before writing. Reload with `post view` or `publication view`, show the conflict, and retry only after reconciling the saved version with the requested edits. ## Verify the outcome After a mutation, inspect the returned ID and current server state: ```sh openpost post view <post-id> --json openpost publication view <publication-id> --json openpost publication events <publication-id> --json openpost jobs list --json ``` Do not describe `scheduled` as `published`. For queued work, report the object ID, job ID when present, schedule time, and current status. For partial or failed publication, inspect rendition failure fields and lifecycle events before retrying. ## Handle common failures - `401` or auth required: run `openpost auth status --json`; do not expose or regenerate credentials without user direction. - Workspace not found or ambiguous: run `openpost workspace list --json`, then pass an exact ID with `--workspace`. - Account selector ambiguous: run `openpost account list --json`, then use a unique slug or ID. - Provider validation failure: inspect readiness, capabilities, media metadata, and publication validation output; fix the stated blocker. - Revision conflict: reload with `post view` or `publication view`; do not replay stale data. - Media deletion blocked: run `openpost media usage <media-id> --json` and report the references. - No next slot: inspect `openpost schedule list --json`; do not invent a time.