@michaelschnyder/teams-cli 0.1.0 → 0.1.1-canary.2.1.g2e6c221f

package/README.md

@@ -1,248 +1,127 @@
 # teams-cli
 
-A safety-conscious command-line client for persistent Microsoft Teams sessions. It supports multiple tenants and users, named profiles, structured output, agent skills, and optional subject-path policies that can prevent messages from being sent to unintended chats or channels.
+A command-line client that gives people and compatible coding agents access to Microsoft Teams through a persistent local browser session.
 
 > [!WARNING]
 > This project relies on undocumented Microsoft Teams behavior and a Microsoft first-party client identity. It is unsupported, may be blocked by tenant policy, and may stop working without notice. Obtain organizational approval before using it, and never run live write tests against a production tenant.
 
-## Requirements
-
-- Node.js 22.20 or newer. Node.js 24 LTS is recommended.
-- Microsoft Edge or Google Chrome.
-- A Microsoft 365 account with Teams access.
-
-### Install Node.js on Windows
-
-Open PowerShell and install the current Node.js LTS release with Windows Package Manager:
-
-```powershell
-winget install --id OpenJS.NodeJS.LTS --exact --source winget
-```
-
-Open a new terminal, then verify both tools:
-
-```powershell
-node --version
-npm --version
-```
-
-If `winget` is unavailable, install Microsoft App Installer or use the signed installer from the [Node.js download page](https://nodejs.org/en/download).
-
-### Install Node.js on macOS
-
-With [Homebrew](https://brew.sh/):
-
-```bash
-brew install node@24
-echo 'export PATH="$(brew --prefix node@24)/bin:$PATH"' >> ~/.zshrc
-source ~/.zshrc
-node --version
-npm --version
-```
-
-Alternatively, use the signed macOS package from the [Node.js download page](https://nodejs.org/en/download).
-
-### Install Node.js on Linux
-
-Distribution repositories may contain a Node.js version older than this CLI requires. A version manager keeps the runtime separate from system packages. The following follows the [Node.js download guidance](https://nodejs.org/en/download) using `nvm`; inspect downloaded installation scripts before running them:
-
-```bash
-curl -o nvm-install.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh
-less nvm-install.sh
-bash nvm-install.sh
-. "$HOME/.nvm/nvm.sh"
-nvm install 24
-node --version
-npm --version
-```
-
-Node.js also publishes signed standalone Linux archives on its download page.
+## Quick start
 
-## Install teams-cli
+You need Node.js 22.20 or newer, Microsoft Edge or Google Chrome, and a Microsoft 365 account with Teams access. Node.js 24 LTS is recommended. See the [installation guide](docs/use/installation.md) for operating-system-specific setup and troubleshooting.
 
-Install the command globally:
+### 1. Install the CLI
 
 ```bash
 npm install --global @michaelschnyder/teams-cli
 teams-cli --version
-teams-cli --help
 ```
 
-To try it without a permanent installation:
+### 2. Sign in
 
 ```bash
-npx @michaelschnyder/teams-cli --help
+teams-cli login
 ```
 
-If a global install reports a permissions error, use a Node version manager instead of running npm with `sudo`. If installation succeeds but `teams-cli` is not found, run `npm prefix --global` and ensure that npm's global executable directory is on `PATH`.
-
-## Quick start
-
-Interactive login opens a dedicated Edge profile by default:
-
-```bash
-teams-cli --profile work --tenant YOUR_TENANT_ID auth login
-teams-cli --profile work auth whoami
-```
-
-The successful login records the verified tenant, user, and browser in the named profile. Subsequent commands reuse identity-isolated tokens and refresh them from the saved browser state when necessary.
-
-Discover Teams data:
-
-```bash
-teams-cli --profile work person search "Alice" --json
-teams-cli --profile work chat list --json
-teams-cli --profile work channel list --json
-teams-cli --profile work message list --chat CHAT_ID --json
-```
+`teams-cli login` is the convenient alias for `teams-cli auth login`. It opens a dedicated Microsoft Edge profile by default, or a dedicated Google Chrome profile when selected. It does not reuse your normal browser profile or its signed-in session. The CLI discovers the Teams tenant and user, then saves them in the implicit `default` profile. Most users never need to provide a tenant ID or create a named profile.
 
-Send a plain-text message after checking the selected identity and target:
+### 3. Install the agent skill
 
 ```bash
-teams-cli --profile work auth whoami
-teams-cli --profile work policy check send --chat CHAT_ID
-teams-cli --profile work message send --chat CHAT_ID --body "Hello"
-```
-
-Use `--channel CHANNEL_ID` instead of `--chat CHAT_ID` for channel messages. A message body can also be piped on stdin.
-
-## Command overview
-
-```text
-teams-cli [--profile NAME] [--tenant ID] [--user ID] [--browser edge|chrome]
-
-version    show the installed version or upgrade it
-skills     list, locate, install, and refresh packaged agent skills
-auth       login, refresh, whoami, tokens, logout
-profile    list, show, save, remove
-policy     init, list, show, check, activate
-person     search, get, image
-chat       list, get
-channel    list, get
-message    list, get, send
+teams-cli skills install
 ```
 
-Run `teams-cli <command> --help` for complete arguments and options.
+The packaged `teams-cli` skill teaches compatible coding agents how to authenticate, discover Teams resources, read and send messages, and respect policies. Auto-detection supports Codex, Claude Code, Cursor, GitHub Copilot, OpenCode, Windsurf, Gemini CLI, Pi, and generic `.agents/skills` environments.
 
-### Structured output
-
-Person, chat, channel, and message commands that return data support `--json`. JSON payloads stay on stdout. Progress, warnings, update notices, and sanitized debug output stay on stderr, so scripts can safely pipe stdout.
+Installing the CLI and its skill is usually everything needed to start using Teams with an agent. See [agent skill installation](docs/use/agent-skills.md) when auto-detection is unavailable or several agent environments are installed.
 
-## Profiles and local state
+### 4. Add a workspace policy
 
-Profiles provide defaults; global flags override them for one command. When no profile is selected, the profile named `default` is used.
+Policies are optional but recommended for agent-assisted work. From the workspace the agent will operate in, run:
 
 ```bash
-teams-cli profile list
-teams-cli profile show work
-teams-cli --tenant TENANT_ID --user USER_ID --browser chrome profile save work
-teams-cli profile remove work
+teams-cli policy edit --open
 ```
 
-Configuration, authentication, browser state, policies, update state, and managed skill-installation records live under `~/.teams-cli/`. Secret-bearing files and directories are created with owner-only permissions on supported operating systems.
-
-See [profiles and precedence](docs/use/profiles.md) and [authentication and token handling](docs/use/authentication.md).
-
-## Policies
-
-Policies are optional. Inactive policies audit and warn without enforcing; active policies enforce the intersection of all matching subject-path rules. A malformed policy store puts authenticated operations into fail-safe mode. Active policies cannot be deactivated through this CLI.
-
-```bash
-teams-cli --profile work policy init project-agent
-teams-cli policy show project-agent
-teams-cli policy check send --chat CHAT_ID
-teams-cli policy activate project-agent
-```
+Choose which people, group chats, and channels may be read or posted to, then save and activate the policy. Policies are cooperative CLI-level safeguards: they help prevent accidental access and posts through `teams-cli`, but they are not an operating-system sandbox or a server-side Teams permission.
 
-Review and edit the generated allowlists before activation. See [workspace policies](docs/use/policies.md) and the [security model](https://github.com/michaelschnyder/teams-cli/blob/main/docs/build/security-model.md).
+See [workspace policies](docs/use/policies.md) for the editor, audit mode, activation, manual editing and deactivation, overlapping policies, and the security boundary.
 
-### Token export
+### 5. Use Teams
 
-The existing authentication commands can print raw bearer tokens or decoded JWT claims:
+Ask a compatible agent naturally after installing the skill, for example:
 
-```bash
-teams-cli --profile work auth tokens
-teams-cli --profile work auth token access
-teams-cli --profile work auth tokens --decode
+```text
+Find my chat with Alice and summarize the latest five messages.
+Draft a reply to the Project Phoenix channel, but show it to me before sending.
 ```
 
-Applicable active policies can deny raw token export. Treat exported tokens like passwords: another HTTP client can use them outside the CLI's cooperative policy checks. Never paste them into prompts, logs, issues, or source files.
-
-## Agent skills
-
-The npm package includes skills that teach compatible coding agents how to use this CLI safely. Auto-detection supports Codex, Claude Code, Cursor, GitHub Copilot, OpenCode, Windsurf, Gemini CLI, Pi, and generic `.agents/skills` environments.
+Or use the CLI directly:
 
 ```bash
-teams-cli skills list
-teams-cli skills path
-teams-cli skills install
+teams-cli auth whoami
+teams-cli person search "Alice" --json
+teams-cli chat search "Alice" --json
+teams-cli channel list --json
+teams-cli message list --chat CHAT_ID --json
+teams-cli message send --person alice@example.com --body "Hello"
 ```
 
-When several environments are detected, the skills are installed into all of them. Specify a target when detection is unavailable:
+For an existing group chat or channel, use `--chat CHAT_ID` or `--channel CHANNEL_ID`. You can optionally preview a known target with `teams-cli policy check send`; the send command always enforces the applicable policy again immediately before posting. Sending is externally visible and the CLI has no delete or undo command.
 
-```bash
-teams-cli skills install codex
-teams-cli skills install github-copilot --project
-teams-cli skills install agents --name teams-cli
-teams-cli skills install all
-teams-cli skills install --dir /custom/skills
+```mermaid
+flowchart LR
+    install[Install teams-cli] --> login[Sign in once]
+    login --> skill[Install the agent skill]
+    skill --> policy[Recommended: add a workspace policy]
+    policy --> use[Ask an agent or run commands]
 ```
 
-Initial installation does not replace an existing `SKILL.md`; use `--force` when replacement is intentional. Successful destinations are recorded. Installed copies are managed by the CLI and are refreshed by `teams-cli skills reinstall` and after a successful CLI upgrade, replacing local edits in those copies.
+## Important concepts
 
-## Updates and upgrades
+### Default session
 
-At startup, the CLI may launch a detached npm registry check. It runs at most once per hour, does not delay the command, and stores only timestamps and version numbers. If a newer version is found, a notice is printed to stderr on the next invocation.
+`teams-cli login` discovers and records the verified tenant, user, and browser in the `default` profile. The longer `teams-cli auth login` form remains available. Named profiles and explicit `--tenant` or `--user` flags are optional tools for people who deliberately maintain more than one identity. Profiles select configuration; they are not permission boundaries. See [authentication](docs/use/authentication.md) and [optional profiles](docs/use/profiles.md).
 
-Disable checks with either environment variable:
+### Agent skill
 
-```bash
-export NO_UPDATE_NOTIFIER=1
-# or
-export TEAMS_CLI_DISABLE_UPDATE_CHECK=1
-```
+The skill gives an agent the operational knowledge that command help alone cannot provide: discover current IDs before using them, verify the active identity, keep JSON payloads separate from diagnostics, optionally preview policy decisions, and stop on denials. Installed copies can be refreshed when the CLI is upgraded.
 
-Checks are automatically disabled in CI. Upgrade the global npm installation and refresh recorded skills with:
+### Cooperative policies
 
-```bash
-teams-cli version --upgrade
-```
+Policies are YAML files matched against the canonical working-directory path. Inactive policies audit and warn; active policies constrain identities, message reads, posts, and raw-token export. All matching active policies must allow an operation, so overlapping policies can only preserve or narrow access.
 
-This command updates the global npm package. It does not modify a project-local or one-off `npx` installation.
+These safeguards apply to operations made through this CLI. A sufficiently privileged local process can change policy files, and a bearer token used by another HTTP client is outside the CLI's checks. Read-only file permissions add protection against accidental edits but do not make a policy immutable.
 
-## Troubleshooting
+### Structured output
 
-- `teams-cli: command not found`: check `npm prefix --global` and your `PATH`.
-- Browser launch fails: install Edge or Chrome and select it with `--browser edge|chrome`.
-- Login succeeds but Teams access fails: confirm that the account has a Teams-enabled Microsoft 365 license.
-- Stored identity is rejected: run `auth login` again for the selected tenant, user, and profile.
-- An agent environment is not detected: pass its name explicitly to `skills install`.
-- Use `--debug` for sanitized request method, endpoint, status, duration, and retry diagnostics. Headers, tokens, cookies, query values, and bodies are not logged.
+Person, chat, channel, and message commands support `--json`. JSON payloads stay on stdout, while progress, warnings, update notices, and sanitized diagnostics stay on stderr. Scripts and agents can therefore consume stdout without mixing it with status text.
 
-## Uninstall
+## Command reference
 
-Remove the global command:
+| Command | Purpose | Examples and details |
+| --- | --- | --- |
+| `login` | Sign in using the default session; alias for `auth login` | [Authentication](docs/use/authentication.md) |
+| `version` | Inspect build provenance, check for updates, or select the notification channel | [Installation and upgrades](docs/use/installation.md) |
+| `skills` | List, locate, install, and refresh the packaged agent skill | [Agent skill installation](docs/use/agent-skills.md) |
+| `auth` | Login, refresh, inspect, export tokens, or logout | [Authentication](docs/use/authentication.md) |
+| `profile` | Manage optional named identity selectors | [Profiles](docs/use/profiles.md) |
+| `policy` | Create, inspect, check, activate, and edit safeguards | [Policies](docs/use/policies.md) |
+| `person` | Search people, inspect profiles, and retrieve images | [Command examples](docs/use/commands.md) |
+| `chat` | Search, explicitly enumerate, and inspect chats | [Command examples](docs/use/commands.md) |
+| `channel` | List and inspect teams and channels | [Command examples](docs/use/commands.md) |
+| `message` | List, get, and send messages | [Command examples](docs/use/commands.md) |
 
-```bash
-npm uninstall --global @michaelschnyder/teams-cli
-```
+Run `teams-cli --help` or `teams-cli <command> --help` for the complete options supported by the installed version.
 
-Uninstalling the npm package intentionally leaves authentication and configuration data in `~/.teams-cli/`. Run `auth logout` for each stored identity before uninstalling. Remove `~/.teams-cli/` manually only when you intend to delete every remaining profile, token, browser session, policy, update record, and managed-skill record.
+## Local state and security
 
-Installed agent skill copies live outside `~/.teams-cli/` and are not deleted automatically.
+Configuration, authentication, dedicated browser state, policies, update state, and managed skill-installation records live under `~/.teams-cli/`. Secret-bearing files and directories use owner-only permissions on supported operating systems.
 
-## Development
+Raw bearer tokens can be exported by authentication commands when applicable policies allow it. Treat them like passwords: never paste them into prompts, logs, issues, or source files. See the [security model](docs/build/security-model.md) for the complete trust boundary.
 
-```bash
-npm install
-npm run check
-npm test
-npm run build
-npm run package:check
-npm run package:smoke
-```
+## Contributing
 
-See [CONTRIBUTING.md](https://github.com/michaelschnyder/teams-cli/blob/main/CONTRIBUTING.md), [architecture](https://github.com/michaelschnyder/teams-cli/blob/main/docs/build/architecture.md), [testing](https://github.com/michaelschnyder/teams-cli/blob/main/docs/build/testing.md), and the [release guide](docs/releasing.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidance.
 
 ## License
 

package/dist/auth.js

@@ -12,6 +12,14 @@ const defaultDependencies = {
     exchangeToken: exchangeInitialToken,
     now: () => new Date(),
 };
+export class InteractiveLoginRequiredError extends Error {
+    code;
+    constructor(code) {
+        super(`Microsoft needs an interactive sign-in (${code}).`);
+        this.code = code;
+        this.name = "InteractiveLoginRequiredError";
+    }
+}
 const execFileAsync = promisify(execFile);
 export async function passwordFromCommand(command) {
     if (!isAbsolute(command))
@@ -113,7 +121,7 @@ function createStoredSession(tokens, exchanged, browser, expectedTenant, now) {
 }
 function interactiveRefreshError(error) {
     if (error instanceof OAuthRedirectError) {
-        throw new Error(`Microsoft could not refresh the session without interaction (${error.code}). Run \`teams-cli auth login\`.`);
+        throw new InteractiveLoginRequiredError(error.code);
     }
     throw error;
 }

package/dist/build-info.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "version": "0.1.1-canary.2.1.g2e6c221f",
+  "channel": "canary",
+  "builtAt": "2026-09-04T04:46:46.454Z",
+  "source": {
+    "branch": "codex/canary-snapshot-channels",
+    "commit": "2e6c221f49e6aeb69fa7c33f98c1b0e09a42ffce",
+    "commitUrl": "https://github.com/michaelschnyder/teams-cli/commit/2e6c221f49e6aeb69fa7c33f98c1b0e09a42ffce",
+    "pullRequest": 11,
+    "pullRequestUrl": "https://github.com/michaelschnyder/teams-cli/pull/11",
+    "author": "michaelschnyder"
+  },
+  "trigger": {
+    "kind": "merged-pull-request",
+    "actor": "michaelschnyder"
+  },
+  "runner": {
+    "name": "GitHub Actions 1000001056",
+    "os": "Linux",
+    "architecture": "X64"
+  },
+  "workflow": {
+    "runId": "33837821954",
+    "runNumber": "2",
+    "runAttempt": "1",
+    "url": "https://github.com/michaelschnyder/teams-cli/actions/runs/33837821954"
+  },
+  "releaseNotes": {
+    "title": "Add canary and snapshot release channels",
+    "body": "## Summary\n\n- publish stable releases, merged-PR canaries, and authorized branch snapshots through one npm workflow\n- embed build provenance and release notes, add channel-aware updates, and protect npx executions\n- show the exact installed version and GitHub link in the policy editor\n- standardize CI on latest Node.js LTS across Linux, macOS, and Windows\n- remove the manually maintained changelog in favor of release, pull request, and commit notes\n\n## Verification\n\n- npm run check\n- npm test (97 tests)\n- npm run build\n- npm run package:check\n- npm run package:smoke\n- npm audit --omit=dev",
+    "url": "https://github.com/michaelschnyder/teams-cli/pull/11"
+  }
+}