Skip to main content

Agent quickstart

If you are using OpenDocs with OpenClaw, Hermes Agent, Codex, Claude Code, Cursor, Copilot, or any other tool that can run terminal commands, this is the place to start.

OpenDocs is designed around a simple loop:

  1. Your agent writes or updates a Markdown file.
  2. The agent runs the OpenDocs CLI.
  3. OpenDocs returns a stable URL.
  4. The agent gives you the link.
  1. Install the CLI:
npm install -g @opendocs.cc/cli
  1. Create an OpenDocs account at opendocs.cc/signup.
  2. Complete onboarding by choosing a username, workspace name, and workspace ID.
  3. Create an API key in Dashboard -> API Keys.
  4. Point your agent at the OpenDocs SKILL.md.
  5. Run:
opendocs login --key od_live_xxxxx

Do not ask an agent to run bare opendocs login unless a human is sitting at the terminal. Bare login waits for an interactive API-key prompt; agents and CI should use --key or OPENDOCS_API_KEY.

Why start with SKILL.md​

SKILL.md is the easiest way to make an agent reliably use OpenDocs. It gives the agent the exact command set, auth expectations, visibility defaults, and safe-sharing behavior.

It teaches the agent to:

  • install the CLI
  • authenticate with an API key
  • publish a new Markdown file
  • publish folders in one batched command
  • create or switch projects for related document batches
  • export successful publishes to PDF or DOCX
  • update an existing post
  • list published docs
  • pull raw Markdown back down
  • unpublish a post safely

Go straight to SKILL.md if your tool supports skills, instruction files, or reusable workflow docs.

What to ask your agent​

Use prompts that combine a writing task with an explicit publish step.

OpenClaw​

Write a Markdown rollout note for the auth changes, publish it with OpenDocs,
and return the final URL.

Codex​

Document the API changes in Markdown, use the OpenDocs SKILL.md if needed,
publish the result, and give me the shareable link.

Hermes Agent​

Write a weekly engineering brief as Markdown, publish it to OpenDocs,
and send the resulting URL back to this channel.

Claude Code​

Create a migration guide as Markdown, run the OpenDocs CLI to publish it, and
paste the resulting URL in your final message.

Why --json matters for agents​

When an agent is calling the CLI programmatically, prefer JSON output:

opendocs publish rollout-note.md --json

That returns a structured object with the postId, slug, url, and title, which is easier for agents to parse than terminal-formatted text.

For folder uploads, also use one batched command with a shared tag:

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

The tag gives the agent and the user a stable way to find the group later with opendocs list --tag api-docs.

For larger or repeated work, prefer a project:

opendocs project create "API docs" --slug api-docs --use --json
opendocs publish docs/*.md --json

Projects keep the workspace root clean. Default project docs appear at opendocs.cc/<workspace>/<slug>; project docs appear at opendocs.cc/<workspace>/projects/<project>/<slug>.

What happens after publish​

  • The Markdown file on your machine stays the source of truth.
  • OpenDocs stores a publishable snapshot and version history.
  • The generated URL is stable, so future updates keep the same link.
  • Visibility defaults to workspace, not public.
tip

If your intent is “share this with the team,” keep the default workspace visibility. Only use public visibility when you want anyone on the internet with the URL to be able to read the document.

Next steps​