Skip to main content

Agent cookbook

These are the workflows agents should use most often. They assume the CLI is installed and authenticated with either opendocs login --key ... or OPENDOCS_API_KEY.

Publish a folder​

Use one batch command, not a shell loop:

opendocs publish docs/*.md --tags api-docs --json

For an Obsidian vault or a larger folder, pass the folder itself:

opendocs publish ./vault --tags obsidian-import --json

Why this shape:

  • the CLI chunks requests into server batches of 25 documents
  • folder uploads are recursive and skip .obsidian, .trash, .git, and node_modules
  • one shared tag lets the user find the whole group later
  • --json gives the agent one result object to parse

Agent response pattern:

Published 12 docs. The batch tag is `api-docs`; you can list them with
`opendocs list --tag api-docs`.

If the user says "upload all .md docs in this folder with tag traction", run:

opendocs publish *.md --tags traction --json

Update a doc by slug​

If the user names a published doc and the slug is obvious, use the slug directly:

opendocs pull launch-note --stdout > /tmp/launch-note-current.md
# edit and save revised Markdown
opendocs update launch-note.md --post-id launch-note --json

If the user is vague, list first:

opendocs list --json --limit 50

Pick the matching slug or id, then update.

Publish and export PDFs​

When the user wants both a URL and a file, use the publish-time export shortcut:

opendocs publish report.md --export pdf --json

For a folder:

opendocs publish docs/*.md --export pdf --tags release-q2 --json

The JSON response includes publish results and export paths. Report both:

Published the report at /acme-docs/report and exported `report.pdf`.

If export fails after publish succeeds, retry only the export:

opendocs export report --format pdf --json

Switch workspace before publishing​

When the user names a workspace, confirm the active workspace before writing:

opendocs workspace list --json
opendocs workspace use acme-docs --json
opendocs publish report.md --json

Match the user's words against both name and slug. If the requested workspace is not listed, tell the user which workspaces are available instead of guessing.

Choose visibility safely​

Default to workspace visibility:

opendocs publish internal-plan.md --visibility workspace --json

Use public only when the user explicitly asks for a public link:

opendocs publish launch-note.md --visibility public --confirm-public --json

If the user says "share this with the team", keep workspace. If they say "make this public", use public --confirm-public.

Recover from the Free document limit​

A document_limit error is not transient. Do not retry in a loop.

Good recoveries:

  • ask which docs to publish if only some fit
  • unpublish old docs with opendocs unpublish <slug>
  • suggest upgrading to Pro for unlimited documents

Agent checklist​

Before publishing:

  • save content to a .md file
  • run opendocs whoami --json if workspace or quota matters
  • switch workspace if the user named one
  • use a shared tag for folder/batch publishes
  • use --json
  • never use --visibility public without explicit consent