// 00 — REFERENCE

CLI REFERENCE

wspc is the command-line surface for the wspc workspace. This page covers what --help can’t fit: option semantics, edge values, common patterns. For live truth, run wspc --help and wspc <subcommand> --help.

Examples below use wspc. If not installed globally, prefix with npx.

// 01 — GLOBAL OPTIONS

GLOBAL OPTIONS

Flags and environment variables that apply to every subcommand. Set once per shell session or pass per invocation.

wspc resolves API base URLs and API keys from the active environment. Production is built in. Local dev and custom deploys register through wspc env add. WSPC_ENV overrides the active env. Each WSPC_*_URL overrides the built-in or default URL. Commands that emit structured output accept --json.

// 02 — AUTH AND ENVIRONMENTS

AUTH AND ENVIRONMENTS

wspc is a shared surface for agents and humans. Every service authenticates through a single API key. This section answers two questions: who am I, and which deployment am I talking to. Swap an email magic code for an API key, then switch the active environment between production, local dev, and custom deploys without rewriting config.

wspc login         # Start email magic-code login for the active env.
wspc whoami        # Show the locally cached user for the active env.
wspc verify        # Check that the active env API key still works.
wspc verify --json # Print the verification result as JSON.
wspc logout        # Remove local credentials for the active env.

wspc login exchanges an email magic code for an API key on the active env. whoami reads from the local config file. verify calls the server-side auth API to confirm the cached API key is still valid.

wspc env          # Show the active environment summary.
wspc env ls       # List built-in and custom environments.
wspc env use prod # Switch future commands to the production environment.
wspc env add local \
  --auth http://127.0.0.1:8787 \
  --todo http://127.0.0.1:8788 \
  --calendar http://127.0.0.1:8789 \
  --email http://127.0.0.1:8790 \
  --push http://127.0.0.1:8793
# Register a custom local environment with explicit API URLs.
wspc env rm local # Remove a custom environment from local config.

env add registers API base URLs. Built-in envs (prod) cannot be removed.

// 03 — API KEYS

API KEYS

One key per agent or device. Revoke individually without disturbing the rest. The full key string surfaces exactly once at creation — store it then, or revoke and reissue. Maximum 25 active keys per user. The web console at app.wspc.ai/settings/api-keys mirrors these commands.

wspc keys ls                              # List your active API keys (label, last4, created, last used).
wspc keys create --label "Claude Desktop" # Create a new key; full value printed once.
wspc keys revoke key_01HXX..ABCD          # Soft-revoke a key by id; prompts for confirmation.
wspc keys revoke key_01HXX..ABCD --yes    # Skip the confirmation prompt.

Revocation is a soft delete. The key stops authenticating immediately; the row stays for audit.

// 04 — TODO

TODO

Todo is the shared task store for agents and humans. Hierarchy through parent / child. State flows open → in_progress → done. Delete is soft. Restore brings it back. Hand the agent a backlog and let it triage — mistakes are recoverable.

wspc todo add "Submit expenses"                  # Create a root-level todo.
wspc todo add "Book hotel" --description "Use refundable rate"
# Create a todo with details.
wspc todo add "Draft outline" --parent <todo-id> # Create a child todo.
wspc todo add "File taxes" --due 2026-05-31      # Create a todo with a due date.
wspc todo ls                                     # List active todos.
wspc todo ls --status open in_progress           # List todos matching specific statuses.
wspc todo ls --parent none                       # List root-level todos only.
wspc todo ls --due-before 2026-05-20             # List todos due before 2026-05-20 (exclusive).
wspc todo ls --due-after 2026-05-13              # List todos due on or after 2026-05-13.
wspc todo ls --due-after 2026-05-13 --due-before 2026-05-20
# List todos due in a window — useful for "what's due this week".
wspc todo show <id>                              # Show one todo by id.
wspc todo set <id> --status in_progress          # Move a todo into in-progress state.
wspc todo set <id> --parent none                 # Move a todo back to root-level.
wspc todo set <id> --due 2026-06-01              # Reschedule a todo's due date.
wspc todo set <id> --due ""                      # Clear a todo's due date.
wspc todo set <id> --description ""              # Clear a todo description.
wspc todo done <id>                              # Mark a todo as done.
wspc todo rm <id>                                # Soft-delete one todo.
wspc todo rm <id> --cascade                      # Soft-delete a todo and its descendants.
wspc todo restore <id>                           # Restore a soft-deleted todo.

