Oggie

CLI-first V1 of the Oggie calendar metalayer.

Runtime

Oggie uses Supabase Auth as the user identity source and Supabase Postgres for app state. The CLI is a thin client: it calls the Next/Vercel API with an Oggie connection token.

CLI / future MCP / future apps
  -> Next API
  -> Oggie Core
  -> Supabase Auth + Postgres
  -> Google Calendar / Microsoft Calendar

Local Development

Requirements:

• npx supabase available.
• A local Google OAuth web client with http://localhost:3000/api/google/callback as an authorized redirect URI.
• A local Microsoft Entra app registration with http://localhost:3000/api/microsoft/callback as a web redirect URI if you want Microsoft Calendar locally.

Create .env.local:

cp .env.example .env.local
openssl rand -base64 32

Paste the generated key into OGGIE_TOKEN_ENCRYPTION_KEY. Fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from your Google OAuth client. For Microsoft Calendar, also fill in MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, and optionally MICROSOFT_TENANT.

Start Supabase and apply migrations:

npx supabase start

npx supabase start applies local migrations when the local database is first created. To reset local data and re-run migrations:

npm run db:local:reset

Run the web/setup/API app:

npm run setup

Open http://localhost:3000, sign in with Supabase Auth, connect Google Calendar or Microsoft Calendar, create a CLI token, then run:

npm run oggie -- auth login oggie_...
npm run oggie -- tools list
npm run oggie -- calendars list --json
npm run oggie -- events list --from "2026-05-21T00:00:00+08:00" --to "2026-05-22T00:00:00+08:00" --json
npm run oggie -- events create --calendar personal --title "Lunch" --start "2026-05-21T12:00:00+08:00" --end "2026-05-21T13:00:00+08:00"

Read commands search all connected readable calendars by default. Use --calendar to narrow reads, including comma-separated or repeated values:

npm run oggie -- events search dentist --from 2026-05-01 --to 2026-06-01 --calendar personal,work
npm run oggie -- freebusy --from "2026-05-21T09:00:00+08:00" --to "2026-05-21T17:00:00+08:00" --calendar personal --calendar work

Write commands require exactly one explicit --calendar. Common aliases such as personal, work, vigi, magicdoor, and todoist work when they resolve unambiguously from connected calendar metadata.

The shared tool catalog is available locally through both:

npm run oggie -- tools list --json
curl http://localhost:3000/api/tools

Install The CLI

From a local checkout:

npm install -g .

From npm:

npm install -g oggie

From GitHub source:

git clone https://github.com/gijsverheijke/oggie.git
cd oggie
npm install
npm run build
npm install -g .

Then login with a CLI token:

oggie auth login oggie_...
oggie calendars list --json

The installed CLI defaults to https://getoggie.com/api. Set OGGIE_API_URL only when targeting a local or alternate Oggie API.

To uninstall:

npm uninstall -g oggie

Release The CLI

Publishing is handled by GitHub Actions when a version tag is pushed.

One-time setup on npm:

• Open oggie package settings on npmjs.com.
• Add a trusted publisher for GitHub Actions.
• Organization or user: gijsverheijke
• Repository: oggie
• Workflow filename: publish-npm.yml
• Allowed action: npm publish
• Leave environment name blank unless the workflow starts using a GitHub deployment environment.

Release:

npm version patch
git push origin main --tags

Use minor or major instead of patch when appropriate.

Live Supabase

For live, configure Supabase Auth providers and set these server env vars on Vercel:

• OGGIE_APP_URL=https://getoggie.com
• OGGIE_API_URL=https://getoggie.com/api
• SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_URL
• SUPABASE_PUBLISHABLE_KEY
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
• SUPABASE_SECRET_KEY
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REDIRECT_URI=https://getoggie.com/api/google/callback
• MICROSOFT_CLIENT_ID
• MICROSOFT_CLIENT_SECRET
• MICROSOFT_REDIRECT_URI=https://getoggie.com/api/microsoft/callback
• MICROSOFT_TENANT=common
• OGGIE_TOKEN_ENCRYPTION_KEY
• CRON_SECRET
• OGGIE_WEBHOOK_SECRET

Use CRON_SECRET for Vercel Cron. Oggie still accepts OGGIE_CRON_SECRET as a non-Vercel/manual scheduler fallback, but Vercel automatically sends Authorization: Bearer <CRON_SECRET> to cron routes. OGGIE_WEBHOOK_SECRET must be a different random value; Oggie sends it to Google Calendar as the channel token and to Microsoft Graph as clientState.

Apply migrations with Supabase CLI access, or paste the SQL in supabase/migrations/202605280001_rename_google_accounts_to_calendar_accounts.sql into the Supabase SQL editor for production:

npm run db:remote:migrate