Skip to content

Rewrite cli/README.md for npm publish #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TianqiZhang merged 1 commit into from
May 7, 2026
Merged

Rewrite cli/README.md for npm publish #6

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 60 additions & 82 deletions cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,117 +1,95 @@
# msevents CLI
# Microsoft Events CLI `preview`

Command-line tool for searching Microsoft flagship event sessions (Build, Ignite). Fetches the public session catalog, builds a local search index, and serves filtered results to agents or humans.
`msevents` is a terminal CLI for searching Microsoft flagship event session catalogs (Build, Ignite, AI Tour).

Named `msevents` (not `msbuild`) because it covers all Microsoft flagship events, matching the `microsoft-events` skill's year-round framing. Adding a new event is a config update, not a code change. Published as `@microsoft/events-cli` on npm, following the `@microsoft/learn-cli` pattern.
It fetches public session catalogs, builds a local search index, and returns filtered results — useful for agents, scripts, or quick lookups from the terminal.

## Usage
## Requirements

```sh
# Run directly (no install needed)
npx @microsoft/events-cli sessions --query "Azure AI Foundry"
This project requires Node.js 22 or later.

# Or install globally
```bash
node --version
```

## Installation

### Option A: Run instantly with `npx` (no install)

```bash
npx @microsoft/events-cli sessions --query "Microsoft Foundry"
```

### Option B: Install globally

```bash
npm install -g @microsoft/events-cli
msevents sessions --query "Azure AI Foundry"
msevents sessions --query "Microsoft Foundry"
```

## Commands

```sh
# Download and cache session catalogs
msevents refresh # all known events
msevents refresh --event build-2025 # just one

# Search sessions by keyword (searches across all fields, boosts title)
```bash
msevents sessions --query "agent orchestration"

# Search sessions by technology (matches product, tags, topic, languages)
msevents sessions --tech "Azure AI Foundry"
msevents sessions --tech "Microsoft Foundry"
msevents sessions --tech "Azure Cosmos DB" --type lab

# Search sessions by speaker
msevents sessions --speaker "Scott Hanselman"

# Combine filters
msevents sessions --tech "Azure AI Foundry" --speaker "Yina Arenas"
msevents sessions --tech "Microsoft Foundry" --speaker "Yina Arenas"
msevents sessions --event build-2025 --query "Foundry"

# Get a specific session (searches all cached events, disambiguates on collision)
msevents session BRK155

# Show what's cached
msevents refresh
msevents refresh --event build-2026
msevents status
# build-2025: 520 sessions, cached 2h ago
# ignite-2025: 312 sessions, cached 3d ago
# build-2026: endpoint not yet available
```

## Output

Human-readable text by default, `--json` for piping to agents or other tools.

```sh
msevents sessions --query "Foundry" --json
```

## Multi-event design

The session catalog endpoint follows a predictable pattern:

```
https://eventtools.event.microsoft.com/{event}{year}-prod/fallback/session-all-en-us.json
Available commands:

- `sessions` searches sessions across all cached events.
- `--query <text>` keyword search across all fields (boosts title)
- `--tech <name>` search by technology (matches product, tags, topic, languages)
- `--speaker <name>` search by speaker name
- `--type <type>` filter by session type (breakout, lab, demo, keynote)
- `--event <id>` filter to a specific event (e.g., `build-2026`, `ignite-2025`)
- `--limit <n>` max results (default: 10)
- `session <code>` looks up a specific session by code. Searches all cached events; disambiguates if the code appears in multiple events.
- `--event <id>` scope to a specific event
- `refresh` downloads and caches session catalogs.
- `--event <id>` refresh a specific event only
- `--force` bypass cache, re-fetch unconditionally
- `status` shows what's cached and how fresh it is.

The `sessions` and `session` commands output human-readable text by default. Pass `--json` to get structured JSON, which is useful for piping to agents or other tools:

```bash
msevents sessions --query "Foundry" --json | jq '.[].title'
msevents session BRK155 --json
```

Known events:
## Supported events

| Event | Endpoint | Status |
| Event | Event ID | Status |
|-------|----------|--------|
| Build 2025 | `build2025-prod` | Live, 520 sessions |
| Ignite 2025 | `ignite2025-prod` | Live, 1090 sessions |
| Build 2026 | `build2026-prod` | Live, 60 sessions |
| Ignite 2026 | `ignite2026-prod` | Not yet available |
| Build 2026 | `build-2026` | Live |
| Ignite 2025 | `ignite-2025` | Live |
| Build 2025 | `build-2025` | Live |

The `--event` flag filters to a single event. Without it, commands search across everything cached. Adding a new event means adding its endpoint to the known events list.
Use `--event <id>` to filter to a single event. Without it, commands search across everything cached.

## Behavior

- **Auto-refresh**: if the cache is empty on first search, the CLI fetches and caches automatically. No explicit `refresh` needed.
- **Cache TTL**: 24 hours. `refresh --force` bypasses. Uses conditional GET (ETag/Last-Modified) for cheap revalidation.
- **Session lookup**: `session BRK155` searches all cached events. If the code exists in multiple events, shows disambiguation.
- **Auto-refresh**: on first search, the CLI fetches and caches automatically. No explicit `refresh` needed.
- **Cache TTL**: 24 hours. `refresh --force` bypasses.
- **Disambiguation**: if a session code exists in multiple events, the CLI shows options.
- **Results**: 10 by default, `--limit` to override.

## Relationship to the skill

The `microsoft-events` skill is the reasoning layer — it decides when to activate, how to inventory the developer's project, and how to present results. The CLI is the data access layer — it handles fetching, caching, indexing, and searching.
## Development

The skill prefers the CLI when available and falls back to direct HTTP fetch when it's not. See the [data access investigation](../docs/data-access-investigation.md) for the full architecture analysis.
To build and test from source:

## Local development

```sh
```bash
cd cli
npm install
npm run build
npm test

# Run locally
node dist/index.js sessions --query "Azure AI Foundry"
node dist/index.js refresh
node dist/index.js status

# Link globally (makes `msevents` available everywhere, no npm publish needed)
npm link
msevents sessions --tech "Azure AI Foundry" --json

# Unlink when done
npm unlink -g @microsoft/events-cli
node dist/index.js --help
```

## Stack

Following the [mslearn CLI](https://github.com/MicrosoftDocs/mcp/tree/main/cli) pattern:

- TypeScript, Node.js 22+
- commander for argument parsing
- minisearch for local search index
- env-paths for XDG-compliant cache location
Loading