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

When a user is working on a named initiative, prefer a project over only using tags. Projects keep related docs together and give the user a focused workspace view.

Create and switch to a project:

opendocs project create "Launch strategy" --slug launch-strategy --use --json
opendocs publish ./launch-docs --tags launch --json

Use an existing project without switching:

opendocs publish ./launch-docs --project launch-strategy --tags launch --json

Agent response pattern:

Published 6 docs to the `Launch strategy` project. You can review them at
`/acme/projects/launch-strategy`.

Use the Default project for small one-off docs. Use a named project when the user says "for this client", "for this feature", "for this launch", "for this test run", or asks you to publish multiple docs that should be reviewed together.

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
  • create or switch projects for named batches of work
  • use a shared tag for folder/batch publishes
  • use --json
  • never use --visibility public without explicit consent