Run and configure

Ways to start Calendarpit, command-line options, environment variables, Docker setup, and the admin UI.

Calendarpit serves the API, OAuth, and admin UI from one origin.

The commands below use the packaged distribution. You need no source checkout or build. See Installation for prerequisites and supported platforms.

Ways to run Calendarpit

Installed CLI

Install with Homebrew or place a standalone executable on your PATH. Then run it from your project directory. See Installation for setup.

calendarpit serve --port 4173
calendarpit serve --port 0 --database :memory:

These are alternative startup commands:

  • Run one server per database file.
  • Port 0 lets the OS choose an available port.
  • Read the actual URLs in the startup output:
Calendarpit data: :memory:

Calendarpit v<version>
Data   :memory:
Admin  http://127.0.0.1:38425/
API    http://127.0.0.1:38425/calendar/v3
Health http://127.0.0.1:38425/__calendarpit/health

The packaged executable includes the server, the admin UI assets (including favicon.svg), and the Bun runtime. You need no separate Node.js or Bun installation. Stop the server with Ctrl+C.

Docker and Compose

docker run --rm \
  -p 127.0.0.1:4173:4173 \
  -v calendarpit-data:/data \
  ghcr.io/iktakahiro/calendarpit:latest

The container has these defaults:

  • It runs as a non-root user.
  • It sets CALENDARPIT_HOST=0.0.0.0 and CALENDARPIT_PORT=4173.
  • It stores the SQLite database at /data/calendarpit.sqlite.

The published host port stays on loopback. Add environment variables with -e before the image name. Add CLI flags after it:

docker run --rm -p 127.0.0.1:4173:4173 \
  ghcr.io/iktakahiro/calendarpit:latest serve --database :memory:

Related pages:

Command-line options and environment variables

The CLI syntax is calendarpit [serve] [options]. The serve subcommand is optional.

The CLI prints an error to stderr and exits with code 1 on any of these:

  • an unknown command
  • an unknown flag
  • an invalid option value

Command-line flags take precedence over environment variables.

CLI optionEnvironment variableDefaultDescription
--host <host>CALENDARPIT_HOST127.0.0.1Bind address. Non-loopback addresses (0.0.0.0, ::) must be set explicitly.
-p, --port <n>CALENDARPIT_PORT4173Listen port (0–65535). Use 0 to let the OS choose a free port.
--database <path>CALENDARPIT_DATABASE.calendarpit/calendarpit.sqliteSQLite database file path, or :memory: for a disposable in-memory session. See Storage and restarts.
--config <path>CALENDARPIT_CONFIGBuilt-in fixturePath to a JSON startup fixture. See Fixtures.
-h, --help——Print help and exit.
-v, --version——Print the version and exit.

Option details:

  • --port 0: The assigned port appears in the startup output.
  • Port 4175: Avoid it if you also run the reference sample app.
  • --config: The file must exist and contain valid JSON. It seeds a new database or a :memory: session.

--config is silently ignored when Calendarpit opens an existing SQLite file.

Additional environment variables

Environment variableDefaultDescription
CALENDARPIT_WATCH_HOSTSLoopback onlyComma-separated extra hostnames allowed as events.watch and calendarList.watch webhook targets.

About CALENDARPIT_WATCH_HOSTS:

  • Example: host.docker.internal when running in Docker.
  • It is an environment variable only. There is no CLI flag.
  • See Watch notifications.

Loopback binding and working directory

Loopback by default. Calendarpit binds to 127.0.0.1 unless you pass --host or CALENDARPIT_HOST.

The admin UI and test control API have no authentication. Binding to 0.0.0.0 exposes them to other machines on your network.

Relative paths. Path resolution depends on how you run Calendarpit:

  • Homebrew and standalone executables: Paths in --database and --config (or their environment variables) resolve from the directory where you start Calendarpit. Run it from your project directory or use absolute paths.
  • Docker: Paths are inside the container. Mount host files before referencing them.

See Troubleshooting for common startup errors.

Admin UI

The admin UI is served at the root of the same origin as the API. The default URL is http://127.0.0.1:4173/.

  • It polls GET /__calendarpit/state and request history every 2 seconds. Changes made by your app appear automatically.
  • Use the left rail to switch the selected test user and calendar (?user=<id>&calendar=<id>).
  • The left rail also shows whether storage is SQLite or In-memory.

The admin UI loads the Roboto Mono font from Google Fonts (fonts.googleapis.com and fonts.gstatic.com). It falls back to system fonts when offline. Calendar API and OAuth operations never contact Google and need no internet access.

RouteScreenPurpose
/ScheduleView, create, edit, and delete events.
/usersUsersList, create, edit, and delete test users.
/calendarsCalendarsManage calendars for the selected test user.
/connectionsConnectionsInspect and revoke OAuth grants.
/watchWatchRead-only view of watch channels and webhook deliveries.
/historyAPI historyInspect and clear recent Calendar API and OAuth traffic.
/settingsSettingsTheme, storage, fixtures, reset, state, and OAuth setup.

Schedule

  • View stored events in day or week mode. The default date is 2026-10-19.
  • Create, edit, and delete events. The editor covers the summary, all-day toggle, start/end, busy/free status, location, description, and extended properties JSON.
  • A recurring series appears once, at its first occurrence. It is not expanded.

Saving an event in the editor overwrites it with only the fields shown in the form:

  • Attendees, colors, and other fields set through the Calendar API are removed.
  • A recurring event loses its recurrence.
  • Custom reminders reset to the default (reminders: { useDefault: true }).

Use the Calendar API to edit those events.

Users

  • List, create, edit, and delete test users.
  • Deleting a user also deletes their calendars and events.
  • Deleting a user also revokes their OAuth connections, which stops their watch channels.

Calendars

  • List, create, edit, and delete calendars for the selected test user.
  • Set the IANA time zone. The default is Asia/Tokyo.
  • Choose the primary calendar.

Connections

  • Inspect active and revoked OAuth grants by test user and OAuth client.
  • Revoke active grants. Revoking a grant stops its watch channels.
  • See Local OAuth.

Watch

  • Read-only view of active watch channels and the webhook delivery log.
  • See Watch notifications.

API history

  • Inspect the latest 200 Calendar API and OAuth exchanges. Credentials are masked.
  • Filter exchanges by text, or show only HTTP >= 400 errors.
  • Clear the history.

Settings

  • Switch the theme (Appearance).
  • View the storage path.
  • Load a fixture JSON file.
  • Reset the workspace to its reset baseline.
  • Inspect the current state JSON (Test data).
  • View registered OAuth clients and redirect URIs (OAuth clients).

Installation

Install Calendarpit with Docker Compose, Homebrew, or a standalone executable.

Connect your app

Point your app's OAuth and Google Calendar SDK clients at Calendarpit while keeping production Google settings switchable.

On this page

Ways to run CalendarpitInstalled CLIDocker and ComposeCommand-line options and environment variablesAdditional environment variablesLoopback binding and working directoryAdmin UIScheduleUsersCalendarsConnectionsWatchAPI historySettings