Manage published docs

Use these commands after a post is live. They cover everything short of editing its Markdown, which is what opendocs update is for.

List

opendocs list

By default, opendocs list shows only the posts in your active workspace and active project — the context shown by opendocs whoami. Use --all-projects to list every project in the active workspace, or --all to list posts across every workspace you belong to.

Useful flags:

opendocs list --page 2 --limit 50
opendocs list --tag roadmap
opendocs list --all-projects           # every project in the active workspace
opendocs list --all                    # every workspace you belong to
opendocs list --json

--page and --limit must be positive integers. --limit cannot exceed 100.

The list response includes the current page, limit, total count, tags, project metadata, and each post's workspaceId / workspaceSlug. The top-level scope field is "project" for the default, "workspace" when --all-projects is passed, and "all" when --all is passed.

Get

opendocs get <postId>

This is the quickest way to inspect a single post's:

• URL
• slug
• visibility
• version number
• timestamps
• tags

Pull

opendocs pull <postId>

By default, the CLI saves the current Markdown as {slug}.md.

Useful options:

opendocs pull <postId> --stdout
opendocs pull <postId> --output docs/current-spec.md
opendocs pull --project launch-docs --output ./launch-docs
opendocs pull --workspace --output ./workspace-docs

--stdout is especially useful in scripts and agent workflows. Project and workspace pulls are useful for local backups or for letting an agent review a full body of work before making changes.

Export

opendocs export <postId> --format pdf
opendocs export <postId> --format docx
opendocs export intro guide api-spec --format pdf --output ./exports

Single-document exports save to the filename suggested by the API unless you pass --output. Batch exports unpack into the current directory, or into the directory passed with --output.

The CLI treats API-provided filenames as plain basenames. If a filename contains path separators or would write outside the selected output directory, the CLI refuses that file instead of writing it.

Change visibility

opendocs visibility <postId> private
opendocs visibility <postId> workspace
opendocs visibility <postId> public --confirm-public

Flips the visibility of a published post without creating a new version, re-uploading the Markdown, or re-processing inline images. This is the right command when you only want to change who can see the post — not its content.

Levels:

• private — only you.
• workspace — workspace members (the default for new posts).
• public — anyone on the internet with the link. Requires --confirm-public as a deliberate opt-in; the CLI refuses otherwise. Your workspace's Allow public documents setting must also be on for public posts to actually render to anonymous viewers.

For changing visibility and content in one shot, use opendocs update with its own --visibility flag instead.

Unpublish (hide — reversible)

opendocs unpublish <postId>

Removes the post from published access without deleting it. The row, its slug reservation, every version, and your local Markdown file all stay intact — only the isPublished flag flips off. Re-publishing later goes through opendocs publish again; opendocs update only works on currently published posts.

Delete (permanent)

opendocs delete <postId> --yes

Hard-deletes the post. Removes the row, every version, all tags, and frees the slug for reuse. Cannot be undone — there's no recycle bin or retention window. The deletion is audited server-side.

Two safety layers:

• --yes / -y is required in any non-interactive context (scripts, CI, agent tool calls). Without it the CLI refuses and exits with confirm_required — no network call is ever made.
• Interactive prompt at a terminal: without --yes, you'll be asked to re-type the post's ID or slug exactly. Anything else cancels cleanly.

Unpublish vs delete

	unpublish	delete
Reversible?	Yes	No
Frees the slug?	No	Yes
Frees a quota slot?	Yes, if the post was published	Yes, if the post was published
Keeps version history?	Yes	No
Use when…	Hiding a draft temporarily	Post is done; want the slot / slug back

If you're unsure, start with unpublish — you can always delete later, but you can't undo a delete.

Common round-trip workflow

opendocs list --json
opendocs pull abc123 --output draft.md
# edit draft.md
opendocs update draft.md --post-id abc123

Tips for agents

• Use list --json to look up the correct post.
• Use pull --stdout when an agent needs the current body in-memory.
• Use get when you need the current URL or visibility before making a change.
• Always pass --yes to delete from an agent — without it, the command refuses with confirm_required in non-TTY contexts.
• Prefer visibility over re-publishing with update if you only want to flip the access level — it skips the version bump and image re-processing.
• When a user says "remove this post", default to unpublish unless they clearly want it gone for good.