A command-line client that gives people and compatible coding agents access to Microsoft Teams through a persistent local browser session.
Warning
This project relies on undocumented Microsoft Teams behavior and a Microsoft first-party client identity. It is unsupported, may be blocked by tenant policy, and may stop working without notice. Obtain organizational approval before using it, and never run live write tests against a production tenant.
You need Node.js 22.20 or newer, Microsoft Edge or Google Chrome, and a Microsoft 365 account with Teams access. Node.js 24 LTS is recommended. See the installation guide for operating-system-specific setup and troubleshooting.
npm install --global @michaelschnyder/teams-cli
teams-cli --versionFor an agent-first setup, install the packaged skill before signing in:
teams-cli skills installFor filesystem-based agents such as Codex, Claude Code, Cursor, GitHub Copilot, OpenCode, Windsurf, Gemini CLI, Pi, and generic .agents/skills environments, the command installs the skill directly. You can then ask the agent, for example, Send a test message to myself via Teams; it can guide or perform login when needed.
When Claude Desktop is detected, the command also creates a versioned Cowork ZIP in Downloads. Cowork requires you to upload that ZIP in Customize > Skills > Create skill > Upload a skill and enable it. This account-level step cannot be completed or verified by the CLI. See Claude Cowork and other agent setup.
For direct console use, skip the skill and continue to login.
teams-cli loginteams-cli login is the convenient alias for teams-cli auth login. It opens a dedicated Microsoft Edge profile by default, or a dedicated Google Chrome profile when selected. It does not reuse your normal browser profile or its signed-in session. The CLI discovers the Teams tenant and user, then saves them in the implicit default profile. Most users never need to provide a tenant ID or create a named profile.
On a first interactive login, the CLI offers to install the skill first when it detects an agent environment and no identity or managed skill. Declining continues login. Automated and non-interactive login never shows this prompt.
Policies are optional but recommended for agent-assisted work. From the workspace the agent will operate in, run:
teams-cli policy edit --openChoose which people, group chats, and channels may be read or posted to, then save and activate the policy. Policies are cooperative CLI-level safeguards: they help prevent accidental access and posts through teams-cli, but they are not an operating-system sandbox or a server-side Teams permission.
See workspace policies for the editor, audit mode, activation, manual editing and deactivation, overlapping policies, and the security boundary.
Ask a compatible agent naturally after installing the skill, for example:
Find my chat with Alice and summarize the latest five messages.
Draft a reply to the Project Phoenix channel, but show it to me before sending.
Or use the CLI directly:
teams-cli auth whoami
teams-cli person search "Alice" --json
teams-cli chat search "Alice" --json
teams-cli channel list --json
teams-cli message list --chat CHAT_ID --json
teams-cli message send --person alice@example.com --body "Hello"For an existing group chat or channel, use --chat CHAT_ID or --channel CHANNEL_ID. You can optionally preview a known target with teams-cli policy check send; the send command always enforces the applicable policy again immediately before posting. Sending is externally visible and the CLI has no delete or undo command.
flowchart LR
install[Install teams-cli] --> route{How will you use it?}
route -->|Agent| skill[Install the agent skill]
route -->|Console| login[Sign in once]
skill --> login
login --> policy[Recommended: add a workspace policy]
policy --> use[Ask an agent or run commands]
teams-cli login discovers and records the verified tenant, user, and browser in the default profile. The longer teams-cli auth login form remains available. Named profiles and explicit --tenant or --user flags are optional tools for people who deliberately maintain more than one identity. Profiles select configuration; they are not permission boundaries. See authentication and optional profiles.
The skill gives an agent the operational knowledge that command help alone cannot provide: discover current IDs before using them, verify the active identity, keep JSON payloads separate from diagnostics, optionally preview policy decisions, and stop on denials. Installed copies can be refreshed when the CLI is upgraded.
Policies are YAML files matched against the canonical working-directory path. Inactive policies audit and warn; active policies constrain identities, message reads, posts, and raw-token export. All matching active policies must allow an operation, so overlapping policies can only preserve or narrow access.
These safeguards apply to operations made through this CLI. A sufficiently privileged local process can change policy files, and a bearer token used by another HTTP client is outside the CLI's checks. Read-only file permissions add protection against accidental edits but do not make a policy immutable.
Person, chat, channel, and message commands support --json. JSON payloads stay on stdout, while progress, warnings, update notices, and sanitized diagnostics stay on stderr. Scripts and agents can therefore consume stdout without mixing it with status text.
| Command | Purpose | Examples and details |
|---|---|---|
login |
Sign in using the default session; alias for auth login |
Authentication |
version |
Inspect build provenance, install updates, or switch stable/canary channels | Installation and upgrades |
skills |
List, locate, install, and refresh the packaged agent skill | Agent skill installation |
doctor |
Diagnose the local runtime, browser, session, and managed skills without changing them | Installation and upgrades |
auth |
Login, refresh, inspect, export tokens, or logout | Authentication |
profile |
Manage optional named identity selectors | Profiles |
policy |
Create, inspect, check, activate, and edit safeguards | Policies |
person |
Search people, inspect profiles, and retrieve images | Command examples |
chat |
Search, explicitly enumerate, and inspect chats | Command examples |
channel |
List and inspect teams and channels | Command examples |
message |
List, get, and send messages | Command examples |
Run teams-cli --help or teams-cli <command> --help for the complete options supported by the installed version.
Configuration, authentication, dedicated browser state, policies, update state, and managed skill-installation records live under ~/.teams-cli/. Secret-bearing files and directories use owner-only permissions on supported operating systems.
Raw bearer tokens can be exported by authentication commands when applicable policies allow it. Treat them like passwords: never paste them into prompts, logs, issues, or source files. See the security model for the complete trust boundary.
See CONTRIBUTING.md for development setup, testing, and contribution guidance.