CLI reference
wecom-calendar-cli syncs your WeCom calendars over CalDAV into a local SQLite store, then serves fast, agent-friendly queries over that data. Events carry a free-form, agent-maintained metadata layer for your own classification and cross-tool task links. Output is JSON with structured errors. AGENT NOTE: a companion Skill ("wecom-calendar") carries the canonical usage, safety modes, and setup and is the source of truth for driving this CLI. If you are an agent, load that Skill before composing commands. Check status with `wecom-calendar-cli skill status`; install it with `wecom-calendar-cli skill install`.
Generated from the command tree, so it always matches --help.
Global flags
Persistent flags accepted by every command.
| Flag | Default | Description |
|---|---|---|
--allow-writes | false | override read-only mode (defaults.read_only / WECOM_CALENDAR_CLI_READ_ONLY) for this invocation |
--base-url | CalDAV server URL (overrides config) | |
--config | config directory (default ~/.angelmsger/wecom-calendar) | |
--fields | comma-separated dot-path fields to keep | |
--format, -f | output format: json, table or ndjson | |
--pretty | false | human-friendly mode for interactive terminal use only (agents/scripts should omit): TUI in `config init`, colorized JSON elsewhere; errors without a TTY |
--timeout | request timeout, e.g. 30s | |
--use-context | use a named context for this invocation | |
--verbose, -v | false | verbose diagnostics on stderr |
wecom-calendar-cli auth
Inspect and manage stored credentials
wecom-calendar-cli auth
wecom-calendar-cli auth login
Store a credential for the configured server
wecom-calendar-cli auth login
Prompt for the app-specific password and store it securely. Run `config init` first if the server URL is not set.
Examples
wecom-calendar-cli auth login wecom-calendar-cli --use-context personal auth login
wecom-calendar-cli auth logout
Remove the stored credential for the configured server
wecom-calendar-cli auth logout
wecom-calendar-cli auth status
Show whether a usable credential is configured
wecom-calendar-cli auth status
wecom-calendar-cli calendar
List calendars
wecom-calendar-cli calendar
wecom-calendar-cli calendar list
List the calendars in the local store
wecom-calendar-cli calendar list [flags]
List calendars from the local store, with id, display name and change tag. Use --refresh to query the server directly instead.
Options
| Flag | Default | Description |
|---|---|---|
--refresh | false | query the server instead of the local store |
Examples
wecom-calendar-cli calendar list wecom-calendar-cli calendar list --refresh --format table
wecom-calendar-cli config
Manage wecom-calendar-cli configuration
wecom-calendar-cli config
wecom-calendar-cli config delete-context
Delete a context and its stored credential
wecom-calendar-cli config delete-context <name>
Examples
wecom-calendar-cli config delete-context personal
wecom-calendar-cli config get-contexts
List the configured contexts
wecom-calendar-cli config get-contexts
List every context in the config file. The current context — the one used when --use-context is not given — is marked.
Examples
wecom-calendar-cli config get-contexts wecom-calendar-cli config get-contexts --format table
wecom-calendar-cli config init
Interactively set up the CalDAV server URL and credentials
wecom-calendar-cli config init
Run the interactive setup wizard. It collects the CalDAV server URL, your WeCom email and app-specific password, validates them and stores the secret in the OS keychain. It can also configure additional named contexts for working with several accounts.
Examples
wecom-calendar-cli config init --pretty # interactive TUI (recommended) wecom-calendar-cli config init # plain line-by-line wizard (scripts, non-TTY)
wecom-calendar-cli config path
Print the config file path
wecom-calendar-cli config path
wecom-calendar-cli config show
Show the resolved configuration
wecom-calendar-cli config show [flags]
Options
| Flag | Default | Description |
|---|---|---|
--explain | false | annotate each value with its source |
wecom-calendar-cli config use-context
Switch the current context
wecom-calendar-cli config use-context <name>
Set the current context — the account used by default. Override it for a single command with the global --use-context flag instead.
Examples
wecom-calendar-cli config use-context personal
wecom-calendar-cli doctor
Diagnose configuration, credentials and connectivity
wecom-calendar-cli doctor [flags]
Options
| Flag | Default | Description |
|---|---|---|
--no-update-check | false | skip the check for a newer wecom-calendar-cli release |
Examples
wecom-calendar-cli doctor wecom-calendar-cli doctor --no-update-check
wecom-calendar-cli event
Query calendar events
wecom-calendar-cli event
wecom-calendar-cli event get
Show one event in full, including description, location, organizer and attendees
wecom-calendar-cli event get <uid> [flags]
Return the full record for one event by uid — the fields `event list` omits: description, location, organizer, and attendees (each flagged `is_self` for the configured account, so you can tell who else is in the meeting). Find the uid with `event list`. For a specific occurrence of a recurring event, pass --occurrence with its `occurrence_key` to apply that date's overrides.
Options
| Flag | Default | Description |
|---|---|---|
--include-meta | false | attach the event's custom metadata |
--occurrence | apply a specific occurrence's overrides (its occurrence_key) |
Examples
wecom-calendar-cli event get <uid> wecom-calendar-cli event get <uid> --include-meta wecom-calendar-cli event get <uid> --occurrence 1781168400000
wecom-calendar-cli event list
List events in a time window from the local store
wecom-calendar-cli event list [flags]
List events overlapping [--since, --until) from the local store. Dates are YYYY-MM-DD in the display timezone; --since defaults to 30 days ago and --until to 30 days ahead. Run `sync` first to populate the store; a staleness notice on stderr flags out-of-date data. Results are paginated: the JSON envelope carries `has_more` and a `next` cursor. Pass `--cursor <next>` to fetch the following page, or `--all` to return every match in one page (fine here since the query is local).
Options
| Flag | Default | Description |
|---|---|---|
--all | false | return every match in one page (no pagination) |
--calendar | restrict to one calendar id | |
--cursor | continue from a previous page's `next` cursor | |
--include-meta | false | attach each event's custom metadata |
--limit | 0 | page size (0 = default page size unless --all) |
--since | start date YYYY-MM-DD (default 30 days ago) | |
--status | keep only these statuses, comma-separated (e.g. confirmed,tentative) | |
--until | end date YYYY-MM-DD, exclusive (default 30 days ahead) |
Examples
wecom-calendar-cli event list --since 2026-07-01 --until 2026-07-31 wecom-calendar-cli event list --calendar 1688853806313356 --format table wecom-calendar-cli event list --since 2026-01-01 --until 2026-12-31 --all
wecom-calendar-cli expand
Rebuild the expanded event-instances view
wecom-calendar-cli expand [flags]
Recompute event_instances from the stored events: expand recurring masters into occurrences (applying EXDATE and overrides) and fold the same event across calendars into one occurrence. Pure rebuild; runs automatically at the end of `sync`. Never touches your metadata. Occurrences are expanded over a window (default 2 years back to 1 year ahead). Pass --since/--until to widen it when you need to query further into the past or future; a query beyond the window prints a coverage notice on stderr. A window set that way is remembered and reused by every later `sync`, so it survives the next refresh; run `expand` with no flags to forget it and return to the rolling default.
Options
| Flag | Default | Description |
|---|---|---|
--since | expansion window start YYYY-MM-DD (default 2 years ago); pins the window for later syncs | |
--until | expansion window end YYYY-MM-DD (default 1 year ahead); pins the window for later syncs |
Examples
wecom-calendar-cli expand wecom-calendar-cli expand --since 2018-01-01 --until 2030-01-01
wecom-calendar-cli meta
Read and write custom, agent-maintained event metadata
wecom-calendar-cli meta
A free-form key-value layer attached to events by uid, organized under namespaces. Use it for your own classification, notes, or links to tasks in any project-management tool — the schema assumes none. Sync never touches this layer, so re-syncing keeps your annotations.
wecom-calendar-cli meta delete
Delete a metadata entry
wecom-calendar-cli meta delete <uid> <namespace> <key> [flags]
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | show what would be deleted without deleting |
--yes | false | confirm the deletion (required for non-interactive use) |
Examples
wecom-calendar-cli meta delete <uid> task feishu_project --dry-run wecom-calendar-cli meta delete <uid> task feishu_project --yes
wecom-calendar-cli meta get
Get metadata for one event
wecom-calendar-cli meta get <uid> [namespace] [key]
Examples
wecom-calendar-cli meta get <uid> wecom-calendar-cli meta get <uid> task
wecom-calendar-cli meta list
List metadata across events, filtered by uid/namespace/key/value
wecom-calendar-cli meta list [flags]
List custom metadata entries. Filter by any of --uid/--namespace/--key, and by --value to reverse-look-up which events carry a given value — e.g. `--value G123` finds every event linked to that task.
Options
| Flag | Default | Description |
|---|---|---|
--key | filter by key | |
--namespace | filter by namespace | |
--uid | filter by event uid | |
--value | filter by value (substring of the stored JSON) |
Examples
wecom-calendar-cli meta list --namespace task wecom-calendar-cli meta list --key category wecom-calendar-cli meta list --value g-5980639611
wecom-calendar-cli meta set
Set a metadata value on an event
wecom-calendar-cli meta set <uid> <namespace> <key> <value> [flags]
Set metadata under (uid, namespace, key). The value is stored as JSON: a value that already parses as JSON is kept verbatim, otherwise it is stored as a JSON string.
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | show what would be written without writing |
--source | agent | provenance tag: agent, user or auto |
Examples
wecom-calendar-cli meta set <uid> classification category 评审
wecom-calendar-cli meta set <uid> task feishu_project g-5980639611
wecom-calendar-cli meta set <uid> note payload '{"minutes":30}'
wecom-calendar-cli skill
Install the companion Skill for coding agents
wecom-calendar-cli skill
wecom-calendar-cli skill install
Deploy the embedded Skill into a coding agent's skills directory
wecom-calendar-cli skill install [flags]
Write the companion `wecom-calendar` Skill — bundled inside this binary — into a coding agent's skills directory. With no flags it probes for installed agents (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) and installs into each one found. Re-run it after upgrading the CLI to refresh the Skill to the matching version.
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | target agents instead of auto-detecting (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) |
--dir | explicit skills base directory; installs into <dir>/wecom-calendar | |
--project | false | install into each agent's project skills directory instead of $HOME |
wecom-calendar-cli skill path
Print where the Skill would be installed, and whether it is
wecom-calendar-cli skill path [flags]
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | limit to specific agents (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) |
--dir | explicit skills base directory | |
--project | false | use the project skills directories instead of $HOME |
wecom-calendar-cli skill show
Print the embedded SKILL.md to stdout
wecom-calendar-cli skill show
wecom-calendar-cli skill status
Report whether the companion Skill is loaded and installed
wecom-calendar-cli skill status [flags]
Options
| Flag | Default | Description |
|---|---|---|
--project | false | check each agent's project skills directory instead of $HOME |
wecom-calendar-cli skill uninstall
Remove the companion Skill from a coding agent's skills directory
wecom-calendar-cli skill uninstall [flags]
Delete a previously installed `wecom-calendar` Skill. With no flags it probes for installed agents (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) and removes the Skill from each one found.
Options
| Flag | Default | Description |
|---|---|---|
--agent | [] | target agents instead of auto-detecting (claude-code, codex, cursor, agents, gemini, github-copilot, opencode, continue, windsurf, grok, pi, kilo, roo) |
--dir | explicit skills base directory; removes <dir>/wecom-calendar | |
--project | false | remove from each agent's project skills directory instead of $HOME |
wecom-calendar-cli sync
Sync WeCom calendars into the local store
wecom-calendar-cli sync [flags]
Pull calendars and events over CalDAV into the local SQLite store. Incremental by default (calendars whose change-tag is unchanged are skipped); --full rescans everything. Idempotent: re-running is safe and leaves the data unchanged. This never touches your event metadata.
Options
| Flag | Default | Description |
|---|---|---|
--calendar | sync only one calendar id | |
--dry-run | false | report which calendars would be scanned, without writing |
--full | false | ignore change-tags and rescan every calendar |
--progress | auto | progress on stderr: auto (a live line on a terminal, bounded JSON notices otherwise), none, or json |
Examples
wecom-calendar-cli sync wecom-calendar-cli sync --full wecom-calendar-cli sync --calendar 1688853806313356 --dry-run
wecom-calendar-cli version
Print version information
wecom-calendar-cli version
wecom-calendar-cli whoami
Show the configured account (your own identity)
wecom-calendar-cli whoami