pi-share-opengist

A Pi extension that exports the current session to the same self-contained HTML Pi already produces for /export, uploads it to a self-hosted Opengist instance, and prints a shareable link — without relying on the GitHub CLI or GitHub gists.

Visualize with https://gistviewer.l3x.in/

Install

pi install @alexanderfortin/pi-share-opengist

Or, for local development:

git clone https://github.com/shaftoe/pi-share-opengist
cd pi-share-opengist
bun install
bun run build
pi -e ./dist/index.js

Configuration

All configuration is via environment variables (consistent with Pi's existing PI_SHARE_VIEWER_URL convention), so the extension stays stateless.

| Var | Required | Example | Purpose | |---|---|---|---| | PI_OPENGIST_HOST | yes | https://opengist.my.domain | Opengist base URL (no trailing slash) | | PI_OPENGIST_TOKEN | yes | og_… | Bearer token for POST /api/gists | | PI_OPENGIST_VISIBILITY | no | unlisted | public | unlisted | private (gist visibility) | | PI_OPENGIST_PUBLIC | no | — | Legacy: true maps to public (overridden by PI_OPENGIST_VISIBILITY) | | PI_SHARE_VIEWER_URL | no | https://gistviewer.l3x.in/ | Viewer base URL; the full Opengist URL is appended as #<gistUrl>. Defaults to the public gistviewer so links render full-screen out of the box. Set to empty to get the raw Opengist URL. | | PI_OPENGIST_USE_INPROCESS | no | 1 | Opt-in fast path: deep-import Pi's internal exporter instead of shelling out to pi --export |

Usage

In a Pi session with some content, run:

/share-og

You'll get a notification with the share URL (copied to the clipboard when available). By default it's a https://gistviewer.l3x.in/#<opengist-url> link that renders the session full-screen; set PI_SHARE_VIEWER_URL to point at your own viewer, or to an empty string for the raw Opengist URL.

How it works

1. Reads host + token from env; bails with a clear error if missing.
2. Exports the active session to HTML. By default it shells out to the public pi --export <session> CLI (zero coupling to Pi internals). Set PI_OPENGIST_USE_INPROCESS=1 to instead deep-import Pi's internal exportSessionToHtml for an in-process fast path (relies on an internal module path; can break on minor Pi versions).
3. POST {host}/api/gists with an Opengist body, Authorization: Bearer <token>, and visibility: "unlisted" by default (reachable by link, not listed publicly).
4. Parses the returned gist URL/UUID.
5. Builds the share URL — <viewer>#<gistUrl> — defaulting the viewer to https://gistviewer.l3x.in/ so links render full-screen out of the box (override with PI_SHARE_VIEWER_URL; set it empty for the raw Opengist URL). Copies it to the clipboard and notifies.
6. Respects ctx.signal so Esc cancels the upload.

Troubleshooting

• "Set PI_OPENGIST_HOST and PI_OPENGIST_TOKEN…" — both env vars are required.
• Share failed: Opengist responded 401: … — the token is invalid/expired.
• pi --export failed — make sure pi is on your PATH in Pi's launch environment, or switch to the in-process path via PI_OPENGIST_USE_INPROCESS=1.
• In-process export failed … — the internal Pi module moved; unset PI_OPENGIST_USE_INPROCESS to fall back to the CLI.

Development

bun install
bun run check      # typecheck + lint
bun test           # unit tests
bun run build      # typecheck + emit dist/
bun run release:dry-run

Pre-commit hooks run via lefthook: format, lint, and tests.

License

MIT © Alexander Fortin