--parent none lists root-level todos only. todo set --parent none moves a todo back to root. --description accepts Markdown (CommonMark + GFM tables / strikethrough / task lists), stored verbatim server-side, rendered client-side. --description "" clears the description. Omitting the flag leaves it unchanged.

--due accepts YYYY-MM-DD. todo set --due "" clears the due date. Omitting --due leaves it unchanged. For queries, --due-after is an inclusive lower bound, --due-before is an exclusive upper bound. Use either, or both for a window. Due filters currently exclude todos with no due date set.

Delete is soft. todo ls hides soft-deleted todos by default — use --all to include them. todo show hides soft-deleted todos by default — use --include-deleted to view one.

RECURRING TODO RULES

Weekly review, monthly reconciliation, anything cyclical. A rule pairs an RFC 5545 RRULE with a template todo. The system materializes future instances on a rolling horizon, so each cycle gets its own completable row instead of one reopened-forever task. Edits to a rule affect only future materializations — already-materialized history stays put.

wspc todo rrule add "Weekly review" \
  --rrule "FREQ=WEEKLY;BYDAY=MO" \
  --dtstart 2026-05-18
# Create a weekly recurring todo rule and materialize upcoming instances.
wspc todo rrule ls                                # List active recurring rules.
wspc todo rrule show <rule-id>                    # Show a rule and its template snapshot.
wspc todo rrule set <rule-id> --rrule "FREQ=WEEKLY;BYDAY=FR"
# Move the weekly rule to Fridays.
wspc todo rrule rm <rule-id>                      # Soft-delete a recurring rule.
wspc todo rrule rm <rule-id> --expected-version 3 # Delete only if the rule is still version 3.

--rrule accepts an RFC 5545 RRULE pattern — exclude DTSTART and TZID. --dtstart is the first materialization date in YYYY-MM-DD. The rule keeps a template todo and materializes future instances from it.

Materialization horizon: 14 days forward. The system creates one independent todo per RRULE occurrence inside that window — each has its own id, status, and due_at, lives in todo ls, and completes or deletes on its own. Subsequent triggers or edits top up the next 14 days. Creating or editing a rule materializes within the window immediately.

rrule set and rrule rm accept an optional --expected-version optimistic lock. Omit it to use the server’s current version. Pass it only when you need “fail if version has moved”.

// 05 — CALENDAR

CALENDAR

The calendar lets the agent book meetings, reschedule, and dispatch invites on your behalf. Time fields accept ISO 8601 and natural language ("tomorrow 12:30pm", "next Monday 9am"). All-day events, attendees, optimistic lock via --version, and standard .ics export are first-class. Cancelled and soft-delete are distinct: cancelled stays in the lifecycle for notification; rm removes the event from default lists entirely.

wspc event add "Lunch with Alice" \
  --start "tomorrow 12:30pm" \
  --end "tomorrow 1:30pm" \
  --location "Taipei HQ" \
  --attendee "Alice <[email protected]>"
# Create an event from natural-language times and add an attendee.

wspc event add "Team offsite" --start 2026-05-10 --end 2026-05-10 --all-day
# Create a one-day all-day event.
wspc event add "Release review" --start 2026-05-15T09:00:00+08:00 --end 2026-05-15T10:00:00+08:00
# Create an event from exact ISO times.
wspc event ls                                 # List upcoming events.
wspc event ls --include-past                  # Include events that have already ended.
wspc event ls --from "next Monday" --to "next Friday"
# List events in a date range.
wspc event show <event-id>                    # Show one event with details.
wspc event set <event-id> --start "tomorrow 1pm" --end "tomorrow 2pm"
# Reschedule an event.
wspc event set <event-id> --start "next Monday 9am" --end "next Monday 10am" --tz Asia/Taipei
# Parse natural-language times in a chosen timezone.
wspc event set <event-id> --description ""    # Clear the event description.
wspc event set <event-id> --status cancelled  # Mark the event cancelled but keep the record.
wspc event set <event-id> --status confirmed --version 4
# Update only if the event is still version 4.
wspc event rm <event-id>                      # Soft-delete an event from default lists.
wspc event restore <event-id>                 # Restore a soft-deleted event.
wspc event ics <event-id> > event.ics         # Save the event as an iCalendar file.

