Skip to main content

Codex

Codex is OpenAI's CLI-based coding agent. It can write files, execute shell commands, and chain multi-step tasks — which makes it a natural fit for writing Markdown and publishing to OpenDocs in a single pass.

Setup​

Install the CLI and authenticate:

npm install -g @opendocs.cc/cli
opendocs login

To make the workflow repeatable across sessions, point Codex at the OpenDocs SKILL.md. Codex will reference the skill file whenever it encounters a documentation task.

Example prompts​

Publish a new doc:

Document the database schema changes as Markdown, publish the
result with OpenDocs, and return the final URL.

Publish with tags and a custom slug:

Write a post-mortem for the auth outage as Markdown. Publish it
to OpenDocs with slug "auth-postmortem-april" and tags
"incident, auth, postmortem". Give me the URL.

Update an existing doc:

Pull the latest version of post abc123 from OpenDocs, add the
new caching section, and publish the update.

Batch publishing:

Generate Markdown docs for each of our three new API endpoints
(create-order, get-order, cancel-order). Publish each one to
OpenDocs with appropriate slugs and the tag "api-v2". Return
all three URLs.

Common workflows​

Write-and-publish​

The most common pattern — Codex writes a Markdown file and publishes it in one task:

opendocs publish db-schema-docs.md --json

Multi-file documentation​

Codex handles multi-step tasks well. Ask it to generate several related docs and publish each one:

opendocs publish api-overview.md --slug api-overview --tags "api,v2" --json
opendocs publish auth-guide.md --slug auth-guide --tags "api,v2" --json
opendocs publish error-codes.md --slug error-codes --tags "api,v2" --json

Review before publishing​

If you want to review the content before it goes live, ask Codex to write the file first and then wait for confirmation:

Write the migration guide as Markdown and save it to migration-v3.md.
Don't publish yet — let me review it first.

Then publish manually or in a follow-up task:

opendocs publish migration-v3.md --json

Ask Codex to return structured information after publishing:

After publishing, return:
- The local Markdown filename
- The published URL
- The post ID (for future updates)

Tips​

  • Use SKILL.md — Codex follows skill files to remember the publishing workflow between sessions
  • Use --json — Codex parses JSON output reliably and can extract URLs, post IDs, and slugs
  • Chain commands — Codex is good at multi-step workflows like "write three docs, publish all three, return a summary table with URLs"
  • Environment variable auth — for CI or automated scripts, set OPENDOCS_API_KEY instead of running opendocs login