{"id":48683111,"url":"https://github.com/mingnz/teams-cli","last_synced_at":"2026-05-29T03:04:42.543Z","repository":{"id":350559914,"uuid":"1206983264","full_name":"mingnz/teams-cli","owner":"mingnz","description":"💬 CLI for Microsoft Teams — list chats, read and send messages, search, and more.","archived":false,"fork":false,"pushed_at":"2026-04-11T03:02:16.000Z","size":248,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T09:03:45.621Z","etag":null,"topics":["cli","httpx","microsoft-teams","python","teams","typer"],"latest_commit_sha":null,"homepage":"https://github.com/mingnz/teams-cli#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mingnz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T13:02:13.000Z","updated_at":"2026-04-11T03:17:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"b4412fea-974e-472a-ab82-8e2dcccb1787","html_url":"https://github.com/mingnz/teams-cli","commit_stats":null,"previous_names":["mingnz/teams-cli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mingnz/teams-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mingnz%2Fteams-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mingnz%2Fteams-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mingnz%2Fteams-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mingnz%2Fteams-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mingnz","download_url":"https://codeload.github.com/mingnz/teams-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mingnz%2Fteams-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33634615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","httpx","microsoft-teams","python","teams","typer"],"created_at":"2026-04-11T03:16:13.693Z","updated_at":"2026-05-29T03:04:42.537Z","avatar_url":"https://github.com/mingnz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# teams-cli\n\n[![npm](https://img.shields.io/npm/v/teams-cli.svg)](https://www.npmjs.com/package/teams-cli)\n[![Node.js 18+](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Formatted with Biome](https://img.shields.io/badge/Formatted_with-Biome-60a5fa?style=flat\u0026logo=biome)](https://biomejs.dev/)\n[![Linted with Biome](https://img.shields.io/badge/Linted_with-Biome-60a5fa?style=flat\u0026logo=biome)](https://biomejs.dev/)\n[![CodeQL](https://github.com/mingnz/teams-cli/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/mingnz/teams-cli/actions/workflows/github-code-scanning/codeql)\n[![Dependabot](https://img.shields.io/badge/dependabot-enabled-brightgreen.svg?logo=dependabot)](https://github.com/mingnz/teams-cli/security)\n\nA command-line interface for Microsoft Teams. List chats, read and send messages, search, view activity, and more — all from your terminal.\n\nUses 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.\n\n### AI agent integration\n\nThis 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.\n\nAn [agent skill](skills/teams-cli/SKILL.md) 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:\n\n```sh\n# Install the skill\nnpx skills add https://github.com/mingnz/teams-cli\n\n# Or copy skills/teams-cli/ into your project's .claude/skills/ directory\n```\n\n## Install\n\nRequires [Node.js](https://nodejs.org/) 18+.\n\n```sh\n# Install globally from npm\nnpm install -g teams-cli\n\n# Or run directly with npx\nnpx teams-cli --help\n\n# Or clone and build from source\ngit clone https://github.com/mingnz/teams-cli.git\ncd teams-cli\nnpm install\nnpm run build\n```\n\n## Authentication\n\nLog in by launching a browser session. Sign in as you normally would (including MFA), and tokens are captured automatically from the browser:\n\n```sh\nteams login\n```\n\nTokens 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.\n\n## Usage\n\n```sh\n# List recent chats\nteams chats\n\n# Read messages (use short ID from `teams chats`)\nteams messages a1b2\n\n# Send a message\nteams send a1b2 \"Hello from the CLI\"\n\n# Find a person by name or email\nteams find \"Jane Smith\"\n\n# Send a direct message (creates 1:1 chat if needed)\nteams dm \"Jane Smith\" \"Hey, quick question\"\nteams dm \"8:orgid:00000000-0000-...\" \"Hello via MRI\"\n\n# Search across all conversations\nteams search \"quarterly report\"\n\n# Watch a chat for new messages (Ctrl+C to stop)\nteams watch a1b2\n\n# Watch all chats for new messages\nteams watch\n\n# View activity feed\nteams activity\nteams activity --feed mentions\nteams activity --feed calllogs\n\n# List members of a chat\nteams members a1b2\n\n# List meeting recordings shared in a chat\nteams recordings a1b2\n\n# Download a recording's transcript (defaults to the first recording, WebVTT)\nteams transcript a1b2\nteams transcript a1b2 1 --format grouped       # 2nd recording, speaker-grouped text\nteams transcript a1b2 --format json -o out.json\nteams transcript a1b2 --output -                # print to stdout\n```\n\n\u003e **Transcripts** are fetched from SharePoint/Stream (where Teams stores meeting\n\u003e recordings). The first `transcript` download for a given SharePoint host briefly\n\u003e opens a headless browser (using your saved login) to obtain a SharePoint token,\n\u003e then caches it for reuse. Limitations:\n\u003e - Only recordings in **your own (home) tenant** can be downloaded — meetings you\n\u003e   joined as an external guest are hosted in another org's SharePoint and can't\n\u003e   get a token (\"Could not obtain a SharePoint token for …\").\n\u003e - Very old recordings whose share links were cleaned up return \"sharing link\n\u003e   could not be found\".\n\n### Options\n\nMost commands accept `--limit` / `-n` to control how many results to fetch:\n\n```sh\nteams chats --limit 50\nteams messages a1b2 --limit 40\nteams search \"budget\" --limit 10\n```\n\nRun `teams --help` or `teams \u003ccommand\u003e --help` for full details.\n\n## Development\n\n```sh\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run tests\nnpm test\n\n# Run in dev mode (no build step)\nnpm run dev -- chats\n```\n\n## How it works\n\n1. `teams login` opens Chromium via Playwright, navigates to Teams, and waits for you to complete sign-in\n2. Auth tokens are extracted from the browser's `localStorage` (three tokens: chat, search, presence) along with your region\n3. 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`\n4. The `teams chats` command caches the conversation list locally so you can reference chats by short ID in subsequent commands\n5. 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\n\n## Project structure\n\n```\nsrc/              # CLI source — auth, API calls, formatting, commands\ntests/            # Unit tests for all modules\nskills/           # Agent skill for AI-assisted Teams interaction\ndocs/             # Architecture and security documentation\n```\n\n## Disclaimer\n\nThis 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmingnz%2Fteams-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmingnz%2Fteams-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmingnz%2Fteams-cli/lists"}