GhostOff #

Export public posts from a Ghost CMS and upload them to Offprint via the AT Protocol / Standard.site lexicons.

The live test publication is at https://ghostoff.offprint.app.

View the package on npm: npmx.dev/package/ghostoff.

Installation #

Install globally from npm:

npm install -g ghostoff

Or run directly with npx:

npx ghostoff -- --help

What it does #

• Paginates through Ghost's public Content API for posts.
• Downloads each post's images, resizes them to fit atproto's blob limits, and uploads them as blobs to a PDS.
• Converts Ghost HTML bodies into Offprint's block-based format (app.offprint.content).
• Writes a site.standard.document record per post and an app.offprint.document.article record that points back to it.
• Tracks progress in a local state file so reruns update existing records instead of duplicating them.

Quick start #

Copy .env.example to .env and fill in the secrets:

cp .env.example .env

GHOST_URL=https://your-ghost-site.com
GHOST_API_KEY=your-ghost-content-api-key
ATPUBLICATION_AT_URI=at://did:plc:.../site.standard.publication/...

# Auth: OAuth is the default. Set only if you want password auth.
ATP_IDENTIFIER=your-handle-or-did
# ATP_APP_PASSWORD=your-app-password

Run a dry first pass to inspect what would be uploaded:

npm install
npm run dev -- --dry-run

When you're ready, run the real migration:

npm run dev

If you haven't set ATP_APP_PASSWORD, the CLI will ask:

No app password found in .env or --atproto-app-password. Would you like to authenticate via OAuth [Y/n]?

Answer Y and it will open a browser so you can authenticate with your PDS. If you set ATP_APP_PASSWORD, it uses password auth instead.

Rerunning the same command will putRecord existing records instead of creating duplicates.

CLI options #

Scripts #

npm run dev          # run the migration
npm run build        # compile TypeScript to dist/
npm run typecheck    # type-check without emitting

Project layout #

src/
├── index.ts              # CLI orchestration
├── config.ts             # env + argv loading
├── ghost.ts              # Ghost Content API client
├── assets.ts             # image download, cache, resize, blob upload
├── html-to-offprint.ts   # Ghost HTML -> Offprint blocks
├── facets.ts             # inline formatting -> richtext facets
├── atproto.ts            # auth adapters (OAuth + password), record ops, validation
├── oauth.ts              # loopback OAuth server and file-backed stores
├── state.ts              # idempotency state file
├── rate-limit.ts         # retry + rate-limit helpers
└── types.ts              # shared type definitions

Learning more #

• PLAN.md — the original migration plan.
• docs/session-summary.md — a narrative of how the first version was built.
• docs/development.md — how the codebase is organized.
• docs/next-steps.md — ideas for what to add or improve next.