teams-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{teams_cli-0.2.0 → teams_cli-0.2.2}/.github/workflows/ci.yml

@@ -24,6 +24,16 @@ jobs:
           components: rustfmt, clippy
       - uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
       - run: cargo test --locked --all-targets
+      - name: Verify pass and GPG credential encryption
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y --no-install-recommends pass
+          bash tests/pass_credentials.sh
+      - name: Verify WSL credential encryption
+        if: runner.os == 'Windows'
+        shell: powershell
+        run: ./tests/wsl_credentials.test.ps1
 
   quality:
     name: Formatting and lints

{teams_cli-0.2.0 → teams_cli-0.2.2}/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2](https://github.com/rvben/teams-cli/compare/v0.2.1...v0.2.2) - 2026-10-15
+
+### Added
+
+- Guided `teams init` asks for Work/school or Personal, chooses a separate browser port, offers explicit send permission, and opens the inbox after verified sign-in.
+- Browser setup can opt in to reopening its saved session with `teams`; existing profiles, native Teams and scripted reads keep their connection behaviour. Explicit setup supports `--auto-start`.
+- Offer initialized `pass` stores during new Graph setup on Linux, WSL and macOS, with explicit `--credential-store pass` and `--pass-store-dir` options. Save the backend and absolute directory per profile, verify GPG encryption/decryption before sign-in, and preserve encrypted credentials on failed updates.
+
+### Fixed
+
+- Report credential-helper failures distinctly from missing sign-ins; bound helper operations and preserve the chosen backend across sign-in, refresh and logout.
+- Store WSL Graph credentials with Windows DPAPI through PowerShell, so callback and device-code sign-in, token refresh, and logout do not require D-Bus or Secret Service.
+
+### Changed
+
+- Guided setup offers separate accounts or explicit connection updates, preserves Graph registration and channel-history access, resumes interrupted browser sign-in on the original port, and verifies fresh Graph credentials before saving them with rollback on config failure.
+- Cold work-browser inbox startup checks sign-in renewal in the background; failures pause sending and offer sign-in while preserving drafts. First-run `teams tui` uses guided setup, including headless Graph recovery and environment-override checks.
+- Guided setup checks local browser/display support, Teams installation and Windows interop, and matching lightweight browser downloads before allowing a connection choice. Unavailable options explain their requirements; supported alternatives are selected automatically.
+- Guided Graph setup verifies chat access before saving connection settings. Desktop/browser sending opt-in now requires a send-interface probe; guided setup offers an explicit read-only alternative if it fails, without sending a test message.
+- Reject personal-only lightweight browser/work-school combinations before saving even with `--no-login`.
+
+## [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

{teams_cli-0.2.0 → teams_cli-0.2.2}/Cargo.lock

@@ -3187,7 +3187,7 @@ dependencies = [
 
 [[package]]
 name = "teams-cli"
-version = "0.2.0"
+version = "0.2.2"
 dependencies = [
  "assert_cmd",
  "base64 0.23.1",

{teams_cli-0.2.0 → teams_cli-0.2.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "teams-cli"
-version = "0.2.0"
+version = "0.2.2"
 edition = "2024"
 rust-version = "1.90"
 description = "A Microsoft Teams CLI and TUI designed equally for humans and agents"
@@ -56,10 +56,11 @@ windows-sys = { version = "0.61", features = [
     "Win32_Security",
     "Win32_Storage_Packaging_Appx",
     "Win32_System_Diagnostics_ToolHelp",
+    "Win32_System_Registry",
     "Win32_System_Threading",
 ] }
 
-[target.'cfg(target_os = "macos")'.dependencies]
+[target.'cfg(unix)'.dependencies]
 libc = "0.2"
 
 [dev-dependencies]

{teams_cli-0.2.0 → teams_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: teams-cli
-Version: 0.2.0
+Version: 0.2.2
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 License-File: LICENSE
@@ -62,27 +62,80 @@ Run `teams` in a terminal on first use, or start explicitly:
 teams init
 ```
 
-`teams-cli` includes a maintained multitenant Microsoft Entra public-client registration, so normal setup does not require creating an app or copying a client ID:
+Choose **Work or school** or **Personal**, choose whether to enable sending, and
+follow sign-in. Setup checks this machine first and gives unavailable connections
+no selectable number, with an explanation of what they need. It chooses a separate
+browser port and opens your inbox once chats are readable. After that, just run:
 
 ```console
-teams init
+teams
 ```
 
-For a personal Microsoft account with the lightweight hidden browser:
+On macOS, Linux and WSL2, work/school setup prefers a dedicated browser; personal
+setup prefers the lightweight browser. Missing display support, missing executables,
+invalid browser overrides and unavailable matching downloads are checked before
+selection. Personal can use a full browser or Teams Desktop when lightweight mode
+is unavailable. Work/school can use Teams Desktop or Microsoft Graph when needed.
+When no lightweight runtime is installed, these checks query public Chrome for
+Testing version metadata at `googlechromelabs.github.io`; no browser download or
+Teams sign-in happens before consent.
+On a Linux terminal without a display, Graph uses device-code sign-in on another device.
+You explicitly approve reopening a dedicated browser
+when you start the inbox. The saved sign-in is reused, and expired work/school
+sign-in offers to reopen the sign-in window. Some organisations require keeping
+the browser visible; minimise it instead of closing it. WSL2 needs WSLg for sign-in.
+On native Windows, browser options are unavailable; use Teams Desktop or run inside
+WSL2 for browser mode.
+
+Guided setup saves connection settings only after a successful chat read, including
+Graph profiles. If sending was requested, desktop/browser setup also probes the
+send interface without sending a message. If that fails, you can explicitly continue
+read-only; setup never silently downgrades your choice. A successful probe establishes
+that the interface is available, while delivery and organisation policies are checked
+when you actually send. Teams build compatibility and sign-in still need live validation.
+
+Running setup again asks whether to connect another account or update an existing
+connection. Updates preserve Graph application/tenant settings and previously granted
+channel-history access. Failed Graph verification preserves the previous credential;
+if saving settings fails, the credential change is rolled back. Browser setup can resume
+an unfinished sign-in on the same port, or start a separate account without touching it.
+Recovery errors include the exact command to close that browser.
+You can forget an unfinished setup after confirmation; its browser data and saved
+sign-in remain on disk, and the old browser's close command is shown. Reusing that
+forgotten browser data requires explicit setup with its original `--desktop-port`.
+Setup offers unfinished connections under other names when you connect another account.
+
+Cold work-browser startup opens the inbox once chats are readable and checks sign-in
+renewal in the background. A sign-out pauses sending and offers sign-in in the inbox.
+Other startup-check failures keep chats readable and pause sending until you reopen
+the inbox to check again. Drafts stay in memory through the sign-in detour.
+Guided Graph setup disables conflicting token or permission environment overrides;
+explicit flags keep their automation behavior.
+
+**Other connection options** keeps Microsoft Graph and the running Teams Desktop
+available. Microsoft Graph includes a maintained Entra public-client registration,
+so normal API setup needs no app registration or copied client ID.
+
+Scripts and explicit connection flags keep their existing behaviour. For example:
 
 ```console
-teams init --profile personal --backend desktop --desktop-client browser-core
+teams init --backend graph
+# Or configure an automatically reopened work browser explicitly:
+teams init --profile work --backend desktop --desktop-client browser \
+  --desktop-account work-school --desktop-port 9224 --auto-start
 ```
 
-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 profiles default to read-only; add `--allow-send` to enable sending.
+Existing profiles retain their connection behaviour unless you opt in with setup
+or `--auto-start`. CLI reads, JSON output, demo mode and snapshots never start a
+browser automatically. See [lightweight browser setup](#low-memory-browser-client-experimental)
+for personal-account 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:
+For Microsoft Graph profiles, browser PKCE is the default when a local browser is available. The browser talks directly to Microsoft, and the CLI never receives or stores your password. Normal Graph 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
 ```
 
@@ -157,12 +210,59 @@ The custom app must be a public client with `http://localhost` registered for br
 
 For short-lived automation, `TEAMS_ACCESS_TOKEN` overrides the stored credential. Refresh credentials are never written to the config file.
 
+Under WSL, Graph credentials use Windows DPAPI encryption for the current Windows
+user through `powershell.exe`; no D-Bus or Linux Secret Service is required. Windows
+executable interop must be enabled. Encrypted files live under
+`%LOCALAPPDATA%\teams-cli\credentials` and are shared by WSL distributions using
+the same Windows account and profile name. Existing WSL Secret Service sign-ins
+require `teams auth login` again after upgrading; their old entries are not migrated
+or removed. Native Linux uses Secret Service by default.
+
+### Using pass for Graph credentials
+
+On Linux, WSL and macOS, interactive Graph setup offers `pass` when it is installed
+and the selected password store has a readable `.gpg-id`. The OS store is recommended
+when available; if it is unavailable, setup recommends the configured pass store.
+Existing profiles keep their saved credential store without prompting again.
+
+To select it explicitly, initialize your GPG password store first, then run:
+
+```console
+pass init GPG_KEY_ID
+teams --profile work-pass init --credential-store pass --device-code
+# To use a different existing store:
+teams --profile other-work init --credential-store pass --pass-store-dir /path/to/password-store --device-code
+```
+
+Before opening Microsoft sign-in for a new pass credential, the CLI checks encryption
+and decryption using synthetic data in a private temporary store. The check leaves
+no probe entries or Git commits in your password store. GPG may ask you to unlock
+your key; configure `gpg-agent` and a suitable pinentry for your terminal or desktop.
+Terminal pinentry may need `export GPG_TTY="$(tty)"`. Helper operations time out after
+60 seconds if unlocking or another operation stalls.
+
+Tokens are passed to `pass` through stdin, and stored under
+`teams-cli/<SHA-256 of profile name>`. The CLI saves `credential_store = "pass"` and
+the absolute `pass_store_dir` in the profile. Changing `PASSWORD_STORE_DIR` later
+will not redirect that profile's credentials. Sign-in, refresh, status and logout
+use the same saved store; failures report the store or GPG problem without falling
+back to another backend. Failed replacements restore the previous encrypted file.
+As usual, pass manages its own local Git history if enabled; logout removes the
+current entry, while older encrypted versions may remain in that history.
+
+Use a new profile name to change credential stores or pass directories. After
+verifying the new connection, sign out the old profile if you no longer need it.
+`--no-login` validates the pass installation and recipient configuration without
+unlocking a key or running the encryption/decryption check.
+
 ## Everyday commands
 
 ```console
 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
@@ -178,7 +278,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:
 
@@ -273,7 +387,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
@@ -295,15 +411,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.
@@ -389,7 +512,7 @@ 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
+teams init --profile browser --backend desktop --desktop-client browser --desktop-account work-school --auto-start --yes
 # The window closes automatically after a successful chat read.
 # Teams then runs headless with the same saved sign-in:
 teams --profile browser
@@ -403,6 +526,13 @@ 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
@@ -413,7 +543,8 @@ The browser uses its own profile under the local data directory at
 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. Unverifiable processes are left untouched.
+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

{teams_cli-0.2.0 → teams_cli-0.2.2}/README.md

@@ -46,27 +46,80 @@ Run `teams` in a terminal on first use, or start explicitly:
 teams init
 ```
 
-`teams-cli` includes a maintained multitenant Microsoft Entra public-client registration, so normal setup does not require creating an app or copying a client ID:
+Choose **Work or school** or **Personal**, choose whether to enable sending, and
+follow sign-in. Setup checks this machine first and gives unavailable connections
+no selectable number, with an explanation of what they need. It chooses a separate
+browser port and opens your inbox once chats are readable. After that, just run:
 
 ```console
-teams init
+teams
 ```
 
-For a personal Microsoft account with the lightweight hidden browser:
+On macOS, Linux and WSL2, work/school setup prefers a dedicated browser; personal
+setup prefers the lightweight browser. Missing display support, missing executables,
+invalid browser overrides and unavailable matching downloads are checked before
+selection. Personal can use a full browser or Teams Desktop when lightweight mode
+is unavailable. Work/school can use Teams Desktop or Microsoft Graph when needed.
+When no lightweight runtime is installed, these checks query public Chrome for
+Testing version metadata at `googlechromelabs.github.io`; no browser download or
+Teams sign-in happens before consent.
+On a Linux terminal without a display, Graph uses device-code sign-in on another device.
+You explicitly approve reopening a dedicated browser
+when you start the inbox. The saved sign-in is reused, and expired work/school
+sign-in offers to reopen the sign-in window. Some organisations require keeping
+the browser visible; minimise it instead of closing it. WSL2 needs WSLg for sign-in.
+On native Windows, browser options are unavailable; use Teams Desktop or run inside
+WSL2 for browser mode.
+
+Guided setup saves connection settings only after a successful chat read, including
+Graph profiles. If sending was requested, desktop/browser setup also probes the
+send interface without sending a message. If that fails, you can explicitly continue
+read-only; setup never silently downgrades your choice. A successful probe establishes
+that the interface is available, while delivery and organisation policies are checked
+when you actually send. Teams build compatibility and sign-in still need live validation.
+
+Running setup again asks whether to connect another account or update an existing
+connection. Updates preserve Graph application/tenant settings and previously granted
+channel-history access. Failed Graph verification preserves the previous credential;
+if saving settings fails, the credential change is rolled back. Browser setup can resume
+an unfinished sign-in on the same port, or start a separate account without touching it.
+Recovery errors include the exact command to close that browser.
+You can forget an unfinished setup after confirmation; its browser data and saved
+sign-in remain on disk, and the old browser's close command is shown. Reusing that
+forgotten browser data requires explicit setup with its original `--desktop-port`.
+Setup offers unfinished connections under other names when you connect another account.
+
+Cold work-browser startup opens the inbox once chats are readable and checks sign-in
+renewal in the background. A sign-out pauses sending and offers sign-in in the inbox.
+Other startup-check failures keep chats readable and pause sending until you reopen
+the inbox to check again. Drafts stay in memory through the sign-in detour.
+Guided Graph setup disables conflicting token or permission environment overrides;
+explicit flags keep their automation behavior.
+
+**Other connection options** keeps Microsoft Graph and the running Teams Desktop
+available. Microsoft Graph includes a maintained Entra public-client registration,
+so normal API setup needs no app registration or copied client ID.
+
+Scripts and explicit connection flags keep their existing behaviour. For example:
 
 ```console
-teams init --profile personal --backend desktop --desktop-client browser-core
+teams init --backend graph
+# Or configure an automatically reopened work browser explicitly:
+teams init --profile work --backend desktop --desktop-client browser \
+  --desktop-account work-school --desktop-port 9224 --auto-start
 ```
 
-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 profiles default to read-only; add `--allow-send` to enable sending.
+Existing profiles retain their connection behaviour unless you opt in with setup
+or `--auto-start`. CLI reads, JSON output, demo mode and snapshots never start a
+browser automatically. See [lightweight browser setup](#low-memory-browser-client-experimental)
+for personal-account 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:
+For Microsoft Graph profiles, browser PKCE is the default when a local browser is available. The browser talks directly to Microsoft, and the CLI never receives or stores your password. Normal Graph 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
 ```
 
@@ -141,12 +194,59 @@ The custom app must be a public client with `http://localhost` registered for br
 
 For short-lived automation, `TEAMS_ACCESS_TOKEN` overrides the stored credential. Refresh credentials are never written to the config file.
 
+Under WSL, Graph credentials use Windows DPAPI encryption for the current Windows
+user through `powershell.exe`; no D-Bus or Linux Secret Service is required. Windows
+executable interop must be enabled. Encrypted files live under
+`%LOCALAPPDATA%\teams-cli\credentials` and are shared by WSL distributions using
+the same Windows account and profile name. Existing WSL Secret Service sign-ins
+require `teams auth login` again after upgrading; their old entries are not migrated
+or removed. Native Linux uses Secret Service by default.
+
+### Using pass for Graph credentials
+
+On Linux, WSL and macOS, interactive Graph setup offers `pass` when it is installed
+and the selected password store has a readable `.gpg-id`. The OS store is recommended
+when available; if it is unavailable, setup recommends the configured pass store.
+Existing profiles keep their saved credential store without prompting again.
+
+To select it explicitly, initialize your GPG password store first, then run:
+
+```console
+pass init GPG_KEY_ID
+teams --profile work-pass init --credential-store pass --device-code
+# To use a different existing store:
+teams --profile other-work init --credential-store pass --pass-store-dir /path/to/password-store --device-code
+```
+
+Before opening Microsoft sign-in for a new pass credential, the CLI checks encryption
+and decryption using synthetic data in a private temporary store. The check leaves
+no probe entries or Git commits in your password store. GPG may ask you to unlock
+your key; configure `gpg-agent` and a suitable pinentry for your terminal or desktop.
+Terminal pinentry may need `export GPG_TTY="$(tty)"`. Helper operations time out after
+60 seconds if unlocking or another operation stalls.
+
+Tokens are passed to `pass` through stdin, and stored under
+`teams-cli/<SHA-256 of profile name>`. The CLI saves `credential_store = "pass"` and
+the absolute `pass_store_dir` in the profile. Changing `PASSWORD_STORE_DIR` later
+will not redirect that profile's credentials. Sign-in, refresh, status and logout
+use the same saved store; failures report the store or GPG problem without falling
+back to another backend. Failed replacements restore the previous encrypted file.
+As usual, pass manages its own local Git history if enabled; logout removes the
+current entry, while older encrypted versions may remain in that history.
+
+Use a new profile name to change credential stores or pass directories. After
+verifying the new connection, sign out the old profile if you no longer need it.
+`--no-login` validates the pass installation and recipient configuration without
+unlocking a key or running the encryption/decryption check.
+
 ## Everyday commands
 
 ```console
 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
@@ -162,7 +262,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:
 
@@ -257,7 +371,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
@@ -279,15 +395,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.
@@ -373,7 +496,7 @@ 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
+teams init --profile browser --backend desktop --desktop-client browser --desktop-account work-school --auto-start --yes
 # The window closes automatically after a successful chat read.
 # Teams then runs headless with the same saved sign-in:
 teams --profile browser
@@ -387,6 +510,13 @@ 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
@@ -397,7 +527,8 @@ The browser uses its own profile under the local data directory at
 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. Unverifiable processes are left untouched.
+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