teams-cli

module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT

README

teams

teams is a command-line client for Microsoft Teams and Outlook calendar. It reads everything you can see in Teams — your teams and channels, threads, chats, search results, mentions, unread messages, people, files — and it writes: post, reply, edit, delete, react, attach files, create chats, change members and move your read state. It also reads your calendar, or a colleague's, and creates, moves, answers, cancels and deletes meetings.

It is one static binary with no runtime to install. Reading and writing both work from a script, a cron job or an AI agent, and the same binary can sign in as a company service account instead of as you.

$ teams channel read Engineering/General --limit 2
Bob Builder · 2 hours ago · #General
  Morning all, the deploy notes are attached.
  attachment: deploy-notes.md

Alice Example · 2 hours ago · #General · edited · high importance
  Subject: Deploy
  Hello @Yuki Tanaka, can you review the deploy?
  reactions: 👍 2

$ teams post Engineering/General 'shipping v0.4 now :rocket:' --mention @yuki
posted 1750000000003
  https://teams.microsoft.com/l/message/19:general@thread.tacv2/1750000000003?…

Install

With mise, the recommended way (mise-en-place):

mise use -g github:floriscornel/teams-cli

mise takes the archive for your platform out of the release, checks it against the digest GitHub reports, verifies the build-provenance attestation, unpacks it and puts teams on your PATH — no archive and no checksum step to do by hand. -g records the tool for every shell; without it, the tool lands in the current project's mise.toml instead.

Name a version to pin one, which is also how to install a release published in the last day: mise withholds those from @latest on purpose (minimum_release_age, 24 h by default):

mise use -g github:floriscornel/teams-cli@1.1.0

Or download a release (macOS, Linux and Windows; amd64 and arm64):

gh release download --repo floriscornel/teams-cli --pattern 'teams_*_darwin_arm64.tar.gz'
tar xzf teams_*_darwin_arm64.tar.gz teams   # the archive also carries the man pages
install teams ~/.local/bin/teams

Or build it yourself (needs Go 1.27+):

go install github.com/floriscornel/teams-cli/cmd/teams@latest

Every archive carries the man pages (man teams) and shell completions for bash, zsh, fish and PowerShell (completions/); a mise install keeps all of it in the directory mise where github:floriscornel/teams-cli prints. Without an archive, teams completion bash prints the same script, and teams version --check says whether a newer release exists.

Every release ships checksums.txt, signed with cosign keyless and covered by a GitHub build-provenance attestation — mise verifies it for you, and a hand download can be checked the same way:

gh attestation verify --owner floriscornel teams_*_darwin_arm64.tar.gz \
  --repository floriscornel/teams-cli \
  --signer-workflow floriscornel/teams-cli/.github/workflows/release.yml

Sign in

teams auth login                 # opens your browser (authorization code + PKCE)
teams auth login --device        # a device code, for SSH and headless machines
teams auth status                # who you are, what the token can do, where it is stored
teams doctor                     # check the config, token store, scopes and Graph reachability

Sign-in works with the Microsoft Graph CLI Tools app by default. Companies often block it, so the recommended setup is your own Entra app registration — see Register your own Entra app for the five-minute walkthrough (redirect URI, public client flows, the permission set per preset and the admin consent). teams auth status --admin-request prints the exact text to paste into a ticket.

The token cache is encrypted and stays local; see Where your data lives.

Reading

Command What it shows
teams team list · teams team show <team> Your teams, and one team's details
teams channel list <team> · teams channel show <channel> A team's channels, and one channel
teams channel read <channel> [--limit --replies --since --until --all] A channel's messages, threads included with --replies
teams thread read <message> One message and its replies
teams chat list [--with <person> --topic <q> --unread --all] Your chats, newest activity first
teams chat show <chat> · teams chat read <chat> [--from --since --until --limit] One chat, and its messages
teams search <query> [--from --to --in --mentions-me --has-attachment --since --until --limit --page] KQL search over messages
teams mentions [--since 24h] Messages that mention you
teams unread [--chats --mentions] [--since] What is waiting for you
teams user search <q> · teams user show <person> People in your directory
teams channel files <channel> · teams file download <message> [-o dir] A channel's files, and a message's attachments
teams calendar list [--user <who> --date <day> --days N --from/--to --tz --free-busy --chat --include-cancelled] Meetings for a day or a range, yours or a colleague's
teams calendar show <event> · teams calendar search <query> One event in full, and a search over your primary calendar
teams alias set|list|rm Names you can use anywhere a reference is

