Skip to main content

CLI quickstart

This is the manual path. It is also the foundation for agent workflows, because agents ultimately call the same CLI under the hood.

1. Install the CLI​

npm install -g @opendocs.cc/cli

2. Create an account and API key​

  1. Sign up at opendocs.cc/signup.
  2. Complete onboarding by choosing a username, workspace name, and workspace ID.
  3. Open Dashboard -> API Keys.
  4. Create a key that starts with od_live_.

3. Log in​

Pass the key directly:

opendocs login --key od_live_xxxxx

Or run opendocs login and paste it into the hidden prompt.

Agent and CI usage

When an AI agent, script, or CI job is running the CLI, avoid the interactive prompt. Pass --key or set OPENDOCS_API_KEY, and use --json on commands whose output the caller needs to parse.

Or export it first:

export OPENDOCS_API_KEY=od_live_xxxxx
opendocs login

The CLI validates the key against https://api.opendocs.cc by default and saves your config locally.

4. Check who you are logged in as​

opendocs whoami

You should see your username, active workspace, active project, and API URL.

5. Publish your first Markdown file​

opendocs publish plan.md

If plan.md contains a first-level heading, OpenDocs uses that as the title by default. The command returns a stable URL such as:

opendocs.cc/<workspace>/plan

The prefix is your workspace slug (chosen during onboarding), not your personal username. See Usernames and workspace slugs for the distinction.

A more explicit first publish​

opendocs publish plan.md \
  --title "Q2 rollout plan" \
  --slug q2-rollout-plan \
  --visibility workspace \
  --tags roadmap,q2-2026

Use JSON when scripting​

opendocs publish plan.md --json

Example response:

{
  "postId": "abc123",
  "slug": "q2-rollout-plan",
  "url": "/acme/q2-rollout-plan",
  "title": "Q2 rollout plan"
}

Helpful commands after login​

opendocs list
opendocs get <postId>
opendocs pull <postId>
opendocs update plan.md --post-id <postId>
opendocs export <postId> --format pdf

Most commands that take <postId> also accept the document slug from the URL. For example, opendocs get q2-rollout-plan works if the active workspace has a post at /acme/q2-rollout-plan.

Publish several files​

For folders of Markdown, pass all files to one command. The CLI uses the batch publish endpoint, chunks server requests in groups of 25, and supports up to 500 files per invocation:

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

You can also pass a folder directly. This is the easiest way to try OpenDocs with an Obsidian vault:

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

Folder uploads are recursive. The CLI skips .obsidian, .trash, .git, and node_modules.

Do this instead of looping one opendocs publish per file. A shared tag gives you and your agent a durable handle for finding the batch later:

opendocs list --tag api-docs

Keep batches organized with projects​

Every workspace has a Default project. One-off docs can stay there. For a named body of work, create a project and publish into it:

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

Or publish to a project without switching:

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

Default project docs use URLs like opendocs.cc/<workspace>/<slug>. Named project docs use opendocs.cc/<workspace>/projects/<project>/<slug>.

Publish and export together​

If you want a URL and a PDF/DOCX file, use the publish-time export shortcut:

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

The post is published first, then the export is written next to the source Markdown file. This is the best agent pattern for prompts like "write this as a Markdown report and give me a PDF."

Working with multiple workspaces​

If you belong to more than one workspace — your own plus workspaces owned by a Team account, multiple Pro workspaces, etc. — the CLI stores one active workspace at a time in its local config. Every publish, update, list, and related command acts on that workspace.

List every workspace you belong to:

opendocs workspace list

The active workspace is marked with a ✔. Switch to a different one by slug:

opendocs workspace use <workspace-slug>

From there, the next opendocs publish will go to the new workspace's Default project and URLs will use the new slug. opendocs whoami shows which workspace and project are active, and how many other workspaces you belong to.

Switching is purely local — it only touches your CLI config. The web dashboard's active workspace is independent.

Local config​

The CLI stores auth config at:

~/.config/opendocs/config.json

The config file is kept readable only by your user (0600) and the containing directory is kept private (0700).

Next steps​