@a83/orbiter-cli

CLI for Orbiter CMS — scaffold projects, manage users, export content, and sync media with git.

Install

npm install -g @a83/orbiter-cli

Requires Node.js 20+.

Commands

orbiter init [dir]

Scaffold a new Astro + Orbiter project.

orbiter init my-site
cd my-site
npm install
npm run dev

Creates:

• astro.config.mjs — pre-configured with @a83/orbiter-integration
• content.pod — fresh pod with a default Posts collection and admin user
• src/pages/ — example index and blog pages using orbiter:collections
• package.json, .gitignore, GitHub Actions workflow

orbiter add-user

Add an admin or editor user to an existing pod.

orbiter add-user --pod ./content.pod

Interactive prompts: username, password, role (admin or editor).

# Non-interactive
orbiter add-user --pod ./content.pod --username editor1 --role editor

orbiter export

Export all published entries to JSON or Markdown files.

# JSON (default)
orbiter export --pod ./content.pod --out ./export

# Markdown — one .md file per entry, frontmatter for all non-body fields
orbiter export --pod ./content.pod --out ./export --format md

# Single collection
orbiter export --pod ./content.pod --out ./export --collection posts

Output structure:

export/
├── posts/
│   ├── my-first-post.json
│   └── another-post.json
└── pages/
    └── about.json

orbiter unpack

Extract media BLOBs from the pod to regular files. Use before git commit when hosting on platforms with ephemeral filesystems (Netlify, Vercel, GitHub Pages).

orbiter unpack --pod ./content.pod --media-dir ./media

After unpacking, BLOBs are removed from _media.data and a storage.mode=git flag is set in _meta. The pod stays small for git — media files live alongside it.

orbiter pack

Restore media BLOBs from files back into the pod. Run at build time before astro build.

orbiter pack --pod ./content.pod --media-dir ./media

Reads each file in ./media, inserts it as a BLOB, and clears the storage.mode flag.

Git sync workflow

For static hosting (Netlify, Vercel, GitHub Pages):

1. Edit content in the Orbiter admin
2. orbiter unpack  →  extracts media to ./media/
3. git add content.pod media/ && git commit && git push
4. CI: orbiter pack → restores BLOBs → astro build → deploy

GitHub Actions

# .github/workflows/build.yml
name: Build & Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:    # ← triggered by Orbiter's build webhook

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install
      - run: npx orbiter pack --pod ./content.pod --media-dir ./media
      - run: npx astro build
      - uses: actions/deploy-pages@v4

A ready-made workflow file is generated by orbiter init and downloadable from Settings → GitHub → ⬇ Workflow in the admin.

Part of Orbiter

| Package | Description | |---------|-------------| | @a83/orbiter-core | SQLite engine, pod management, auth | | @a83/orbiter-admin | Standalone admin server (Hono, port 4322) | | @a83/orbiter-integration | Astro integration, orbiter:collections virtual module | | @a83/orbiter-cli | This package — CLI tools |

orbiter.sh · MIT · github.com/aeon022/orbiter