teams-cli 0.1.13__tar.gz → 0.2.1__tar.gz

{teams_cli-0.1.13 → teams_cli-0.2.1}/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1](https://github.com/rvben/teams-cli/compare/v0.2.0...v0.2.1) - 2026-10-15
+
+### Added
+
+- **desktop**: add `teams desktop clear-flags` and a confirmed TUI cleanup that remove remote-debugging flags from the user-wide WebView2 setting while keeping its other arguments.
+- Search people by name or email and create or reuse a one-to-one conversation with `people search` and `chats create --recipient ID --yes`. Opening a conversation never sends a message.
+- Support these operations through the selected personal or work/school desktop account and through Microsoft Graph. Graph search requires a new sign-in to consent to `User.ReadBasic.All`.
+
+### Changed
+
+- Windows desktop helpers use protocol 4. WSL requires the helper from the same CLI release.
+- Ambiguous conversation-creation outcomes remain unconfirmed and are never automatically retried.
+- Personal-account searches put verified live matches first and filter unrelated recent-contact suggestions before applying the result limit.
+
+### Fixed
+
+- **desktop**: pass the debugging flags only to the Teams launch on Windows and WSL, so other WebView2 apps such as Outlook no longer open the debugging port.
+- **desktop**: name the application that holds a refused port and report a user-wide debugging setting as the cause.
+- **desktop**: recognise the dedicated browser on Linux and WSL when Chrome rewrites its process title, so setup no longer stops with "did not open its debugging endpoint"; recovery hints now name the browser mode and port in use.
+- **desktop**: keep the work/school browser visible when the organisation's sign-in (such as AD FS with Windows sign-in) does not let Teams stay signed in headless, instead of reporting success and then losing the session; reads now say when Teams was sent back to sign-in, and setup reports whether the browser runs headless or visible.
+- **desktop**: stop a verified dedicated browser that hangs after closing its debugging port, so disconnect and recover no longer leave it running.
+- **desktop**: refuse sign-in success when the browser closes or loses verified ownership during the sign-in check, and verify reads again after observing work-account sign-in.
+- **desktop**: separate email lookup from name search ([b0647f1](https://github.com/rvben/teams-cli/commit/b0647f177c3f4cb5f73e74f42aed11078832e632))
+
+## [0.2.0](https://github.com/rvben/teams-cli/compare/v0.1.13...v0.2.0) - 2026-10-14
+
+### Added
+
+- **desktop**: add one-command lightweight browser setup with automatic matching browser downloads, visible sign-in followed by verified hidden operation, personal-account defaults, and safe reconnect/recovery.
+- **desktop**: add managed browser clients and cached avatars ([319c494](https://github.com/rvben/teams-cli/commit/319c494b18c9dff98d26b2d069d4347a39d02e6b))
+
+### Fixed
+
+- **security**: update rustls to 0.23.46 to address the newly published TLS advisories.
+
 ## [0.1.13](https://github.com/rvben/teams-cli/compare/v0.1.12...v0.1.13) - 2026-10-14
 
 ### Fixed

{teams_cli-0.1.13 → teams_cli-0.2.1}/Cargo.lock

@@ -1776,7 +1776,7 @@ version = "1.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c0aeb26bf5e836cc1c341c8106051b573f1766dfa05aa87f0b98be5e51b02303"
 dependencies = [
- "nix",
+ "nix 0.29.0",
  "winapi",
 ]
 
@@ -1848,6 +1848,18 @@ dependencies = [
  "memoffset",
 ]
 
+[[package]]
+name = "nix"
+version = "0.31.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d"
+dependencies = [
+ "bitflags 2.13.1",
+ "cfg-if",
+ "cfg_aliases",
+ "libc",
+]
+
 [[package]]
 name = "nom"
 version = "7.1.3"
@@ -2740,9 +2752,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.45"
+version = "0.23.46"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
+checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
 dependencies = [
  "aws-lc-rs",
  "once_cell",
@@ -3175,7 +3187,7 @@ dependencies = [
 
 [[package]]
 name = "teams-cli"
-version = "0.1.13"
+version = "0.2.1"
 dependencies = [
  "assert_cmd",
  "base64 0.23.1",
@@ -3188,6 +3200,7 @@ dependencies = [
  "jiff",
  "jsonschema",
  "keyring",
+ "libc",
  "open",
  "predicates",
  "rand 0.9.5",
@@ -3206,6 +3219,7 @@ dependencies = [
  "url",
  "windows-sys 0.61.2",
  "wiremock",
+ "zip",
 ]
 
 [[package]]
@@ -3215,7 +3229,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.3",
+ "getrandom 0.3.4",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",
@@ -3279,7 +3293,7 @@ dependencies = [
  "libc",
  "log",
  "memmem",
- "nix",
+ "nix 0.29.0",
  "num-derive",
  "num-traits",
  "ordered-float",
@@ -3577,6 +3591,12 @@ dependencies = [
  "thiserror 2.0.20",
 ]
 
+[[package]]
+name = "typed-path"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
+
 [[package]]
 name = "typenum"
 version = "1.20.1"
@@ -4263,6 +4283,20 @@ dependencies = [
  "syn 3.0.4",
 ]
 
+[[package]]
+name = "zip"
+version = "9.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2d98561b612a84ae525331a7a094429ef8a5772514ed507ff6db5f54badc971"
+dependencies = [
+ "crc32fast",
+ "flate2",
+ "indexmap",
+ "memchr",
+ "nix 0.31.3",
+ "typed-path",
+]
+
 [[package]]
 name = "zmij"
 version = "1.0.23"

{teams_cli-0.1.13 → teams_cli-0.2.1}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "teams-cli"
-version = "0.1.13"
+version = "0.2.1"
 edition = "2024"
 rust-version = "1.90"
 description = "A Microsoft Teams CLI and TUI designed equally for humans and agents"
@@ -46,6 +46,7 @@ toml = "1.1"
 url = "2"
 jiff = "0.2"
 unicode-width = "0.2"
+zip = { version = "9.0.3", default-features = false, features = ["deflate-flate2"] }
 
 [target.'cfg(windows)'.dependencies]
 windows-sys = { version = "0.61", features = [
@@ -55,9 +56,13 @@ windows-sys = { version = "0.61", features = [
     "Win32_Security",
     "Win32_Storage_Packaging_Appx",
     "Win32_System_Diagnostics_ToolHelp",
+    "Win32_System_Registry",
     "Win32_System_Threading",
 ] }
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
 [dev-dependencies]
 assert_cmd = "2"
 jsonschema = "0.49.8"

{teams_cli-0.1.13 → teams_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teams-cli
-Version: 0.1.13
+Version: 0.2.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 License-File: LICENSE
@@ -18,7 +18,7 @@ Project-URL: Repository, https://github.com/rvben/teams-cli
 
 Microsoft Teams from your terminal—human-first and agent-first.
 
-`teams-cli` is a Rust CLI and TUI for everyday Microsoft Teams work through supported Microsoft Graph APIs, with an optional experimental desktop backend that reads chats from, and can send chat messages through, a running Teams client on macOS, Windows or WSL. It is designed as two equally first-class experiences over one typed core: a fast, calm terminal interface for people and a deterministic, introspectable command contract for agents. The default Graph backend signs in as you with delegated OAuth and protects refresh credentials in your operating system's credential store. Output is readable text on a TTY and structured JSON when piped.
+`teams-cli` is a Rust CLI and TUI for everyday Microsoft Teams work through supported Microsoft Graph APIs, with an optional experimental desktop backend that reads chats from, and can send chat messages through, a running Teams client on macOS, Windows or WSL. A dedicated browser client also provides an experimental route on native Linux; see [browser setup](#dedicated-browser-client-experimental). It is designed as two equally first-class experiences over one typed core: a fast, calm terminal interface for people and a deterministic, introspectable command contract for agents. The default Graph backend signs in as you with delegated OAuth and protects refresh credentials in your operating system's credential store. Output is readable text on a TTY and structured JSON when piped.
 
 For humans, no arguments open guided onboarding on first use and the TUI afterward. For agents, no command ever waits for an undeclared prompt: `teams schema` works offline, collection sizes are caller-bounded, writes declare their effects, errors have stable kinds and exit codes, and stdout contains data only.
 
@@ -68,11 +68,21 @@ teams init
 teams init
 ```
 
+For a personal Microsoft account with the lightweight hidden browser:
+
+```console
+teams init --profile personal --backend desktop --desktop-client browser-core
+```
+
+This downloads its browsers automatically, opens visible sign-in once, and then
+runs hidden. See [lightweight browser setup](#low-memory-browser-client-experimental)
+for sending, reconnecting, and experimental compatibility limits.
+
 Browser PKCE is the human-friendly default. The browser talks directly to Microsoft, and the CLI never receives or stores your password. Normal sign-in requests these delegated scopes:
 
 ```text
-openid profile offline_access User.Read Team.ReadBasic.All
-Channel.ReadBasic.All Chat.Read Chat.Create ChatMessage.Send
+openid profile offline_access User.Read User.ReadBasic.All
+Team.ReadBasic.All Channel.ReadBasic.All Chat.Read Chat.Create ChatMessage.Send
 ChannelMessage.Send
 ```
 
@@ -153,6 +163,8 @@ For short-lived automation, `TEAMS_ACCESS_TOKEN` overrides the stored credential
 teams list
 teams channels list TEAM_ID
 teams chats list --limit 25
+teams people search "Alex" --limit 20
+teams chats create --recipient PERSON_ID --yes  # no message is sent
 teams messages list --chat CHAT_ID
 teams auth login --channel-history  # once, with administrator approval
 teams messages list --team TEAM_ID --channel CHANNEL_ID
@@ -168,7 +180,21 @@ teams config path
 teams doctor --offline
 ```
 
-Collection commands expose `--limit` and `--fields`; Graph-native collections use `--cursor`, while joined teams and channels use `--offset` because those endpoints do not accept `$top`. With a terminal they render concise text; when stdout is piped they emit JSON envelopes with continuation metadata and `truncated`.
+Chat, message, team and channel collections expose `--limit` and `--fields`; Graph-native collections use `--cursor`, while joined teams and channels use `--offset` because those endpoints do not accept `$top`. With a terminal they render concise text; when stdout is piped they emit JSON envelopes with continuation metadata and `truncated`.
+
+To message someone for the first time, use `people search` to find their verified
+identity in the active profile. Search accepts a name or email prefix of 2–256
+characters and returns at most 50 people; refine the query if `truncated` is true.
+Pass the exact returned ID to `chats create`, then pass the resulting chat ID to
+`messages send`. Creating a conversation reuses an existing one-to-one chat when
+available and sends no message. It requires a writable profile and confirmation
+(`--yes` for automation). Recipient IDs belong to their selected account/backend.
+If creation is unconfirmed, inspect your chats before trying again.
+
+Graph recipient search needs delegated `User.ReadBasic.All` consent. Existing
+sign-ins can keep reading chats; run `teams auth login` again to enable directory
+search. Your organization may restrict consent, directory guest access, external
+recipients or chat creation. Personal accounts use the desktop backend.
 
 Profiles can block every remote write while keeping reads, sign-in, diagnostics, and the TUI available:
 
@@ -223,6 +249,15 @@ ids returned by `chats list`; personal chats are accessed through the desktop ba
 The chat with yourself is listed too, with the id `48:notes`, so
 you can try sending there first.
 
+Desktop chat results may also include optional `avatarData` raster data URIs on
+members and one-to-one chats. Photos come only from image resources already loaded
+by that account's Teams page; the CLI never fetches a photo URL. Missing, stale,
+ambiguous, or unsupported photos leave the fields absent, so clients should show
+initials as a fallback. Reads allow at most 16 photos, 256 KiB per photo, 1 MiB of
+avatar data in total, and a one-second budget. A photo failure never fails a chat
+read. Personal photo reads have been checked on macOS; work/school and other
+platforms still need photo-specific runtime validation.
+
 Desktop profiles are read-only unless created with `init --allow-send`;
 `TEAMS_READ_ONLY=true` still blocks sending, but `TEAMS_READ_ONLY=false` cannot unlock a
 desktop profile. With the opt-in, `messages send --chat` sends one plain-text message
@@ -254,7 +289,9 @@ paste; `r` checks delivery, `s` offers an explicit second-copy confirmation, and
 `esc` keeps the draft and uncertainty together in memory. Reopening it does not
 unlock ordinary sending. Queued results are labelled queued rather than sent.
 
-Desktop cannot create new chats. Teams, channels, identity commands, subscriptions,
+Desktop supports people search and one-to-one chat creation through the selected
+Teams client's own session. Creation requires a profile with `--allow-send` and
+sends no message. Teams, channels, identity commands, subscriptions,
 replies, mentions, attachments and edits return `unsupported` on desktop. The TUI
 reads chats from the same cache and sends through the same path as `messages send`.
 Existing profiles without a backend field
@@ -276,15 +313,22 @@ Added auxiliary processes are left alone. If Teams was
 restarted independently, quit and relaunch it normally, then disconnect again to
 clear the old record. No command automatically restarts Teams on exit.
 
-On macOS, flags apply only to the managed launch. On Windows/WSL, setup saves the
-previous user environment value, applies flags temporarily while Teams starts, then
-restores that value. Unrelated changes to the value are preserved and reported.
+Debugging flags apply only to the managed Teams launch; other apps and the user
+environment are left unchanged. On Windows/WSL, Teams starts through its
+`ms-teams.exe` app execution alias, which must be enabled (Settings > Apps >
+Advanced app settings > App execution aliases). Connect refuses a user-wide
+`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` that already has debugging flags: such a
+setting opens the port in every WebView2 app, for example Outlook, and the
+listener is then refused because Teams does not own it. Errors name those apps.
+`teams desktop clear-flags` removes only the debugging flags from that setting
+after confirmation (`--yes` when scripted); quit and reopen the named apps
+afterwards. The TUI offers the same cleanup.
 Windows and WSL share a recovery record and lock. WSL finds PowerShell in its normal
 Windows system directory even when Windows PATH entries are disabled; Windows
 executable interop must still be enabled.
 
-If setup is interrupted, run `teams --profile local desktop recover`. It restores
-pending settings without restarting Teams or requiring the Windows helper; it does
+If setup is interrupted, run `teams --profile local desktop recover`. It clears the
+interrupted record (and restores settings left by older versions) without restarting Teams or requiring the Windows helper; it does
 not claim ownership of an unrecorded Teams process. Use `desktop status` to inspect
 the endpoint and saved session. Recovery cannot close an already-running debugging
 endpoint: quit Teams and relaunch it normally if its ownership was not recorded.
@@ -360,12 +404,134 @@ This backend is experimental: chat reading depends on the Teams client's interna
 cache layout and sending on its internal send interface, and an unrecognised layout
 fails with `desktop_error` rather than guessing.
 
+### Dedicated browser client (experimental)
+
+On native Linux, macOS, or WSL2, the desktop backend can use an installed Chrome,
+Chromium, or Edge browser instead of the native Teams app. WSL2 uses a Linux browser;
+visible sign-in requires WSLg or another graphical display. The existing Windows
+helper route remains the default for native desktop profiles.
+
+Create a separate read-only profile and sign in in the window that opens:
+
+```console
+teams init --profile browser --backend desktop --desktop-client browser --desktop-account work-school --yes
+# The window closes automatically after a successful chat read.
+# Teams then runs headless with the same saved sign-in:
+teams --profile browser
+# To renew sign-in or complete MFA later:
+teams --profile browser desktop login --yes
+```
+
+Login waits up to five minutes for a readable chat cache, then restarts headless
+and verifies another read before reporting success. An empty chat list is valid.
+A sign-in timeout leaves the visible window open; finish signing in and retry
+`desktop login`. Interrupting login preserves the browser and its saved profile.
+On WSL2, the visible step needs WSLg or another graphical display.
+
+Some organisations sign in through their own identity provider (for example AD FS
+with Windows sign-in) and do not let Teams renew its sign-in in a headless browser.
+For work/school accounts, login therefore watches the headless browser for up to a
+minute; when Teams is sent back to sign-in, the visible browser is reopened and stays
+open instead. Minimise that window, but keep it open. When a headless session is sent
+back to sign-in later, reads report it; run `desktop login` again.
+
+Use `--desktop-account personal` for a personal Microsoft account. Sending still
+requires an explicit `init --allow-send` and the existing send confirmation.
+`init --no-login` only saves configuration. `desktop connect --visible` remains
+available for manually managed sign-in; `desktop connect` starts headless.
+
+The browser uses its own profile under the local data directory at
+`teams-cli/browser/<port>/profile`; it never copies or opens your normal browser
+profile. Different ports use different browser profiles. Disconnect closes this
+browser and keeps its sign-in data. To switch between visible and headless operation,
+disconnect first. `desktop recover` closes a verified managed browser or clears a
+stale record when no listener remains. A verified browser that does not exit after
+closing its debugging port is stopped; unverifiable processes are left untouched.
+
+The CLI checks that every listener is loopback-only and belongs to the recorded
+browser process, running as you with the expected executable, debugging port and
+dedicated profile. Only HTTPS Teams pages are used for reads or sends. While the
+port is open, other programs running as you can access that browser session.
+
+Browser discovery supports common system installations. For another installation,
+set `TEAMS_DESKTOP_BROWSER` to the absolute path of the actual browser executable,
+not a shell launcher. Snap/Flatpak installations are not automatically supported.
+The optional `TEAMS_DESKTOP_BROWSER_DATA_DIR` sets an absolute browser data directory
+(each port gets a separate subdirectory). Keep the same browser executable and data
+directory settings while managing a session. Headless mode removes the visible window; Teams still consumes browser CPU and RAM.
+
+This route is experimental. Browser lifecycle and ownership checks can be tested
+without signing in, but live Teams Web reads, sends, session persistence and MFA
+recovery still require validation on a signed-in machine. Existing native Teams
+validation does not establish browser-client compatibility.
+
+### Low-memory browser client (experimental)
+
+`--desktop-client browser-core` keeps the authenticated Teams data runtime without
+starting the main UI. It supports personal accounts only and requires the
+exact Teams Personal bootstrap build validated by this CLI. Unknown builds fail
+with `desktop_error`; the CLI does not fall back to old cache data or the full UI.
+Use `--desktop-client browser` on a separate port for the full web client.
+
+Start with one command:
+
+```console
+teams init --profile core --backend desktop --desktop-client browser-core
+```
+
+The CLI downloads a matching **Chrome for Testing / chrome-headless-shell** pair
+from Google's official Stable channel on first setup, opens a separate sign-in
+window, and hides it once chats are readable. It verifies the hidden session before
+saving your CLI profile. Core mode defaults to a personal account, port **9223**,
+and read-only access; add `--allow-send` to enable sending. Your normal browser,
+its profile, and the native Teams connection on port 9222 are left alone.
+
+Browser binaries and sign-in state live in a private `teams-cli/browser` data
+directory. The installed pair is reused offline and is not silently updated while
+sessions are running. Setup needs roughly 1 GiB of disk space for the browsers and
+extraction; the ZIP downloads are removed after installation. Linux/WSL2 need a
+desktop display (WSLg on WSL2) for initial sign-in.
+
+```console
+teams --profile core desktop login       # Sign in again; automatically hide afterward
+teams --profile core desktop disconnect  # Stop the browser; retain sign-in
+teams --profile core desktop connect     # Start hidden using the saved session
+teams --profile core desktop status      # Inspect process and recovery state
+```
+
+An interrupted sign-in retains the dedicated window and profile. Rerun `desktop
+login` to finish; an expired hidden session can use the same command. A stale
+process record is recovered automatically only when its port has no listener;
+unrelated or changed processes are refused. `desktop recover` preserves sign-in
+and can close only a verified managed browser. The status command does not prove
+that you are signed in; `chats list` or `doctor` verifies message access.
+
+Advanced setups can override both `TEAMS_DESKTOP_BROWSER` and
+`TEAMS_DESKTOP_HEADLESS_BROWSER` with absolute paths to matching executables.
+Set both or neither; a partial override is refused. `TEAMS_DESKTOP_BROWSER_DATA_DIR`
+changes the private data location. Keep these settings stable while a session is
+running. Unknown Teams builds are refused; use the full `browser` client on its
+own port if your Teams build is not yet supported.
+
+On macOS, both dedicated test browsers use mock-keychain encryption because the
+headless shell uses it. This profile contains sensitive login state and remains in
+a private directory; it never opens your ordinary browser profile.
+
+The integrated CLI measured about **307 MiB after collection and 322 MiB idle**
+of summed browser process physical footprint on macOS with a personal account.
+Signed-in reads, visible-to-headless login, sending/readback and incoming updates
+from a second verified client passed. This is approximate process accounting, not a guaranteed RAM cap or a
+Linux measurement. Startup peaks, large accounts, overnight use, reconnect/MFA and
+Linux/WSL2 signed-in operation still need validation. Size-oriented V8 settings may
+trade CPU for memory. Avatar fields may be absent because UI photos are not loaded.
+Sending still requires `init --allow-send` and the existing send confirmation.
+
 ## Graph boundaries
 
 - The Graph backend supports Microsoft 365 work or school accounts only. Use the experimental desktop backend on macOS, Windows or WSL for personal Microsoft accounts; the relevant Teams Graph endpoints do not support them.
 - A work account can authenticate successfully before Microsoft Teams is licensed or provisioned; `teams doctor` distinguishes identity access from Teams availability.
 - Calling and screen sharing are not available as a delegated user CLI; Graph calling is built around bot/application scenarios.
-- No extracted desktop tokens, browser interception, or direct calls to private Teams services; the experimental desktop backend reads the local client cache and sends only through the Teams window's own client.
+- No extracted desktop tokens or direct calls to private Teams services; the experimental desktop backend reads the local client cache and sends only through the Teams window's own client.
 - Tenant policy and admin consent can restrict delegated capabilities.
 
 ## CLI Spec