Codex CLI

cdx - a command-line tool for managing a Codex instance. Manage docs, workspaces, API keys, plugins, and more from the terminal.

Not to be confused with OpenAI's Codex. This is for a document editor, not for a coding agent.

Runtime: Bun or Deno. CLI is written in Typescript. If people request it i will swap to a JS bundle

Installation

# From the monorepo
bun i -g @getcodex/cli
cdx auth login

# Or run directly
bunx @getcodex/cli <command>

Configuration

cdx config set instance-url https://codex.example.com   
cdx config set registry-url https://plugins.codex.example.com
cdx config get                                           # show all config
cdx config unset registry-url

Environment variable overrides:

CODEX_BASE_URL      Instance URL
CODEX_API_KEY       API key for headless/CI usage
CODEX_ACCESS_TOKEN  OAuth access token

Authentication

cdx auth login                        # interactive OAuth flow
cdx auth login --api-key cdx_mykey   # save an API key
cdx auth whoami                       # print current user
cdx auth logout

Workspaces

cdx workspaces list
cdx workspaces create "Engineering" engineering
cdx workspaces members engineering
cdx workspaces invite engineering --max-uses 5 --expires-at 2025-12-31

Documents

cdx docs list engineering
cdx docs create engineering "Architecture Decision Records"
cdx docs get engineering <docId>
cdx docs update engineering <docId> --title "ADR Index" --visibility internal --pin
cdx docs delete engineering <docId>

--visibility accepts private, internal, or public.

Versions

cdx versions list <docId>
cdx versions snapshot <docId> "Before refactor"
cdx versions get <docId> <versionId>

Comments

cdx comments list <docId>
cdx comments add <docId> "This section needs a diagram."

Templates

cdx templates list engineering
cdx templates use engineering <templateId>

API Keys

cdx keys list engineering
cdx keys create engineering "CI bot"
cdx keys delete engineering <keyId>

Webhooks

cdx webhooks list engineering
cdx webhooks create engineering https://example.com/hook doc.created doc.updated
cdx webhooks ping engineering <webhookId>
cdx webhooks deliveries engineering <webhookId>
cdx webhooks delete engineering <webhookId>

Supported events: doc.created, doc.updated, doc.deleted, comment.created, member.joined. Omit events to subscribe to all.

Plugins

Registry management (instance admin)

cdx plugins registries list
cdx plugins registries add "Official" https://plugins.codex.cane1712.dev
cdx plugins registries remove <registryId>

Installing plugins

cdx plugins list                                  # installed instance-wide
cdx plugins install official:word-count           # install (registrySlug:pluginId)
cdx plugins install word-count                    # registry prefix optional if only one is configured
cdx plugins uninstall <pluginId>

The registry slug is fetched automatically from the registry when you add it, so install only needs the registry ID and the plugin's manifest ID.

Workspace policy

cdx plugins workspace engineering                               # list plugins + policies
cdx plugins policy set engineering <pluginId> required          # required | available | blocked
cdx plugins policy remove engineering <pluginId>

Developing and publishing plugins

# Scaffold a new plugin
cdx plugins init dev.yourname.word-count           # creates ./word-count/
cdx plugins init dev.yourname.word-count my-dir    # custom output directory

# Build your plugin, then publish
cdx plugins publish                                # reads manifest.codex.json in cwd
cdx plugins publish --dir ./my-plugin --registry https://plugins.example.com --author "Your Name"

The publish command reads manifest.codex.json, builds the bundle, and pushes it to the configured registry. Auth uses the saved API key (cdx auth login --api-key ...).

Global Flags

--json              Output raw JSON (useful for scripting)
--dry-run           Print request details without sending
--instance-url URL  Override instance URL for this invocation
--api-key KEY       Override API key for this invocation
-h, --help          Show help
-v, --version       Print version

Examples

# List all docs in a workspace as JSON and pipe to jq
cdx docs list engineering --json | jq '.[].title'

# Create an API key for CI
cdx auth login --api-key cdx_myadminkey
cdx keys create engineering "CI" --json | jq -r '.key'

# Install a plugin from the official registry
cdx plugins registries add "Official" https://plugins.codex.cane1712.dev
cdx plugins install official:word-count
cdx plugins policy set engineering <pluginId> required

# Re-running install re-fetches and overwrites the stored bundle — this is
# also how you push out an update after `cdx plugins publish`.
cdx plugins install official:word-count