@awolve/myoffice

MyOffice CLI

A command-line interface for personal Microsoft 365 access via Microsoft Graph API.

Unlike admin-focused M365 tools, this uses delegated authentication - users authenticate as themselves and can only access their own data.

Features

• Email - List, read, search, send (with attachments), reply, delete, mark read/unread, move to folders
• Calendar - List, create, update, delete events (with Teams meetings)
• Tasks - Manage Microsoft To Do lists and tasks
• Planner - Access plans, buckets, and tasks
• OneDrive - Browse, search, read files
• SharePoint - Access sites and document libraries
• Teams - List teams, channels, read/post messages
• Chats - 1:1 and group chats
• Contacts - List, search, create, update contacts

Installation

From npm (recommended)

npm install -g awolve-myoffice-cli

From source

git clone https://github.com/awolve/ops-myoffice.git
cd ops-myoffice
npm install
npm run build
npm link

Prerequisites

• Node.js 18+
• An Azure AD app registration with delegated permissions
• Microsoft 365 account

Configuration

Add to your shell profile (~/.zshrc or ~/.bashrc):

export M365_CLIENT_ID="your-app-client-id"
# Optional: export M365_TENANT_ID="your-tenant-id"

Authentication

myoffice login

Opens a browser for device code authentication. Token is cached at ~/.config/myoffice-mcp/msal-cache.json.

CLI Usage

# Check status
myoffice status

# Email
myoffice mail list
myoffice mail list --unread
myoffice mail list --folder "Under Processing"  # Custom folders supported
myoffice mail read <id>
myoffice mail move --id <id> --folder "Captured"
myoffice mail send --to user@example.com --subject "Hi" --body "Hello"
myoffice mail send --to user@example.com --subject "Report" --body "See attached" --attach report.pdf  # With attachment

# Calendar
myoffice calendar list
myoffice calendar list --start 2024-01-15 --end 2024-01-20

# Tasks (To Do)
myoffice tasks lists
myoffice tasks list
myoffice tasks create "Buy milk"

# Files (OneDrive)
myoffice files list
myoffice files search "report"

# Teams & Chats
myoffice teams list
myoffice chats list

# Planner
myoffice planner plans
myoffice planner tasks <planId>

# JSON output (for scripting)
myoffice mail list --json

Run myoffice --help for all commands.

Azure AD App Registration

1. Go to Azure Portal > Azure Active Directory > App registrations
2. Click New registration
   • Name: MyOffice CLI (or your choice)
   • Supported account types: Accounts in any organizational directory
   • Redirect URI: Leave blank (uses device code flow)
3. Note the Application (client) ID
4. Go to Authentication > Enable Allow public client flows = Yes
5. Go to API permissions > Add Microsoft Graph delegated permissions:
   • Mail.ReadWrite, Mail.Send
   • Calendars.ReadWrite
   • Tasks.ReadWrite
   • Files.ReadWrite, Sites.Read.All
   • Contacts.ReadWrite
   • Team.ReadBasic.All, Channel.ReadBasic.All
   • ChannelMessage.Read.All, ChannelMessage.Send
   • Chat.Create, Chat.ReadBasic, Chat.Read, ChatMessage.Send
   • Tasks.Read, Tasks.ReadWrite, Group.Read.All (for Planner)
   • User.Read, offline_access

Development

npm install      # Install dependencies
npm run dev      # Run with tsx (no build needed)
npm run build    # Compile TypeScript to dist/
npm run login    # Authenticate with Microsoft

Project Structure

src/
├── cli.ts             # CLI entry point (Commander.js)
├── core/
│   └── handler.ts     # Command dispatch logic
├── cli/
│   └── formatter.ts   # Human-readable output formatting
├── auth/              # Authentication (device code flow, token cache)
├── tools/             # Microsoft Graph API implementations
└── utils/             # Graph client, version helper

Testing Locally

# Test CLI directly (no build needed)
npx tsx src/cli.ts mail list

# Or build first then test
npm run build
node dist/cli.js mail list

Deploying to npm

The package is published to npm as awolve-myoffice-cli.

First-Time Setup

1. Create npm account at https://www.npmjs.com/signup
2. Login from terminal:

   npm login

Publishing a New Version

# 1. Make sure you're on main branch with clean working directory
git checkout main
git pull
git status  # Should be clean

# 2. Run tests / verify everything works
npm run build
node dist/cli.js --help

# 3. Bump version (choose one)
npm version patch  # 1.1.0 -> 1.1.1 (bug fixes)
npm version minor  # 1.1.0 -> 1.2.0 (new features)
npm version major  # 1.1.0 -> 2.0.0 (breaking changes)

# 4. Publish to npm (builds automatically via prepublishOnly)
npm publish --access public

# 5. Push version commit and tag to GitHub
git push && git push --tags

What Gets Published

The files field in package.json controls what's included:

• dist/**/* - Compiled JavaScript
• README.md - Documentation

Source code (src/), specs, and dev files are NOT published.

Verifying Publication

# Check package on npm
npm view awolve-myoffice-cli

# Test fresh install
npm install -g awolve-myoffice-cli
myoffice --version

Important: Version Immutability

npm does not allow republishing the same version. Once 1.1.0 is published, that version number is permanently taken. If you need to fix something:

1. Bump to a new version (npm version patch → 1.1.1)
2. Publish the new version

There is no way to "update" an existing version.

Troubleshooting

• "You must be logged in" - Run npm login
• "Package name already exists" - Name is taken, choose another
• "Cannot publish over existing version" - Bump version with npm version patch
• Build fails during publish - Fix TypeScript errors first

Security

• Uses delegated permissions only - users can only access their own data
• Tokens stored locally with restrictive permissions
• No client secrets required (public client)
• Destructive operations require explicit confirmation

License

MIT