teams search takes the documented KQL scope terms both as flags and inline in the query, so teams search 'from:bob deploy sent>=2026-10-01' works. Hits carry no message body — Graph does not return one — so pipe the webUrl into teams thread read when you want the text.

teams calendar list                                # today
teams calendar list --date tomorrow --tz Asia/Tokyo
teams calendar list --from mon --to fri            # weekdays read naturally
teams calendar list --user bob@example.com          # full details if shared
teams calendar list --user bob@example.com --free-busy
teams calendar list --chat                         # resolve each meeting's chat
teams calendar show a1b2c3d                        # a handle from the listing
teams calendar search standup

Days are local: a day runs midnight to midnight in --tz, or in this machine's zone without it. All-day events are floating, so they are matched by date and never shifted by a timezone conversion. The ID column is a 7-character handle for Graph's 152-character event id; show accepts the handle, the full id, or an Outlook web link. A colleague's calendar is shown in full when it is shared with you; otherwise the command falls back to free/busy (times and status only) and says so on stderr.

Writing

Command What it does
teams post <channel|chat> [text|-] A new message
teams reply <message> [text|-] A thread reply in a channel; a quote reply in a chat
teams edit <message> [text|-] [--subject --importance] Change a message you sent
teams delete <message> Soft-delete it, as Teams does (the conversation keeps a tombstone)
teams react <message> <emoji> [--remove] Add or remove your reaction
teams chat create --with <person> [--with …] [--topic <title>] A one-on-one or group chat
teams chat add-member <chat> <person…> · teams chat delete <chat> Membership, and deleting a chat
teams chat mark-read|mark-unread <chat> Move your own read watermark
teams api <method> <path> Any Graph call the CLI does not wrap
# markdown is the default; --text sends it verbatim and --html sends HTML
teams post Engineering/General '**deploy done** — notes attached' --subject Deploy

# a file goes to the channel's SharePoint folder; an image is embedded inline
teams post Engineering/General 'the chart:' --file chart.png --file notes.md

# stdin, so another command can write the message
git log --oneline -5 | teams post Engineering/General -

# see exactly what would be sent, then send it
teams post Engineering/General 'hi' --dry-run
teams reply Engineering/General/m-1002 'on it' --dry-run

Anything that writes supports --dry-run, which prints the Graph request it would send instead of sending it — including the uploads a message with --file would perform.

Writing to your calendar

teams calendar create --subject Standup --start 09:00 --duration 15m --attendee bob@example.com
teams calendar create --subject Offsite --all-day --date 2026-10-12 --days 2
teams calendar create --subject "Design review" --start 14:00 --teams
teams calendar accept a1b2c3d --comment "see you there"
teams calendar tentative a1b2c3d --propose "2026-10-07 15:00/2026-10-07 15:30"
teams calendar update a1b2c3d --subject "Moved review" --start 15:00 --duration 45m
teams calendar cancel a1b2c3d --comment "rescheduling"
teams calendar delete a1b2c3d --yes

These commands notify people. Creating with --attendee sends the invitations immediately, so on a terminal the command asks first and anywhere else it needs --yes. Accepting, tentatively accepting and declining tell the organizer; cancelling a meeting — or deleting one you organize — sends your attendees a cancellation. --dry-run prints the request instead of sending it (and still runs the read-only checks), and --no-notify answers without telling the organizer.

The CLI refuses what Graph would reject, before sending anything:

  • responding to a meeting you organize (you are the organizer…);
  • cancelling one you do not organize (use teams calendar decline);
  • updating one you do not organize, unless --local-copy — otherwise you change only your copy and the organizer's next update overwrites it;
  • --propose together with --no-notify (a proposed time has to reach the organizer), or on an event whose organizer does not accept proposals;
  • create --teams on a mailbox that cannot make Teams meetings.

