booklet-cli

Publish Markdown from your terminal, a CI pipeline, or a script — as Booklet pages with a permanent, shareable URL.

Built for automation first: --key/BOOKLET_API_KEY for non-interactive auth, --update <id> to republish in place instead of minting a new URL every run, and --json on every read command for scripting. The most common use is a CI job that keeps a changelog or release-notes page current — see CI / GitHub Actions below. It works the same way from a terminal, of course; booklet publish README.md is still the whole command.

Install

npm install -g booklet-cli

Or use without installing:

npx booklet-cli publish README.md

Authentication

booklet login

This opens your browser to authorize the CLI. Sign in (or create an account) and you're done, no copy-pasting required. Your key is saved securely — see Credential storage below for where.

CI / non-interactive environments: pass your key directly with --key:

booklet login --key bklt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

You can also set it via environment variable, which takes precedence over the config file:

export BOOKLET_API_KEY=bklt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Generate keys manually at booklet.ashwinsathian.com → My Pages → Settings → API Keys.

Commands

booklet publish [file]

Publish a Markdown file as a Booklet page.

booklet publish README.md
booklet publish NOTES.md --slug my-notes
booklet publish NOTES.md --visibility unlisted
booklet publish README.md --open          # opens the page in your browser

Publish from stdin:

cat CHANGELOG.md | booklet publish -
echo "# Hello world" | booklet publish -

Update an existing page in-place:

booklet publish README.md --update <page-id>

Watch mode: auto-republish on every save

booklet publish README.md --watch
booklet publish README.md --update <id> --watch

Options:

| Flag | Description | |------|-------------| | --slug <slug> | Set a custom URL slug (e.g. my-readme) | | --visibility <v> | public (default) or unlisted | | --update <id> | Update an existing page by ID | | --watch | Watch file and re-publish on change | | --open | Open the page in your browser after publishing |

booklet pages list

List all your published pages. Useful in a script to find the right page ID before calling booklet publish --update <id>, instead of hardcoding it.

booklet pages list
booklet pages list --json                 # machine-readable output
booklet pages list --query "release"      # only pages whose title contains this text
booklet pages list --tag runbook          # only pages with this exact frontmatter tag

booklet pages open <id>

Open a page in your browser. Pass --print to print the URL without opening a browser, or --json for the full page object.

booklet pages open abc123             # opens browser
booklet pages open abc123 --print     # prints URL only
booklet pages open abc123 --json      # prints the page object as JSON
booklet pages open my-custom-slug     # works with slugs too

booklet pages delete <id>

Delete a page by ID or slug. Shows the page title and URL in the confirmation prompt.

booklet pages delete abc123
booklet pages delete abc123 --yes   # skip confirmation prompt

booklet whoami

Show the active API key, base URL, and where the key was loaded from (env var, OS keychain, or config file). Pass --json for machine-readable output.

booklet logout

Remove the saved API key from wherever it's stored (OS keychain and/or ~/.booklet/config.json).

Shell completion

# bash
booklet completion bash >> ~/.bash_completion

# zsh (add to a directory in your $fpath)
booklet completion zsh > "${fpath[1]}/_booklet"

# fish
booklet completion fish > ~/.config/fish/completions/booklet.fish

Frontmatter support

YAML frontmatter in your Markdown is parsed and applied automatically:

---
title: My Release Notes
slug: release-notes-v2
visibility: public
description: Summary of changes in v2.
author: Ashwin Sathian
date: 2026-05-24
---

# Release Notes v2

Content here…

Supported frontmatter fields:

| Field | Type | Notes | |-------|------|-------| | title | string | Overrides the extracted H1 title (max 200 chars) | | slug | string | Custom URL slug (max 60 chars) | | visibility | "public" | "unlisted" | Defaults to public | | description | string | SEO meta description (max 300 chars) | | author | string | Stored as metadata (max 100 chars) | | date | string | Stored as metadata, any format |

Environment variables

| Variable | Description | |----------|-------------| | BOOKLET_API_KEY | API key, overrides ~/.booklet/config.json | | BOOKLET_API_URL | Override API base URL (default: production) | | NO_COLOR | Set to any value to disable ANSI colour output (or pass --no-color) |

Credential storage

booklet login saves your API key to your OS's credential store when available — macOS Keychain, Windows Credential Manager, or Linux Secret Service. On macOS, the first booklet command that touches the keychain may show a one-time system prompt asking to allow access; choosing "Always Allow" avoids repeat prompts.

If no keychain backend is available (common on headless Linux/CI), the key is stored in ~/.booklet/config.json instead, with owner-only file permissions (0600). booklet whoami always shows exactly where your active key came from.

booklet logout removes the key from wherever it's stored.

CI / GitHub Actions

Use the BOOKLET_API_KEY secret to publish from CI:

- name: Publish to Booklet
  env:
    BOOKLET_API_KEY: ${{ secrets.BOOKLET_API_KEY }}
  run: |
    if [ -n "${{ vars.BOOKLET_PAGE_ID }}" ]; then
      npx booklet-cli publish CHANGELOG.md --update ${{ vars.BOOKLET_PAGE_ID }}
    else
      npx booklet-cli publish CHANGELOG.md --slug release-notes --visibility public
    fi

Set BOOKLET_API_KEY under Settings → Secrets → Actions. Set BOOKLET_PAGE_ID as a repository variable to reuse the same URL on every run.

See .github/examples/publish-to-booklet.yml for a complete example workflow.

Links

• booklet.ashwinsathian.com: create your account
• npmjs.com/package/booklet-cli: npm package
• GitHub: source