# Comms CLI > Comms messaging CLI. View and respond to inbox threads, channel threads, direct messages, mentions, and group conversations; search, react, archive, mute, and manage workspaces. Use when the user mentions Comms, asks about their inbox, mentions, threads, DMs, channels, or wants to read or send Comms messages. - Skill: `doist/comms-cli` (Agent Skill) - Install (CLI): `npx skillmds@latest add doist/comms-cli` - Raw SKILL.md: https://api.skillmd.com/api/skills/doist/comms-cli/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: Doist (https://skillmd.com/u/doist) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/doist/comms-cli --- # Comms CLI (tdc) Access Comms messaging via the `tdc` CLI. Use when the user asks about their Comms workspaces, threads, messages, or wants to interact with Comms in any way. ## Setup ```bash tdc auth login # OAuth login (standard write scopes) tdc auth login --read-only # OAuth login with read-only scope tdc auth login --full-access # OAuth login with delete/admin scopes tdc auth login --credential-store system # Require the system credential manager tdc auth login --credential-store plaintext # Explicitly allow plaintext config storage tdc auth login --callback-port # Override the local OAuth callback port (default 8766) tdc auth login --json # Emit a JSON envelope for scripted / agent use tdc auth login --ndjson # Emit an NDJSON envelope for scripted / agent use tdc auth token # Save API token manually (prompts securely; scope unknown, assumed write-capable) tdc auth token --credential-store system # Require the system credential manager tdc auth status # Verify authentication + show mode tdc auth status --json # Full status payload as JSON (--ndjson also supported) tdc auth status --user # Target a specific stored account (id, id:, or display name) tdc --user auth # Equivalent to passing --user after the subcommand; other commands accept the flag but ignore it tdc auth logout # Remove saved token and auth metadata tdc auth logout --json # Emits `{"ok": true}` (--ndjson is silent) tdc auth logout --user # Target a specific stored account; mismatched ref errors with ACCOUNT_NOT_FOUND tdc auth token view # Print the saved token to stdout (pipe-safe; refuses if COMMS_API_TOKEN is set) tdc auth token view --user # Print the saved token for a specific stored account tdc auth refresh-token view # Print the saved OAuth refresh token to stdout (pipe-safe; OAuth logins only) tdc auth refresh-token view --user # Print the saved OAuth refresh token for a specific stored account tdc account [list|current|use |remove ] # Manage stored accounts; all support --json/--ndjson # current's payload is {id, label, authMode, authScope, source:"config"} | {source:"env"} | {source:"token-only"} tdc auth login # Re-running auth login with a different OAuth grant adds a NEW account; default stays pinned unless none was set tdc workspaces # List available workspaces tdc workspaces --ids-only # Output only workspace IDs tdc workspace use # Set current workspace tdc completion install # Install shell completions tdc config view # Show the current CLI configuration file (token masked) tdc config set # Set a user preference (e.g. unarchive-new-threads true) tdc doctor # Diagnose CLI setup and environment issues tdc update # Update CLI to latest version tdc changelog # Show recent changelog entries tdc migrate urls # Translate old twist.com URLs to Comms URLs (needs a Twist token) ``` OAuth login uses Todoist OAuth for Comms access. The default grant can read Comms data and create/update content or messages. It does not include delete, channel management, or user/workspace write scopes; use `tdc auth login --full-access` only when needed (all `tdc groups` writes require it). Credential storage defaults to `fallback`: use the system credential manager when available, otherwise warn and save to `~/.config/comms-cli/config.json`. Pass `--credential-store system` to fail instead of writing plaintext, or `--credential-store plaintext` to choose config-file storage explicitly. `COMMS_API_TOKEN` always takes priority over the stored token. In read-only mode (`tdc auth login --read-only`), commands that modify Comms data (reply, archive, react, delete, etc.) are blocked by the CLI. Externally provided tokens (`COMMS_API_TOKEN` or `tdc auth token`) are treated as unknown scope and assumed write-capable. ## View by URL ```bash tdc view # View any Comms entity by URL ``` Routes automatically based on URL structure: - Message URL → `tdc msg view` - Conversation URL → `tdc conversation view` - Thread+comment URL → `tdc thread view` (comment ID extracted from URL) - Thread URL → `tdc thread view` URLs may use either `https://comms.todoist.com/{workspaceId}/...` or `https://comms.todoist.com/a/{workspaceId}/...`. All target command flags pass through (e.g. `--json`, `--raw`, `--full`). ## Inbox ```bash tdc inbox # Show inbox threads tdc inbox --unread # Only unread threads tdc inbox --archive-filter all # Show active + done threads tdc inbox --archive-filter archived # Show only done threads tdc inbox --channel # Filter by channel name (fuzzy) tdc inbox --since # Filter by date (ISO format) tdc inbox --limit # Max items (default: 50) tdc inbox --ids-only # Output only thread IDs, one per line ``` ## Threads ```bash tdc thread # View thread (shorthand for view) tdc thread view # View thread with comments tdc thread view --comment # View a specific comment tdc thread view # Comment ID extracted from URL tdc thread view --unread # Show only unread comments tdc thread view --context 3 # Include 3 read comments before unread tdc thread view --limit 20 # Limit number of comments tdc thread view --since # Comments newer than date tdc thread view --raw # Show raw markdown tdc thread create "Title" "content" # Create a new thread tdc thread create "Title" "content" --json # Create and return as JSON tdc thread create "Title" "content" --json --full # Include all thread fields tdc thread create "Title" "content" --notify 123,Cbzzm11ZeYZoJYD4a6rti # Notify user and/or group IDs tdc thread create "Title" "content" --unarchive # Land thread in author's Inbox (overrides default Comms auto-archive) tdc thread create "Title" "content" --no-unarchive # Force archive even when userSettings.unarchiveNewThreads=true tdc thread create "Title" "content" --dry-run # Preview without posting tdc thread create "Title" --file ./a.png # Attach a file (repeatable; content optional) tdc thread reply "content" # Post a comment (notifies EVERYONE_IN_THREAD by default) tdc thread reply "content" --notify EVERYONE # Notify all workspace members tdc thread reply "content" --notify 123,id:456 # Notify specific users by ID tdc thread reply "content" --notify 123,Cbzzm11ZeYZoJYD4a6rti # Notify a user and a group (group IDs are base58, not numeric) tdc thread reply "content" --json # Post and return comment as JSON tdc thread reply "content" --json --full # Include all comment fields tdc thread reply "content" --close # Reply and close the thread tdc thread reply "content" --reopen # Reply and reopen a closed thread tdc thread reply "content" --file ./a.png # Attach a file (repeatable; content optional) tdc thread done # Preview thread archive (requires --yes to execute) tdc thread done --yes # Archive thread (mark done) tdc thread done --yes --json # Archive and return status as JSON tdc thread mark-read # Mark a thread read tdc thread mark-read --yes # Mark multiple threads read printf "id:CbT8n2Kp4Qx6Rz9Lm3Va\nid:CbT9m4Qr7Vz2Nx8Lp5Sa\n" | tdc thread mark-read --dry-run # Preview bulk mark-read from stdin tdc thread mute # Mute thread for 60 minutes (default) tdc thread mute --minutes 480 # Mute for custom duration tdc thread mute --json # Mute and return { id, mutedUntil } as JSON tdc thread mute --json --full # Mute and return full thread as JSON tdc thread unmute # Unmute a muted thread tdc thread unmute --json # Unmute and return { id, mutedUntil } as JSON tdc thread delete # Preview thread deletion (requires --yes to execute) tdc thread delete --yes # Permanently delete a thread tdc thread delete --yes --json # Delete and return status as JSON tdc thread rename "New title" # Rename a thread (change its title) tdc thread rename "New title" --json # Rename and return { id, title } as JSON tdc thread rename "New title" --json --full # Rename and return full thread as JSON tdc thread update "New body" # Update a thread's body (the first post) echo "New body" | tdc thread update # Update body from stdin tdc thread update "New body" --dry-run # Preview without updating tdc thread update "New body" --json # Update and return { id, content } as JSON tdc thread update "New body" --json --full # Update and return full thread as JSON ``` Default `--notify` for reply is EVERYONE_IN_THREAD, which may notify more people than intended. Before posting, confirm with the user whether specific people should be notified instead (via `--notify `). Options: EVERYONE, EVERYONE_IN_THREAD, or comma-separated user and/or group IDs. `--notify` automatically resolves IDs: group IDs are routed to the `groups` API field, user IDs to `recipients`. No special syntax needed. ## Thread Comments ```bash tdc comment # View a comment (shorthand for view) tdc comment view # View a single thread comment tdc comment view --raw # Show raw markdown tdc comment view --json # Output as JSON tdc comment view --ndjson # Output as newline-delimited JSON tdc comment view --json --full # Include all fields in JSON output tdc comment update "new content" # Update a thread comment tdc comment update "content" --json # Update and return updated comment as JSON tdc comment update "content" --json --full # Include all comment fields tdc comment delete # Preview comment deletion (requires --yes to execute) tdc comment delete --yes # Delete a thread comment tdc comment delete --yes --json # Delete and return status as JSON ``` ## Conversations (DMs/Groups) ```bash tdc conversation unread # List unread conversations tdc conversation list # List active conversations (DMs and groups) tdc conversation list --kind group # Only group conversations (3+ people) tdc conversation list --kind direct # Only 1:1 conversations (and your self-DM) tdc conversation list --participant "Jane" # Only conversations including these users (comma-separated) tdc conversation list --name "release" # Filter by title substring (case-insensitive) tdc conversation list --state archived # Archived conversations only (active|all|archived; default active) tdc conversation list --snippet # Include the latest message snippet tdc conversation list --limit 20 --json # Cap rows and output as JSON tdc conversation list --ids-only # Output only conversation IDs tdc conversation unread --ids-only # Output only unread conversation IDs tdc conversation # View conversation (shorthand for view) tdc conversation view # View conversation messages tdc conversation with # Find your 1:1 DM with a user tdc conversation with --snippet # Include the latest message preview tdc conversation with --include-groups # List any conversations with that user tdc conversation reply "content" # Send a message tdc conversation reply "content" --json # Send and return message as JSON tdc conversation reply "content" --json --full # Include all message fields tdc conversation reply "content" --file ./a.png # Attach a file (repeatable; content optional) tdc conversation done # Preview conversation archive (requires --yes to execute) tdc conversation done --yes # Archive conversation tdc conversation done --yes --json # Archive and return status as JSON tdc conversation mute # Mute conversation for 60 minutes (default) tdc conversation mute --minutes 480 # Mute for custom duration tdc conversation mute --json # Mute and return { id, mutedUntil } as JSON tdc conversation mute --json --full # Mute and return full conversation as JSON tdc conversation unmute # Unmute a muted conversation tdc conversation unmute --json # Unmute and return { id, mutedUntil } as JSON ``` Alias: `tdc convo` works the same as `tdc conversation`. ## Conversation Messages ```bash tdc msg # View a message (shorthand for view) tdc msg view # View a single conversation message tdc msg update "content" # Edit a conversation message tdc msg update "content" --json # Edit and return updated message as JSON tdc msg update "content" --json --full # Include all message fields tdc msg delete # Preview message deletion (requires --yes to execute) tdc msg delete --yes # Delete a conversation message tdc msg delete --yes --json # Delete and return status as JSON ``` Alias: `tdc message` works the same as `tdc msg`. ## Search ```bash tdc mentions # Show content mentioning current user tdc mentions --since 2026-04-01 --all # Fetch every mention since a date tdc mentions --type threads --json # Limit mentions to threads tdc search "query" # Search content tdc search "query" --type threads # Filter: threads, messages, or all tdc search "query" --author # Filter by author tdc search "query" --to # Messages sent to user tdc search "query" --title-only # Search thread titles only tdc search "query" --mention-me # Results mentioning current user tdc search "query" --conversation # Limit to conversations (comma-separated refs) tdc search "query" --since # Content from date tdc search "query" --until # Content until date tdc search "query" --channel # Filter by channel refs (comma-separated) tdc search "query" --limit # Max results (default: 50) tdc search "query" --cursor # Pagination cursor tdc search "query" --all # Fetch all result pages ``` ## Users, Channels & Groups ```bash tdc user # Show current user info tdc user --json # JSON output tdc user --json --full # Include all fields in JSON output tdc users # List active workspace users tdc users --search # Filter by name/email tdc users --include-removed # Include users removed from the workspace tdc users --ids-only # Output only user IDs tdc channels # List active joined workspace channels (alias of: tdc channel list) tdc channels --state all # Include archived joined channels too tdc channels --scope discoverable # Active public channels you can see but have not joined tdc channels --scope public --state all --json # All visible public channels, with joined status tdc channels --ids-only # Output only channel IDs tdc channel create "Engineering" # Create a channel in the current workspace tdc channel create "Leadership Team" --private --users id:10,id:20 # Create private channel with initial members tdc channel create "Product" --workspace "Doist" --description "Product discussions" --json # Create and return channel as JSON tdc channel update "New name" # Rename a channel tdc channel update --name "New name" # Rename with an explicit flag tdc channel update --description "Team discussions" # Update channel description tdc channel update --clear-description # Clear channel description tdc channel update --public # Make a channel public (--private makes it private) tdc channel update --description "Team discussions" --json --full # Update and return all channel fields tdc channel delete --yes # Permanently delete a channel (requires --yes; usually admin-only) tdc channel delete --dry-run # Preview deletion tdc channel archive # Archive a channel (no-op if already archived) tdc channel unarchive id: # Unarchive a channel (pass id: for archived channels) tdc channel threads # List threads in a channel (fuzzy name, id:, or URL) tdc channel threads "general" --unread # Only unread threads tdc channel threads --archive-filter all # Include archived threads (active|archived|all) tdc channel threads --since 2026-01-01 # Filter by last-updated date (ISO) tdc channel threads --limit 20 # Max threads per page (default: 50) tdc channel threads --limit 20 --cursor # Paginate tdc channel threads --json # { results, nextCursor } with isUnread + url tdc channel threads --ids-only # Output only thread IDs; pagination notice goes to stderr tdc channel members # List a channel's members + groups fully in the channel tdc channel members --json # JSON with id, name, workspaceId, members tdc channel members --ids-only # Output only member user IDs tdc channel members add alice group:Design # Add users and/or expand group: members tdc channel members add a@d.com id:789 --json # Add refs, output result as JSON tdc channel members remove alice group:Frontend # Remove users and/or group members tdc channel members set group:Squad --apply # Replace membership with the resolved set tdc channel members set alice bob # Dry-run by default; refuses to remove you (--include-self to override) tdc groups # List workspace groups tdc groups --search "frontend" # Filter groups by name (case-insensitive) tdc groups --json # JSON output tdc groups --ids-only # Output only group IDs tdc groups --json --full # Include all fields in JSON output tdc groups view # Show group with member details tdc groups view --json # JSON output with id, name, workspaceId, members tdc groups view --json --full # Include all fields in JSON output tdc groups create "Name" # Create a new group tdc groups create "Name" --users alice@doist.com,bob@doist.com # Create with members tdc groups create "Name" --json # Output created group as JSON tdc groups rename "New name" # Rename a group tdc groups rename "Name" --json # Output renamed group as JSON tdc groups delete --yes # Delete a group (requires --yes) tdc groups delete --dry-run # Preview deletion tdc groups add-user user1 user2 # Add users to a group tdc groups add-user a@d.com,b@d.com # Comma-separated refs tdc groups add-user id:123 --json # Output result as JSON tdc groups remove-user user1 user2 # Remove users from a group tdc groups remove-user id:123,id:456 # Comma-separated ID refs ``` All group *writes* (`groups create`, `rename`, `delete`, `add-user`, `remove-user`) need the `workspaces:write` scope, which only `tdc auth login --full-access` grants. Group *reads* (`groups`, `groups view`) work on a default login. If a channel is not found in `tdc channels`, widen with broader listings such as `tdc channels --scope public`, then `tdc channels --scope public --state all`. Check `tdc channels --help` for other available filters. `tdc channel threads` returns every thread in the channel; pagination filters (`--limit`, `--cursor`, `--since`, `--until`, `--unread`) are applied client-side after fetch. `--archive-filter` is applied server-side. Results are sorted newest-first by last activity. In `--json` / `--ndjson`, the response includes a `nextCursor` string (opaque) you can pass via `--cursor` to fetch the next page; NDJSON emits the cursor as a final `{ "_meta": true, "nextCursor": "..." }` line. For `tdc channel members add/remove/set`, refs accept user identifiers (`id:N`, email, name) or `group:`, which expands to the group's current members. Group expansion is one-shot — it is not a persistent link, so users added to the group later will not auto-join the channel. `set` replaces membership with the resolved set and is dry-run by default (pass `--apply` to mutate); it refuses to remove the acting user unless `--include-self` is passed. ## Reactions ```bash tdc react thread 👍 # Add reaction to thread tdc react comment +1 # Add reaction (shortcode) tdc react message heart # Add reaction to DM message tdc react thread 👍 --json # Output result as JSON tdc unreact thread 👍 # Remove reaction tdc unreact thread 👍 --json # Output result as JSON ``` Supported shortcodes: +1, -1, heart, tada, smile, laughing, thinking, fire, check, x, eyes, pray, clap, rocket, wave ## Shell Completions ```bash tdc completion install # Install tab completions (prompts for shell) tdc completion install bash # Install for specific shell tdc completion install zsh tdc completion install fish tdc completion uninstall # Remove completions ``` ### Diagnostics ```bash tdc doctor # Run local + network diagnostics tdc doctor --offline # Skip Comms and npm network checks tdc doctor --json # JSON output with per-check results ``` ### Configuration ```bash tdc config view # Pretty-printed config, token masked, labels actual token source tdc config view --json # Raw JSON, token masked tdc config view --show-token # Include the full token tdc config set unarchive-new-threads true # Persist: always unarchive new threads so they land in your Inbox tdc config set unarchive-new-threads false # Persist: keep Comms's default (thread auto-archived for author) ``` User preferences are stored under `userSettings` in the config file. Currently supported keys: `unarchive-new-threads`. The flag on `tdc thread create` (`--unarchive` / `--no-unarchive`) overrides this default per-invocation. ### Update ```bash tdc update # Update CLI to latest version tdc update --check # Check for updates without installing, show channel tdc update --check --json # Same, JSON envelope tdc update --check --ndjson # Same, newline-delimited JSON envelope tdc update --channel # Show current update channel tdc update switch --stable # Switch to stable release channel tdc update switch --pre-release # Switch to pre-release (next) channel tdc update switch --pre-release --json # Same, JSON envelope tdc update switch --pre-release --ndjson # Same, newline-delimited JSON envelope ``` ### Changelog ```bash tdc changelog # Show last 5 versions tdc changelog -n 3 # Show last 3 versions tdc changelog --count 10 # Show last 10 versions ``` ## Migration Translate old `twist.com` URLs to their Comms equivalents (e.g. for rewriting bookmarks or history). The migration endpoint authenticates with a **Twist** token (not a Comms one). Prefer the `TWIST_AUTH_TOKEN` environment variable — a CLI flag exposes the token in process listings. `--twist-token` is supported for ad-hoc use and overrides the env var. If the Twist CLI (`tw`) is installed, populate the env var inline with `TWIST_AUTH_TOKEN="$(tw auth token view)"`. ```bash # Comma-separated list as an argument (token from the environment) TWIST_AUTH_TOKEN="$(tw auth token view)" tdc migrate urls "https://twist.com/a/1/ch/2/t/3,https://twist.com/a/1/ch/2/t/4" # Or pipe URLs via stdin (comma- or newline-separated) cat old-urls.txt | TWIST_AUTH_TOKEN="$(tw auth token view)" tdc migrate urls # --twist-token overrides the env var (visible in process lists — prefer the env var) tdc migrate urls "https://twist.com/a/1/ch/2/t/3" --twist-token tdc migrate urls "" --json # Structured output ({ oldUrl, newUrl } / { oldUrl, error }) tdc migrate urls "" --ndjson # Newline-delimited JSON ``` Output is one line per URL in input order: `old -> new` on success, `old ✗ ` on failure (`invalid_url` / `not_imported`, or `API_ERROR` when the endpoint gives no code). Per-URL failures don't abort the run; the command exits non-zero if any URL fails to migrate. ## Global Options ```bash --no-spinner # Disable loading animations --progress-jsonl # Machine-readable progress events (JSONL to stderr) --progress-jsonl= # Same, but write events to instead of stderr --progress-jsonl # Same as above (space-separated form also accepted) --accessible # Add text labels to color-coded output (also: TDC_ACCESSIBLE=1) --non-interactive # Disable interactive prompts (auto-detected when stdin is not a TTY) --interactive # Force interactive mode even when stdin is not a TTY ``` ## Output Formats List and view commands commonly support `--json`, `--ndjson`, and `--full`. List commands with one clear entity ID also support `--ids-only`; check command help for the exact surface. ```bash --json # Output as JSON --ndjson # Output as newline-delimited JSON (for streaming) --ids-only # Output one stable ID per line; mutually exclusive with JSON/NDJSON --full # Include all fields (default shows essential fields only) ``` ## Dry Run Mutating commands accept `--dry-run` to preview the operation without making the change. Where a command performs pre-flight validation (e.g. fetching the target thread to check channel access or ownership), those checks still run in dry-run — only the mutating write is skipped. Commands that have no pre-flight validation parse the reference and print the preview without hitting the API. The preview is structured: ``` [dry-run] Would : : ... Run without --dry-run to execute. ``` ## Reference System Commands accept flexible references: - **IDs**: `id:` (or a bare ID when unambiguous). Workspace/user IDs are numeric; most Comms entity IDs are opaque strings. - **Comms URLs**: Full `https://comms.todoist.com/...` URLs (parsed automatically) - **Fuzzy names**: For workspaces/users/channels/groups - `"My Workspace"` or partial matches ## Piping Input Commands that accept content (`thread create`, `thread reply`, `comment update`, `conversation reply`, `msg update`) auto-detect piped stdin: ```bash cat notes.md | tdc thread reply tdc thread create "Title" < body.md echo "Quick reply" | tdc conversation reply ``` If no content argument is provided and no stdin is piped, the CLI opens `$EDITOR` for interactive input. In non-TTY environments (e.g. when called by an agent or in a pipeline), the editor is automatically skipped and the command fails fast with an actionable error message. Use `--non-interactive` to force this behavior even in a TTY, or `--interactive` to override auto-detection. `tdc thread mark-read` also accepts thread refs from stdin, one per line: ```bash printf "id:CbT8n2Kp4Qx6Rz9Lm3Va\nid:CbT9m4Qr7Vz2Nx8Lp5Sa\n" | tdc thread mark-read --yes ``` ## Common Workflows **View by URL (auto-routes to the right command):** ```bash tdc view https://comms.todoist.com/1585/ch/CbC8n2Kp4Qx6Rz9Lm3Va/t/CbT8n2Kp4Qx6Rz9Lm3Va # View thread tdc view https://comms.todoist.com/a/1585/ch/CbC8n2Kp4Qx6Rz9Lm3Va/t/CbT8n2Kp4Qx6Rz9Lm3Va # View thread tdc view https://comms.todoist.com/a/1585/ch/CbC8n2Kp4Qx6Rz9Lm3Va/t/CbT8n2Kp4Qx6Rz9Lm3Va/c/CbM8n2Kp4Qx6Rz9Lm3Va # View comment tdc view https://comms.todoist.com/a/1585/msg/CbV8n2Kp4Qx6Rz9Lm3Va # View conversation tdc view https://comms.todoist.com/a/1585/msg/CbV8n2Kp4Qx6Rz9Lm3Va/m/CbS8n2Kp4Qx6Rz9Lm3Va --json # View message as JSON ``` **Check inbox and respond:** ```bash tdc inbox --unread --json tdc thread view --unread tdc thread reply "Thanks, I'll look into this." tdc thread done --yes ``` **Search and review:** ```bash tdc mentions --since 2026-04-01 --all --json tdc search "deployment" --type threads --json tdc thread view ``` **Check DMs:** ```bash tdc conversation unread --json tdc conversation list --kind group --json # find a group DM by participants/name tdc conversation view tdc conversation with "Alice Example" tdc conversation reply "Got it, thanks!" ```