teams-cli

A command-line interface for Microsoft Teams. List chats, read and send messages, search, view activity, and more — all from your terminal.

Uses the internal Teams Chat Service API (the same API the Teams web client uses), authenticated via a Playwright-based browser login flow. No Entra ID app registration or tenant-level admin setup required — just sign in with your browser.

AI agent integration

This CLI can be used as a tool for AI agents (e.g. Claude Code, Codex, GitHub Copilot) to access Microsoft Teams on your behalf — without needing a direct Microsoft integration. Most Teams integrations require Entra ID app registrations and tenant admin approval. This doesn't.

An agent skill is included that teaches coding agents how to use the CLI — install it and your agent can read your messages, send DMs, search chats, and more:

# Install the skill
npx skills add https://github.com/mingnz/teams-cli

# Or copy skills/teams-cli/ into your project's .claude/skills/ directory

Install

Requires Node.js 18+.

# Install globally from npm
npm install -g teams-cli

# Or run directly with npx
npx teams-cli --help

# Or clone and build from source
git clone https://github.com/mingnz/teams-cli.git
cd teams-cli
npm install
npm run build

Authentication

Log in by launching a browser session. Sign in as you normally would (including MFA), and tokens are captured automatically from the browser:

teams login

Tokens are stored in ~/.teams-cli/tokens.json. Token lifetimes vary by API (the chat token lasts ~24 hours, the search token ~1.5 hours). Expired tokens are refreshed automatically via a headless browser using your saved session cookies — no manual re-login needed unless the session itself has expired.

Usage

# List recent chats
teams chats

# Read messages (use short ID from `teams chats`)
teams messages a1b2

# Send a message
teams send a1b2 "Hello from the CLI"

# Find a person by name or email
teams find "Jane Smith"

# Send a direct message (creates 1:1 chat if needed)
teams dm "Jane Smith" "Hey, quick question"
teams dm "8:orgid:00000000-0000-..." "Hello via MRI"

# Search across all conversations
teams search "quarterly report"

# Watch a chat for new messages (Ctrl+C to stop)
teams watch a1b2

# Watch all chats for new messages
teams watch

# View activity feed
teams activity
teams activity --feed mentions
teams activity --feed calllogs

# List members of a chat
teams members a1b2

# List meeting recordings shared in a chat
teams recordings a1b2

# Download a recording's transcript (defaults to the first recording, WebVTT)
teams transcript a1b2
teams transcript a1b2 1 --format grouped       # 2nd recording, speaker-grouped text
teams transcript a1b2 --format json -o out.json
teams transcript a1b2 --output -                # print to stdout

Transcripts are fetched from SharePoint/Stream (where Teams stores meeting recordings). The first transcript download for a given SharePoint host briefly opens a headless browser (using your saved login) to obtain a SharePoint token, then caches it for reuse. Limitations:

• Only recordings in your own (home) tenant can be downloaded — meetings you joined as an external guest are hosted in another org's SharePoint and can't get a token ("Could not obtain a SharePoint token for …").
• Very old recordings whose share links were cleaned up return "sharing link could not be found".

Options

Most commands accept --limit / -n to control how many results to fetch:

teams chats --limit 50
teams messages a1b2 --limit 40
teams search "budget" --limit 10

Run teams --help or teams <command> --help for full details.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in dev mode (no build step)
npm run dev -- chats

How it works

1. teams login opens Chromium via Playwright, navigates to Teams, and waits for you to complete sign-in
2. Auth tokens are extracted from the browser's localStorage (three tokens: chat, search, presence) along with your region
3. CLI commands use these tokens to call the Teams Chat Service API (teams.cloud.microsoft/api/chatsvc/) and the Substrate Search API (substrate.office.com) directly via fetch
4. The teams chats command caches the conversation list locally so you can reference chats by short ID in subsequent commands
5. The teams dm command searches for a user via the Substrate Suggestions API, creates a 1:1 thread via POST /threads, and sends the message — all in one step

Project structure

src/              # CLI source — auth, API calls, formatting, commands
tests/            # Unit tests for all modules
skills/           # Agent skill for AI-assisted Teams interaction
docs/             # Architecture and security documentation

Disclaimer

This project is not affiliated with, endorsed by, or associated with Microsoft. It uses undocumented internal APIs that Microsoft can change or restrict at any time without notice. Use at your own risk — this tool may break unexpectedly.