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. NDJSON lists keep rows on stdout and emit pagination notices on stderr; pass the notice's next value as --cursor to continue. 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`. After a CLI upgrade, refresh the Skill and reload the agent context.
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 |
--auth-scheme | authentication scheme (overrides environment and config); basic is the only one WeCom CalDAV accepts | |
--base-url | CalDAV server URL (overrides config) | |
--config | config directory (default ~/.angelmsger/wecom-calendar) | |
--credential-url | credential acquisition page URL (display only) | |
--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 guide
Show offline credential acquisition guidance for this service
wecom-calendar-cli auth guide
Explain where the CalDAV password comes from, without touching the network or the credential store. WeCom issues the password in its mobile app and has no web page for it, so credential_url is empty unless a team configured a page of its own; no request is ever sent to that URL. Issuing a new password invalidates the previous one, and the instructions say when not to. When another context on the same server already has a WeCom email, the guide puts auth reuse first: it completes this context without any password.
wecom-calendar-cli auth login
Verify and store personal credentials for the configured service
wecom-calendar-cli auth login
Reuse the configured service, show where the CalDAV password comes from, and store a verified password together with its WeCom email. Issuing a new password in WeCom invalidates the previous one. Requires a terminal; use the credential environment variables for non-interactive execution.
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 reuse
Reuse an existing login in the selected context without signing in again
wecom-calendar-cli auth reuse [flags]
Fill in the selected context's missing WeCom email from another context on the same service whose stored login still works, instead of asking for a CalDAV password. Stored passwords are keyed by server host and scheme, so contexts on one server already share one, and nothing is copied. Reuse matches stored contexts by complete service URL and scheme, verifies the stored password with a candidate's email through the calendar-home check auth login runs, and records that email on the selected context. It never replaces an existing email, reads credentials from environment variables, switches the scheme or activates a context. --dry-run performs the same read-only verification and reports the proposed association. An unchanged or unavailable result is not proof of authentication; use auth status to check.
Options
| Flag | Default | Description |
|---|---|---|
--dry-run | false | verify and preview the identity association without writing |
--from-context | choose a matching source from config get-contexts when multiple identities are available |
Examples
wecom-calendar-cli --use-context team auth reuse --dry-run wecom-calendar-cli --use-context team auth reuse wecom-calendar-cli --use-context team auth reuse --from-context personal
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>
Delete a context from the config file, together with its stored credential. The credential is kept when another context on the same server still uses it: a new CalDAV password would invalidate the previous one.
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 set-context
Configure service presets without credentials or network access
wecom-calendar-cli config set-context <name> [flags]
Write service fields from flags, environment or .env over the named target context. Personal environment fields and secrets — the WeCom email and the CalDAV password — are ignored. Existing conflicting fields require --overwrite; unrelated contexts and user identities are preserved. The server URL defaults to the public WeCom CalDAV endpoint, so --base-url is needed only for another endpoint.
Options
| Flag | Default | Description |
|---|---|---|
--activate | false | make this the current context |
--dry-run | false | preview configuration changes without writing files or credentials |
--overwrite | false | update conflicting service fields; preserve personal identity and credentials |
Examples
wecom-calendar-cli config set-context team --dry-run wecom-calendar-cli config set-context team --credential-url https://wiki.example.com/wecom-caldav --activate
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 the half-open window [from, to) from the local store. Run `sync` first to populate it; a staleness notice on stderr flags out-of-date data. --since <duration> looks back from now (24h, 7d). --from is an inclusive lower bound and --to an exclusive upper bound; each takes YYYY-MM-DD (midnight in the display timezone, Asia/Shanghai), an RFC 3339 instant with an offset, or now±duration. A calendar looks ahead, so a bound may lie in the future: --from now --to now+14d. --since cannot be combined with --from/--to, and --to requires --from. With no window flag the window is 30 days either side of today, on local day boundaries; with --from alone it ends 30 days ahead. Results are paginated: the JSON envelope carries `has_more` and a `next` cursor, and --format ndjson reports the same on stderr as `_notice.pagination`. Pass `--cursor <next>` with the same window to fetch the following page, or `--all` to return every match in one page (fine here since the query is local). A cursor needs fixed bounds: page with absolute --from/--to. A window relative to the current time (--since, now±duration) is rejected with --cursor; read it with --all instead.
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; needs the same fixed window | |
--from | window start, inclusive: YYYY-MM-DD, RFC 3339 with an offset, or now-7d (default 30 days ago) | |
--include-meta | false | attach each event's custom metadata |
--limit | 0 | page size (0 = default page size unless --all) |
--since | look back this far from now, e.g. 24h or 7d (a YYYY-MM-DD value is a deprecated alias of --from) | |
--status | keep only these statuses, comma-separated (e.g. confirmed,tentative) | |
--to | window end, exclusive, same forms; may be in the future, e.g. now+14d; requires --from (default 30 days ahead) | |
--until | deprecated alias of --to |
Examples
wecom-calendar-cli event list --from 2026-07-01 --to 2026-08-01 wecom-calendar-cli event list --since 7d wecom-calendar-cli event list --from now --to now+14d --calendar 1688853806313356 --format table wecom-calendar-cli event list --from 2026-01-01 --to 2027-01-01 --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 --from/--to 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. Each bound takes YYYY-MM-DD (midnight in the display timezone, Asia/Shanghai) or an RFC 3339 instant with an offset, and either may be given alone. 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. There is no look-back --since here: a window ending now would drop every future occurrence.
Options
| Flag | Default | Description |
|---|---|---|
--from | expansion window start: YYYY-MM-DD or RFC 3339 with an offset (default 2 years ago); pins the window for later syncs | |
--since | deprecated alias of --from (YYYY-MM-DD only; a look-back duration is rejected) | |
--to | expansion window end, exclusive, same forms (default 1 year ahead); pins the window for later syncs | |
--until | deprecated alias of --to |
Examples
wecom-calendar-cli expand wecom-calendar-cli expand --from 2018-01-01 --to 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, then reload the agent context.
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 Skill paths, installation state and version alignment
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 loaded, installed and embedded Skill versions
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