GPDoc CLI

The GPDoc CLI creates, inspects, validates, converts, edits, and shares document files from a terminal. It uses the same GPDoc file conversion logic as the GPDoc apps. gpdoc open FILE defaults to terminal GPEditor; gpdoc edit FILE defaults to web GPEditor.

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

npm run cli -- new docs/release-plan.gpdoc.md --title "Release plan"
npm run cli -- --version
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

For Context Lake answers, use the named lake commands after gpdoc login:

gpdoc context-lakes list --json
gpdoc context-lakes status LAKE_ID --json
gpdoc context-lakes search LAKE_ID "Explain the architecture"
gpdoc context-lakes search LAKE_ID,SECOND_LAKE_ID "Compare the designs" --json
gpdoc context-lakes search LAKE_ID "Explain the architecture" --output answer.md
gpdoc context-lakes search LAKE_ID "Explain the architecture" --output answer.gpdoc.md

Search returns generated Markdown answers, source citations and revisions, and unavailable-source information. --json preserves each full lake response in answers alongside the aggregated results. --output creates a new file and refuses to overwrite an existing target. Use --to markdown or --to gpdoc to select the output format explicitly. Diagrams and formulas retain their Markdown source.

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.

Editing

gpdoc edit FILE starts a short-lived server on 127.0.0.1, opens the selected file in GPEditor, and saves back to that file. The server uses a random URL, exposes no other workspace files, and closes when you press Control-C. Keep the command running while you edit.

An exact GPDoc shared-document URL keeps the server-backed document as its save authority. open joins its live session in the terminal, while edit opens the shared browser editor:

gpdoc open https://gpdoc.io/s/SHARE_CODE
gpdoc edit https://gpdoc.io/s/SHARE_CODE
gpdoc open https://gpdoc.io/app/document/shared/SHARE_ID
gpdoc edit https://gpdoc.io/app/document/shared/SHARE_ID

Run gpdoc login first. Shared URLs require access through the signed-in GPDoc account and an active live document. They do not create a local copy or loopback preview. --editor local does not accept a shared URL.

Use your configured external editor when needed:

gpdoc edit docs/release-plan.gpdoc.md --editor local
VISUAL=code gpdoc edit docs/release-plan.gpdoc.md --editor local
GPDOC_EDITOR=local gpdoc edit docs/release-plan.gpdoc.md

The local mode uses $VISUAL, then $EDITOR. Both edit and open accept --editor web|local|terminal. An explicit --editor overrides a nonempty GPDOC_EDITOR; otherwise the command default applies. Use --editor web to select web GPEditor explicitly.

GPEditor in the terminal

gpdoc open docs/notes.gpdoc.md
gpdoc open docs/notes.gpdoc.md --mode split
gpdoc edit docs/notes.gpdoc.md --editor terminal
gpdoc edit docs/notes.gpdoc.md --editor terminal --mode split
gpdoc edit docs/notes.gpdoc.md --editor terminal --mode preview --keymap vim
GPDOC_EDITOR=terminal gpdoc edit docs/notes.gpdoc.md

Terminal GPEditor runs in the foreground without a browser, local server, or external editor. Local files need no provider login. Shared URLs use the existing GPDoc login to resolve and join the document's live session. An explicit --editor overrides GPDOC_EDITOR. --mode and --keymap apply only to terminal editing. Both input and output must be interactive terminals; pipes, TERM=dumb, and --json cannot start an editing session. macOS/Linux require Node.js 20 or later. Windows terminal editing requires Node 22.17+ within 22.x or Node 24.2+ for safe bracketed-paste input; unsupported versions are refused before opening the file. Use the current security-patched Node release. Other CLI commands retain their Node 20 minimum.

| Mode | Behavior | | --- | --- | | edit (default) | Renders Markdown outside the active block; reveals that block's exact source for editing. | | split | Shows source and preview side by side at 100 columns or more, otherwise stacked. Preview scrolling does not move the editing cursor. | | preview | Read-only navigation of the current draft. Returning to editing restores the editing selection. |

The default nano keymap uses direct typing. vim provides a bounded Normal/Insert/Visual keymap, not Vim plugins or arbitrary Ex commands. Ctrl+G opens the full keyboard help, including the read-only metadata view and Reload. Source line numbers are shown by default. Shared controls are Ctrl+S Save, Ctrl+Q Quit, Ctrl+T Mode, Ctrl+G Help, Ctrl+O Inspect image, F3 Show/Hide line numbers, and F7 Review. Review adds, replies to, resolves, and reopens managed GPDoc comment threads and records or reviews suggestions. Nano uses Ctrl+F Search and Ctrl+Z Undo; Vim Normal uses / or ? Search and u Undo. Copying uses an in-process clipboard; the editor does not export to the system clipboard. F6 changes Split focus. Nano and Vim Normal also accept Escape then Tab; in Vim Insert or Visual, first return to Normal. Minimum editing size is 40 columns by 12 rows; resizing smaller retains the draft and leaves Save, Quit, and Help available.

