CLI reference

Generated from the same command tree meridian --help renders from, so the two can never disagree.

meridian run

Start the reconciliation loop

meridian run [options]

Loads and validates config, builds adapters, runs a read-only startup auth probe against every configured calendar, then cycles on the config’s interval until SIGINT/SIGTERM.

No reconciliation cycle runs (outside --once) until every calendar’s auth probe passes — a pod that never becomes ready has provably written and deleted nothing.

See also: metrics & health, Deploy on Kubernetes.

--configDefault: rules.yaml · Env: MERIDIAN_CONFIG

path to rules.yaml

--onceDefault: false

run a single cycle and exit

--listenDefault: [::]:8080 · Env: MERIDIAN_LISTEN

observability listen address (/metrics, /healthz, /readyz)

meridian validate

Validate a rules.yaml (no credentials needed)

meridian validate [options]

Strict parse, every reference check, CEL and template compilation — everything run does at startup except resolving secret env vars and the live auth probes. Safe for CI.

--configDefault: rules.yaml · Env: MERIDIAN_CONFIG

path to rules.yaml

--from-configmapDefault: false

treat the config file as a k8s ConfigMap manifest and validate its data key “rules.yaml” (e.g. helm template output, kubectl get cm -o yaml)

meridian wipe

Delete this instance’s shadow events (explicit cleanup)

meridian wipe

The explicit-cleanup counterpart to the automatic per-cycle sweep, which only ever touches calendars currently targeted by a rule. Listing here is unbounded: it also reaches shadows outside the normal sync window. Only markers belonging to the resolved instance ID are ever touched.

Both subcommands print a plan (how many shadows, on which calendars) and prompt for confirmation before deleting anything; --yes skips the prompt for scripting. --instance targets a different instance ID than the one in your current config — useful after renaming an instance, when the old shadows are otherwise invisible and need a one-time manual cleanup.

See also: Operate.

meridian wipe calendar

Delete ALL of this instance’s shadows on one calendar

meridian wipe calendar <account/calendar> [options]

--configDefault: rules.yaml · Env: MERIDIAN_CONFIG

path to rules.yaml

--yesDefault: false

skip the confirmation prompt

--instance

wipe shadows of this instance ID instead of the configured one (post-rename cleanup)

meridian wipe rule

Delete one rule’s shadows (all calendars, or --calendar)

meridian wipe rule <rule-id> [options]

--configDefault: rules.yaml · Env: MERIDIAN_CONFIG

path to rules.yaml

--yesDefault: false

skip the confirmation prompt

--instance

wipe shadows of this instance ID instead of the configured one (post-rename cleanup)

--calendar

narrow to one account/calendar

meridian oauth

Interactive OAuth bootstrap for provider accounts (Google)

meridian oauth [options]

Runs the local-loopback OAuth consent flow and obtains a refresh token. By default the token is printed to stdout (pipe it into your secret store). With --write-env FILE the token is instead written into FILE as MERIDIAN_GOOGLE_REFRESH_TOKEN=… without ever being displayed.

The OAuth consent screen must be published to Production status in Google Cloud Console — apps left in Testing mode issue refresh tokens that expire after 7 days, unworkable for a long-running sync engine.

--client-idEnv: MERIDIAN_GOOGLE_CLIENT_ID

OAuth client ID (Desktop-app type)

--client-secretEnv: MERIDIAN_GOOGLE_CLIENT_SECRET

OAuth client secret

--portDefault: 5555

localhost callback port

--write-env

write the refresh token into this env file instead of printing it

--env-keyDefault: MERIDIAN_GOOGLE_REFRESH_TOKEN

env key to write with --write-env

meridian identities

Ask a CalDAV server which addresses it knows this account by

meridian identities [account] [options]

Reading your own RSVP off an invitation means picking your entry out of the attendee list. Google marks it; iCalendar has no equivalent, so a CalDAV account has to name its own addresses in identities before filter.skipDeclined or transform.transparentForRSVP can work.

This asks the server directly, via the calendar-user-address-set property, and prints the answer ready to paste. It also lists the account’s calendars and their paths, which a config needs anyway and which providers tend to bury in a web UI.

Run it against a configured account by name, or before any config exists by passing --endpoint with credentials in the environment or a local .env. Nothing is written: the config is usually a ConfigMap in git.

--configDefault: rules.yaml · Env: MERIDIAN_CONFIG

path to rules.yaml

--endpointEnv: MERIDIAN_CALDAV_ENDPOINT

CalDAV base URL, to run without a config file

--usernameEnv: MERIDIAN_CALDAV_USERNAME

CalDAV username (prefer MERIDIAN_CALDAV_USERNAME in a .env)

--passwordEnv: MERIDIAN_CALDAV_PASSWORD

CalDAV password (prefer MERIDIAN_CALDAV_PASSWORD in a .env)

meridian version

Print build version information

meridian version

Tag, commit, and build date via -ldflags in release builds; falls back to Go’s toolchain-embedded build info (debug.ReadBuildInfo) for local builds.