Time fields accept ISO 8601 or natural language. Natural-language parsing resolves the timezone in this order: --tz <IANA>, WSPC_TZ, system timezone. Example: --tz Asia/Taipei.

--all-day means --start and --end are YYYY-MM-DD, and the CLI input end is inclusive. --start 2026-05-10 --end 2026-05-12 --all-day covers three full days, 5/10 through 5/12.

event set --status cancelled differs from event rm. Cancelled events stay in the calendar lifecycle. rm is soft-delete — default lists hide it.

--version is an optional optimistic lock. Omit to use the server’s current version. Pass when you need to pin the version you last read.

--description accepts Markdown (CommonMark + GFM tables / strikethrough / task lists). Stored verbatim server-side, rendered client-side. Invitation emails carry the raw Markdown text — most email clients show it as plain text.

// 06 — EMAIL

EMAIL

Email gives you @wspc.app addresses for sending and receiving — the agent’s outward identity. Common pattern: spin up a dedicated alias for one stream (subscription, form, notification) and let the agent read, classify, reply, or pipe attachments downstream. One account, many aliases — for example [email protected], [email protected], [email protected]. Deleting an alias stops new mail. Historical mail stays readable.

ALIASES

wspc email alias create [email protected]  # Create a receiving alias.
wspc email alias ls                       # List active aliases.
wspc email alias ls --include-deleted     # Include soft-deleted aliases.
wspc email alias rm [email protected]      # Soft-delete an alias so it stops receiving mail.
wspc email alias restore [email protected] # Reactivate a soft-deleted alias.

The alias identifier is the full @wspc.app email address. The CLI does not accept legacy alias ids or local-part selectors. Deleted aliases stop receiving new mail. Historical mail stays readable. Use restore to bring an alias back online.

INBOX

wspc email ls                            # List recent emails.
wspc email ls --unread                   # List only unread emails.
wspc email ls --since 7d --limit 50      # List up to 50 emails from the last 7 days.
wspc email ls --alias [email protected]   # Filter by full alias address.
wspc email ls --full-body                # Include full text bodies in list output.
wspc email show em_xxx                   # Show one email.
wspc email show em_xxx --full            # Show the full text body without truncation.
wspc email show em_xxx --html            # Show the HTML body source.
wspc email read em_xxx em_yyy            # Mark multiple emails as read.
wspc email unread em_xxx                 # Mark one email as unread.
wspc email rm em_xxx em_yyy              # Soft-delete multiple emails.
wspc email restore em_xxx                # Restore a soft-deleted email.

--alias accepts a full @wspc.app alias email address. --since accepts ISO 8601 or a relative span — for example 2026-05-01, 7d, 24h, 30m. --limit ranges 1-100. Default 20.

read, unread, rm, and restore each accept 1-100 email ids per call.

SEND AND REPLY

wspc email send \
  --from [email protected] \
  --to [email protected] \
  --subject "Hello" \
  --text "Hi from wspc"
# Send a short plain-text email from an alias.

wspc email send \
  --from [email protected] \
  --to [email protected] \
  --subject "Longer note" \
  --text-file ./body.txt \
  --idempotency-key retry-20260515-001
# Send a longer email from a file and make retries safe.

wspc email reply em_xxx --from [email protected] --text-file ./reply.txt
# Reply to an existing email using file content.

--from accepts a full @wspc.app alias email address. Sending is restricted to active aliases. --text-file handles longer bodies. --idempotency-key makes retries safe — the server collapses duplicate sends with the same key.

ATTACHMENTS

wspc email attachment em_xxx 0                      # Download attachment 0 to its original filename.
wspc email attachment em_xxx 0 --output invoice.pdf # Save attachment 0 to a chosen path.
wspc email attachment em_xxx 0 --force              # Overwrite the output file if it exists.

Without --output, the CLI writes to the original filename in the current directory. Existing files are not overwritten by default. Pass --force to overwrite.