Terminal input is one existing UTF-8 Markdown file (.md, .markdown, .mdown, including .gpdoc.md), a GPDoc Markdown JSON document (.json), or an exact https://gpdoc.io/s/{code} or https://gpdoc.io/app/document/shared/{shareId} shared-document URL. The complete serialized file or resolved shared snapshot, including metadata and JSON escaping, must fit within 1 MiB. This is separate from conversion-command format support. Managed metadata is preserved, not rewritten through the rendered Markdown tree. Files with protected review/live metadata, hard links, or read-only permissions open in Preview when no mode is specified; an explicit editing mode is refused. Final-path symlinks and unsupported file kinds are refused. Use ./name:part.md for a POSIX filename containing a colon rather than a provider-looking reference.

Markdown headings, emphasis, lists, tasks, quotes, links, tables, and code use terminal cells. Supported static PNG, math, and Mermaid subsets have bounded renderers; unsupported content remains visible as labeled source or an image placeholder. A relative local PNG needs explicit per-image consent through Ctrl+O. Embedded data PNGs may render automatically. Remote images, SVG, scripts, CSS, and fonts are not loaded. Colors depend on terminal capabilities; NO_COLOR disables them. Typography, image fidelity, themes, and accessibility behavior are not identical to graphical GPEditor.

Saving is explicit. There is no autosave or recovery journal. Quit with unsaved changes offers Save, Discard, or Cancel, with Cancel selected initially. Conflicting disk revisions require review and Reload; there is no force overwrite. If a write outcome is uncertain, Verify checks the submitted save, while Reload replaces the draft only after confirmation. A dispatched save may still complete after an unrecoverable terminal interruption. Unexpected termination can lose unsaved edits and leave a temporary file or lock from an active save; those artifacts are not a supported recovery mechanism and are never automatically taken over.

The disk lock coordinates cooperating terminal and loopback CLI writers on the selected local file. Use a user-controlled local directory whose filesystem supports atomic replacement. External editors and cloud sync tools do not necessarily honor that lock. Neither --editor local, convert --in-place, older clients, nor MCP writers participate in this transaction protocol. An external writer can race after the final byte check. Network mounts and metadata/ACL parity are not guaranteed. Byte-revision and identity checks detect changes within the supported local transaction boundary, not universal filesystem coordination. A managed GPDoc with a valid active live descriptor joins its existing authenticated collaboration room; local, detached, inactive, and malformed descriptors remain network silent. Live terminal sessions synchronize Yjs source edits, source-relative cursor and selection presence, comments, and suggestions, with bounded offline queuing and reconnect. Close unused local sessions and inspect a reported conflict before choosing Reload.

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 displays the available identity claims without credentials. gpdoc whoami --json returns the same data as structured JSON. 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. The device flow requests offline_access; GPDoc refreshes the short-lived access token automatically while the refresh token remains valid. The access-token expiry shown by whoami is not the expected time until the next interactive login. Refresh-token lifetime and revocation remain controlled by the GPDoc Auth0 tenant. Provider tokens are not shown in command output.

Connect Google Drive or Microsoft 365 from the CLI before listing or writing files. The connect command opens the provider authorization page and waits for GPDoc to confirm the connection. The CLI never prints provider credentials.

gpdoc google connect
gpdoc microsoft connect
gpdoc google status
gpdoc microsoft status

# List the contents of My Drive or OneDrive. Add --shared for provider-shared entries.
gpdoc google list
gpdoc google list --shared
gpdoc microsoft list
gpdoc microsoft list --query "release plan"

# The table identifies folders and document kinds. When another page exists,
# GPDoc tells you to run --next. Use --cursor only for scripts.
gpdoc google list --next
gpdoc google list --cursor 'CURSOR_FROM_JSON'

# Open an item in its provider, or import a supported document into a new
# local GPDoc Markdown file and open it in GPEditor.
gpdoc google list --open 7
gpdoc google list --open-gpdoc 7 --output docs/imported-plan.gpdoc.md
gpdoc microsoft list --open-gpdoc 3

# List GPDoc files you own and files others shared with your GPDoc account.
gpdoc shared list

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

Uploads report preparation, transfer, and completion progress in an interactive terminal. Use --json for script-safe output without progress lines. 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.

--open-gpdoc ROW supports Google Docs and Microsoft Word documents. It imports the selected document into a new managed local .gpdoc.md file, preserves source details as GPDoc metadata, opens that local copy in GPEditor, and leaves the original Google Drive or Microsoft 365 file unchanged. If --output is omitted, GPDoc creates a safe filename in the current directory and refuses to replace an existing file.

If a remote command reports ACCOUNT_STATE_UNAVAILABLE, GPDoc could not verify the signed-in account and intentionally did not send a provider request. Retry after the GPDoc account service recovers, then run gpdoc google status or gpdoc microsoft status to confirm the connection.

Context Lakes

Context Lake commands call the GPDoc Cloudflare Worker using the saved gpdoc login session or an explicit GPDOC_ACCESS_TOKEN override. They never receive GitHub App credentials, Cloudflare credentials, or source-index bindings. For repository discovery and connection, the CLI retrieves the GitHub connection already attached to the signed-in GPDoc account. It does not require, display, or save a second GitHub token. Connect GitHub once in GPDoc before using these commands. After authorization, the CLI can discover and filter candidates, create and manage Context Lakes, edit metadata, manage lake invitations, search selected lakes, and maintain sources. gpdoc knowledge remains a source-command compatibility alias. 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.