GPDoc CLI

The GPDoc CLI creates, inspects, validates, converts, and publishes document files from a terminal. It keeps body editing in GPEditor or the editor configured through $VISUAL or $EDITOR.

From this repository, run commands through npm run cli --:

npm run cli -- new docs/release-plan.gpdoc.md --title "Release plan"
npm run cli -- convert notes.html --to gpdoc --output docs/notes.gpdoc.md
npm run cli -- convert https://example.com/guide --to markdown --output guide.md
npm run cli -- validate docs/notes.gpdoc.md --json
npm run cli -- edit docs/notes.gpdoc.md
npm run cli -- knowledge list --json
npm run cli -- knowledge search repo_123 "deployment review" --json
npm run cli -- knowledge github-authorize

Supported input formats are Markdown, managed GPDoc Markdown, HTML, plain text, GPDoc JSON documents, DOCX, and PPTX text. Supported outputs are gpdoc, markdown, html, text, json, docx, and pdf. DOCX/PPTX conversion preserves text and headings, not full presentation layout; PDF output is text-only. PDF input, RTF input, and PPTX output return an explicit unsupported-format error.

Conversions write to standard output or an explicit output path. Existing files are never overwritten unless --in-place is supplied for the source file.

Account and remote providers

Use gpdoc login to begin GPDoc's device authorization flow. It attempts to open your browser, waits for authorization, and writes the local CLI session before returning. If it cannot launch a browser, use the printed URL and code manually. Use gpdoc login --no-browser in a headless session. If you interrupt the command after completing browser authorization, run gpdoc login complete before the displayed expiry to finish saving the local session. gpdoc whoami --json reports the CLI session without including credentials. gpdoc logout clears only the local CLI credential file.

For CI, set GPDOC_ACCESS_TOKEN instead of signing in interactively. The CLI does not persist that environment value. Interactive credentials are stored outside the current workspace with user-only permissions. Provider tokens are not shown in command output.

After the associated Google Drive, Microsoft 365, and GitHub accounts are connected in GPDoc, use explicit actions to avoid accidental remote writes:

# Create or revise a Google Docs source document.
gpdoc google upload docs/release-plan.gpdoc.md --title "Release plan"
gpdoc google update docs/release-plan.gpdoc.md --drive-id DRIVE_ID --item-id ITEM_ID --revision REVISION

# Create, revise, or share a Microsoft 365 file.
gpdoc microsoft upload docs/release-plan.gpdoc.md
gpdoc microsoft update docs/release-plan.gpdoc.md --drive-id DRIVE_ID --item-id ITEM_ID
gpdoc microsoft share --drive-id DRIVE_ID --item-id ITEM_ID --role edit --scope organization

# Create or revise a GitHub Gist or a repository file.
gpdoc gist create docs/release-plan.gpdoc.md --description "Release plan"
gpdoc gist update GIST_ID docs/release-plan.gpdoc.md
gpdoc repo put repetere/example docs/release-plan.gpdoc.md --path docs/release-plan.gpdoc.md --branch main

Private Gists and private repositories require the same GPDoc GitHub-source entitlement as the VS Code extension. Google and Microsoft operations use GPDoc's provider API boundary; GitHub actions use the GitHub identity linked to the signed-in GPDoc account.

Git Knowledge

Git Knowledge commands call the GPDoc Cloudflare Worker and use GPDOC_ACCESS_TOKEN. They never receive GitHub App credentials, Cloudflare credentials, or source-index bindings. Run gpdoc knowledge github-authorize to use the GitHub App device flow, then use connect with a GitHub repository ID. After authorization, the CLI can list, inspect, search, connect, reindex, manage members, propose reviewable wiki changes, and disconnect repositories. Use --json for machine-readable cited search results.

Installation

After the public npm release, install with npm install --global @gpdoc/cli, or run one command without installation through npx --yes @gpdoc/cli. The initial distribution target is npm because the CLI requires Node.js 20 or later on every supported platform. A Homebrew formula and signed macOS, Windows, and Linux downloads should follow once release artifacts and signing are in place.