update sends only the fields you name, so moving a meeting cannot drop its body or its Teams link. --body rewrites the body and can lose the Teams meeting details, which is why it is never sent unless you ask for it.

Mentions, files and images

--mention marks someone as a real Teams mention, so they get notified. The text must name them the way you want it shown; the CLI resolves the person and matches @alice, @"Alice Example" or the address you typed:

teams post Engineering/General 'thanks @alice, please review' --mention alice@example.com
teams post Engineering/General 'cc @"Yuki Tanaka"' --mention yuki@example.com

--file attaches a file and references it in the message. An image that fits the 4 MB inline limit is embedded in the message body; anything else is uploaded (the channel's SharePoint folder, or your own OneDrive for a chat, with a sharing link so recipients can open it).

Every <team>, <channel>, <chat>, <message> and <person> argument accepts any of these:

teams channel read Engineering/General                    # Team/Channel
teams thread read Engineering/General/1750000000001         # a message in that channel
teams thread read 'https://teams.microsoft.com/l/message/19:general@thread.tacv2/1750000000001?groupId=…'
teams chat read @yuki                                      # your 1:1 chat with a person
teams chat read yuki@example.com                           # the same person, by address
teams chat read 'Release train'                            # a chat topic
teams chat read 19:bob@thread.v2                           # a raw id
teams chat read @boss                                      # an alias you defined

Names are matched case-insensitively and remembered per profile in a small cache (an hour for names, a week for people), so the second command is instant. --refresh resolves them again. When a name is ambiguous on a terminal, the CLI asks which one you meant; in a script it prints the candidates and exits 2.

teams alias set boss alice@example.com
teams alias set standup Engineering/Daily
teams alias list

Output and scripting

On a terminal you get tables and rendered markdown. When the output is piped you get plain text, and --json gives a stable schema designed for scripts; --jq <expr> filters it (and implies --json).

teams chat list --unread --json | jq -r '.[].topic'
teams search deploy --json --jq '.hits[0].webUrl'
teams channel read Engineering/General --json --jq '.[0].body.content'
teams unread --json --jq '{chats: (.chats | length), mentions: (.mentions | length)}'
teams calendar list --date tomorrow --json --jq '.[] | "\(.start) \(.subject)"'

Exit codes are the same everywhere, so a script can tell failures apart:

Code Meaning
0 success
1 error
2 usage — a bad flag, an ambiguous name, a missing confirmation
3 authentication required — no session, an expired token, a missing scope
4 not found
5 throttled by Graph (the CLI retries first)

Non-interactive runs never prompt. With --no-input, in CI, or when stdin is not a terminal, anything that needs an answer fails fast with a hint instead — which is why destructive commands take --yes.

Read-only mode refuses every write before any network call:

teams --read-only channel read Engineering/General   # fine
teams --read-only post Engineering/General hi        # exit 2, "read-only"
TEAMS_READ_ONLY=1 teams react <message> 👍           # the same, from the environment

Inbox and reminders

teams unread                       # unread chats and unread mentions, last 24h
teams unread --since 7d            # a wider window
teams unread --all                 # every unread chat, however old
teams mentions --since 2h          # just the mentions
teams chat mark-read 'Release train'

teams unread never marks anything read; only teams chat mark-read does.

Configuration

The config file is at ~/.config/teams/config.toml on Linux, ~/Library/Application Support/teams/config.toml on macOS and %AppData%\teams\config.toml on Windows; TEAMS_CONFIG overrides the path. Profiles let you keep a personal identity and a service account side by side:

default_profile = "me"

[profiles.me]
tenant = "contoso.com"        # or "common"
client_id = ""                # empty → the Microsoft Graph CLI Tools public client
mode = "full"                 # full | read-only (read-only refuses write commands)
cloud = "global"              # global | usgov | china
token_store = "auto"          # auto | file | file:///path/to/cache
scopes = "full"               # chats | read-only | full, or an explicit list

[profiles.bot]
tenant = "contoso.com"
client_id = "00000000-0000-0000-0000-000000000000"
scopes = "full"
teams profile list
teams config set profiles.bot.client_id 00000000-0000-0000-0000-000000000000
teams --profile bot chat list        # or TEAMS_PROFILE=bot, or default_profile

Environment overrides: TEAMS_PROFILE, TEAMS_READ_ONLY, TEAMS_CONFIG, TEAMS_CACHE_DIR, TEAMS_STATE_DIR, TEAMS_ACCESS_TOKEN (a short-lived Graph token used as-is, for CI) and TEAMS_NO_KEYCHAIN (use the plaintext token file, for containers).

Service accounts

A service account signs in the same way — once, with --device:

teams auth login --profile bot --device     # signed in as the bot user
teams --profile bot post Engineering/Deploys 'nightly build finished'

The token cache lives in the same place as your own, so the account is reusable on that machine. Storing it in Azure Key Vault, so an unattended runner can read it, is on the roadmap (see Status).

The scopes setting is a preset for the app registration, and it decides what the CLI can ask for:

Preset Includes
chats Your chats: Chat.Read, Chat.ReadWrite, ChatMessage.Send, files in your OneDrive
read-only Reading, plus ChannelMessage.Read.All and Files.Read.All for channel content
full Everything: channel and chat writes, and channel file uploads (Files.ReadWrite.All)

ChannelMessage.Read.All, ChannelMessage.ReadWrite and TeamMember.Read.All need admin consent, so reading a channel usually needs an admin even though writing a chat does not. A command whose scope the token does not carry fails immediately, names the scope, and exits 3 — it does not call Graph first. teams doctor shows which commands the current token unlocks, and teams auth status --admin-request prints the consent request.

teams chat delete needs Chat.ManageDeletion.All, which is in no preset because an admin has to consent to it. On a terminal the CLI offers to sign in again with that scope; anywhere else it exits 3 with the admin request.

The calendar commands work the same way, because a calendar scope in a preset would make every existing login ask for it (which triggers AADSTS65001):

Command Scope
teams calendar list (your own), show, search Calendars.Read
teams calendar list --user <colleague> Calendars.Read.Shared
teams calendar list --chat, show (chat lookup) OnlineMeetings.Read

None of them needs admin consent by the docs, but a production tenant may still block user consent, in which case the error's hint says so and teams auth status --admin-request prints the ticket. Listing a colleague by address needs nothing beyond the calendar scopes; naming them by display name additionally resolves through the directory, which needs User.ReadBasic.All or People.Read.

Where your data lives

Kind Where Removed by
Config os.UserConfigDir()/teams/config.toml teams config
Secrets your OS keychain + token.bin in the state dir teams auth logout — never teams cache clear
Cache (rebuildable) os.UserCacheDir()/teams/<profile>/ teams cache clear
State ~/.local/state/teams/<profile>/ on Linux, beside the config elsewhere teams cache clear --all

Files are 0600 and directories 0700. The token cache is encrypted with AES-256-GCM, and only the 32-byte data key sits in your keychain — created the first time tokens are stored, so a fresh teams auth status never touches it.

teams cache info            # every path, size and entry count, no network calls
teams cache clear           # the rebuildable cache
teams cache clear --all -y  # everything except the config and your tokens

Teams API escape hatch

Anything the CLI does not wrap is still reachable, with the same authentication:

teams api GET /me
teams api GET /teams/$TEAM_ID/channels --jq '.value[].displayName'
teams api POST /chats/19:bob@thread.v2/markChatReadForUser -f user.id=user-1
teams api POST /search/query --input query.json

-f key=value adds a string field (dotted keys nest, so -f body.content=hi works), -F key=value keeps JSON types, --input <file> sends a whole body, --query and --header add parameters and headers, and --dry-run prints the request. Read-only mode still applies: a raw GET or HEAD is allowed, anything else is refused.

Troubleshooting

Symptom What to do
exit 3, "not signed in" teams auth login, or --device on a headless machine
exit 3, "needs ChannelMessage.Read.All" The token lacks the scope: teams doctor shows the gap, teams auth status --admin-request prints the ticket for an admin
Graph answers 403 for a call Usually consent, occasionally a tenant policy on the app registration; the error names the scope Graph wanted
AADSTS50011 on sign-in The app registration has no http://localhost redirect URI; teams auth login --device works meanwhile
AADSTS50020 / AADSTS65001 The tenant or client ID is wrong / the user or an admin has not consented: check tenant and client_id in the profile
A command finds no chat for @person There is no existing 1:1 chat; any write (teams post @person hi) creates it, or use teams chat create --with <person>
A name matches several objects Run it on a terminal and pick one, or use the raw id from teams user search
Calls hang or time out -v logs every request, page and retry; a stalled call reports a timeout rather than hanging
Nothing works behind a proxy Set HTTPS_PROXY; the CLI uses the standard Go proxy variables

Security and privacy

  • Credentials never touch the command line. There is no flag that takes a secret; the token cache is encrypted at rest, and no command prints a token.
  • The token cache is the only secret on disk. teams cache clear can never delete it — teams auth logout is the command that forgets you.
  • TEAMS_ACCESS_TOKEN is a decode-only escape hatch. It is checked for audience and expiry to catch mistakes, not verified as a signature, and it skips the scope pre-check.
  • teams api sends whatever you ask. It is the escape hatch, so it can write anything the token allows. --dry-run shows the request first.
  • AI features are opt-in and not built yet. When they land, nothing is sent to a model provider until you run teams ai setup and consent, and Teams content is only sent to the provider you configure.

Status

v1.1.0 is the current release. It adds the calendar, read and write: teams calendar list, show and search, and create, update, accept, tentative, decline, cancel and delete. v1.0.x covers everything else here. The binary is what this README describes, and this documentation is also published at https://floriscornel.github.io/teams-cli/ (generated from the repository).

In order from here:

  1. AI features — summarize, ask, draft, catchup with an Anthropic, OpenAI-compatible or Azure/Foundry provider, conversation history and curated memory. Opt-in, off by default.
  2. Service accounts — the Key Vault token store, auth export/auth refresh and a CI guide, for unattended runners.

Not in either release yet, and asked for often enough to say so: forward a meeting, delta sync, rooms and resources as first-class targets, and editing a whole recurring series (every calendar action applies to the single instance you list).

PLAN.md is the full design and the reasoning behind each decision.

Contributing

Bug reports and pull requests are welcome at floriscornel/teams-cli. The short version for a checkout:

mise trust && mise install
mise run check        # fmt, tidy, lint, tests with coverage, contract checks
mise run test         # go test -race -shuffle=on ./...
mise run docs         # regenerate docs/commands, the man pages and completions
mise run docs-site    # render the documentation site into dist/docs-site

AGENTS.md explains the layout and the rules (in particular: read the reference mirror under refs/ before changing any Graph call, OAuth flow, Teams URL or KQL query), docs/ci.md covers CI and releases, and SECURITY.md says how to report a vulnerability privately.

License

See LICENSE (added with the first release).

Directories

Path Synopsis
cmd
teams command
Command teams is the CLI entry point.
Command teams is the CLI entry point.
internal
auth
Package auth wraps MSAL Go: profiles, the interactive and device-code flows, silent acquisition, the token stores and the friendly errors PLAN.md requires.
Package auth wraps MSAL Go: profiles, the interactive and device-code flows, silent acquisition, the token stores and the friendly errors PLAN.md requires.
auth/tokenstore
Package tokenstore holds the MSAL cache backends.
Package tokenstore holds the MSAL cache backends.
cli
Package cli wires the cobra command tree and the process exit codes.
Package cli wires the cobra command tree and the process exit codes.
clock
Package clock injects time into the CLI so that relative output, `--since` windows, token-expiry checks and retention pruning are deterministic in tests (PLAN.md, Layer 1: "an injected clock keeps relative times and --since deterministic").
Package clock injects time into the CLI so that relative output, `--since` windows, token-expiry checks and retention pruning are deterministic in tests (PLAN.md, Layer 1: "an injected clock keeps relative times and --since deterministic").
cloud
Package cloud holds the per-cloud endpoint bases PLAN.md's `cloud` setting selects (global, usgov, china).
Package cloud holds the per-cloud endpoint bases PLAN.md's `cloud` setting selects (global, usgov, china).
config
Package config loads and validates the TOML config file described in PLAN.md ("Profiles"): a default profile, one section per profile, and the environment overrides that let tests, CI and containers relocate everything.
Package config loads and validates the TOML config file described in PLAN.md ("Profiles"): a default profile, one section per profile, and the environment overrides that let tests, CI and containers relocate everything.
format
Package format converts Microsoft Teams message bodies into the markdown the CLI renders.
Package format converts Microsoft Teams message bodies into the markdown the CLI renders.
graph
Package graph is the thin, hand-written Microsoft Graph client PLAN.md chooses over msgraph-sdk-go.
Package graph is the thin, hand-written Microsoft Graph client PLAN.md chooses over msgraph-sdk-go.
output
Package output centralizes everything the CLI writes to a terminal and the process exit codes it uses.
Package output centralizes everything the CLI writes to a terminal and the process exit codes it uses.
ref
Package ref turns the flexible references the CLI accepts into concrete Microsoft Graph ids: Teams deep links, "Team/Channel/Message" name paths, "@person", e-mail addresses, aliases and raw ids.
Package ref turns the flexible references the CLI accepts into concrete Microsoft Graph ids: Teams deep links, "Team/Channel/Message" name paths, "@person", e-mail addresses, aliases and raw ids.
store
Package store owns the CLI's on-disk layout and the primitives every other package uses to touch it: directory resolution, atomic 0600/0700 writes and a per-profile lock file.
Package store owns the CLI's on-disk layout and the primitives every other package uses to touch it: directory resolution, atomic 0600/0700 writes and a per-profile lock file.
testing/contract
Package contract implements the Layer 6 contract tests: it vendors a trimmed copy of Microsoft's Graph v1.0 OpenAPI description and validates the requests and responses that teams-mcp's Go port actually sends.
Package contract implements the Layer 6 contract tests: it vendors a trimmed copy of Microsoft's Graph v1.0 OpenAPI description and validates the requests and responses that teams-mcp's Go port actually sends.
testing/contract/cmd/gencontract command
Command gencontract regenerates the committed Layer 6 contract artifacts (the trimmed OpenAPI description, the route list and the provenance record) from a local, gitignored refs/ mirror.
Command gencontract regenerates the committed Layer 6 contract artifacts (the trimmed OpenAPI description, the route list and the provenance record) from a local, gitignored refs/ mirror.
testing/coveragecheck command
Command coveragecheck enforces the repo's coverage floor over the paths that count.
Command coveragecheck enforces the repo's coverage floor over the paths that count.
testing/docgen command
Command docgen regenerates docs/commands (per-command markdown), docs/man (man pages) and docs/completion (shell completion scripts) from the cobra command tree, so the documentation cannot drift from the CLI.
Command docgen regenerates docs/commands (per-command markdown), docs/man (man pages) and docs/completion (shell completion scripts) from the cobra command tree, so the documentation cannot drift from the CLI.
testing/docsite command
Command docsite renders the user documentation into a static site.
Command docsite renders the user documentation into a static site.
testing/fakegraph
Package fakegraph is a stateful, in-memory Microsoft Graph server for the teams CLI test suite.
Package fakegraph is a stateful, in-memory Microsoft Graph server for the teams CLI test suite.
testing/fakeidp
Package fakeidp is an in-process fake Microsoft identity platform (Microsoft Entra ID) that MSAL Go can talk to: a TLS httptest server that serves the OIDC metadata document, the device-code endpoint, the token endpoint (device code, auth code + PKCE and refresh grants) and the JWKS document, plus helpers that drive the interactive auth-code flow headlessly.
Package fakeidp is an in-process fake Microsoft identity platform (Microsoft Entra ID) that MSAL Go can talk to: a TLS httptest server that serves the OIDC metadata document, the device-code endpoint, the token endpoint (device code, auth code + PKCE and refresh grants) and the JWKS document, plus helpers that drive the interactive auth-code flow headlessly.
update
Package update checks GitHub Releases for a newer `teams` and reports it.
Package update checks GitHub Releases for a newer `teams` and reports it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL