GITMD2PDF CLI

The gitmd2pdf command-line interface converts a Git markdown repository, a remote Markdown URL, or a local .md file to PDF — from your terminal or a CI pipeline — without the web UI.

It is a thin client over the Premium API: every conversion is submitted to GITMD2PDF, which runs it and returns the PDF. The CLI handles authentication, the async job poll, and the download for you.

Online only — by design. The CLI never converts locally. It requires a login (an API credential) and always sends the documents to be converted to GITMD2PDF over the network. There is no offline mode: a local .md file is uploaded and converted on the server, exactly like a repo URL or a remote URL. If you need to convert without network access, this CLI is not the right tool.

Requires a Premium subscription and an API credential (created in your Dashboard, under API credentials). The CLI uses the same credentials and the same conversion engine as the API and the web app.

Install

The CLI ships in Phase 1 and is not yet on npm. When published, install will be:

npm install -g gitmd2pdf-cli

A standalone binary (no Node required) for CI images is planned. Until then, run it from the cli/ directory of the repository with node bin/gitmd2pdf.js ….

Requirements: Node.js 22 or newer.

Authenticate

Create an API credential in your Dashboard (OAuth client-credentials or HMAC), then either store it once or supply it via environment variables.

Store it (interactive — saved to ~/.config/gitmd2pdf/credentials.json, permissions 0600):

gitmd2pdf auth login --scheme oauth --client-id <id> --client-secret <secret>
gitmd2pdf auth status      # confirm what's configured

Or use environment variables (recommended for CI):

Environment variables take precedence over the stored file. Secrets are never passed on the command line or logged.

Convert

gitmd2pdf convert <repo-url | https-url | file.md> [options]

The input kind is auto-detected (override with --type):

• a Git repo URL (https://…, git@…, ssh://…) → the whole repository is converted;
• a path to a local .md file → that file is uploaded and converted;
• a remote Markdown URL → pass --type url to convert a single document.

Examples

# Public repo → docs.pdf
gitmd2pdf convert https://github.com/user/docs -o docs.pdf

# Private repo — your PAT is forwarded per request and never stored
gitmd2pdf convert https://gitlab.com/me/private --token "$GL_PAT"

# A specific branch or tag
gitmd2pdf convert https://github.com/user/docs --branch v2.1.0

# A single local Markdown file
gitmd2pdf convert ./README.md

# A remote Markdown document, streamed to stdout
gitmd2pdf convert https://example.com/spec.md --type url --out - > spec.pdf

# Machine-readable result for scripting
gitmd2pdf convert https://github.com/user/docs --json

Options

Private repositories

Pass a Personal Access Token with --token (or the GITMD2PDF_REPO_TOKEN environment variable). The token is sent with that single conversion request, used to clone the repository, and never persisted or logged — the same per-request model the API and web app use. See Git security for how to scope and handle tokens.

Repository configuration

For a repo conversion, GITMD2PDF automatically reads a .gitmd2pdf.yml file from the repository root if present — ignore globs, structure nesting, heading shifts, and more. The CLI behaves identically to the web app here; with --json you can see whether the config was applied.

Exit codes

The CLI automatically retries transient conditions — cold starts (503 while the service warms up), rate limits (429, honouring Retry-After), and brief network blips.

Use in CI

# Example: GitLab CI / GitHub Actions step
script:
  - export GITMD2PDF_OAUTH_CLIENT_ID="$G2P_ID"
  - export GITMD2PDF_OAUTH_CLIENT_SECRET="$G2P_SECRET"
  - gitmd2pdf convert "$CI_PROJECT_URL" --branch "$CI_COMMIT_TAG" -o release.pdf

Store the credentials as protected/masked CI variables, not in the repository.

Troubleshooting

See also

• Premium API — the HTTP API the CLI is built on.
• .gitmd2pdf.yml configuration
• Git security