# Teams Phone CLI

A command-line tool for managing Microsoft Teams Phone configurations via Microsoft Graph API.

## Features

- **User Management** - List, search, and view Teams users and their voice configuration
- **Phone Number Management** - Assign, unassign, and manage phone numbers from your inventory
- **Policy Management** - View and assign voice policies (calling, voicemail, emergency, dial-plan, etc.)
- **Location Management** - Search and view emergency locations
- **Multi-Tenant Support** - Manage multiple tenants with easy switching
- **Bulk Operations** - Assign numbers and policies in bulk from CSV files
- **Automation-Friendly** - JSON output mode for scripting and automation

## Quick Start

### Installation

```bash
pip install teams-phone-cli
```

### Configure Your First Tenant

```bash
# Add a tenant with certificate authentication
teams-phone tenants add contoso \
    "12345678-1234-1234-1234-123456789012" \
    "87654321-4321-4321-4321-210987654321" \
    --display-name "Contoso Ltd" \
    --cert-path "/path/to/certificate.pem"
```

### Authenticate

```bash
teams-phone auth login
```

### Start Using

```bash
# List users
teams-phone users list

# Show a user's voice configuration
teams-phone users show john.doe@contoso.com

# List available phone numbers
teams-phone numbers list --status unassigned

# Assign a phone number
teams-phone numbers assign john@contoso.com +14255551234 --location "Seattle HQ"
```

## Prerequisites

- Python 3.10+
- Azure AD App Registration with required Graph API permissions
- Certificate or client secret for authentication

See the [Installation Guide](docs/installation.md) for detailed setup instructions.

## Commands

| Command | Description |
|---------|-------------|
| `users list` | List users with voice configuration |
| `users show <user>` | Show user voice configuration |
| `users search <query>` | Search users by name/UPN/phone |
| `numbers list` | List phone number inventory |
| `numbers show <number>` | Show phone number details |
| `numbers assign <user> <number>` | Assign number to user |
| `numbers unassign <number>` | Unassign phone number |
| `numbers bulk-assign <csv>` | Bulk assign from CSV |
| `policies list [type]` | List available policies |
| `policies show <user>` | Show user's policy assignments |
| `policies assign <user> <type> <name>` | Assign policy to user |
| `locations list` | List emergency locations |
| `locations search <query>` | Search locations |
| `tenants list` | List configured tenants |
| `tenants switch <name>` | Switch active tenant |
| `auth login` | Authenticate with tenant |
| `auth status` | Show authentication status |

See the [Command Reference](docs/commands.md) for full documentation.

## Global Options

```bash
teams-phone [OPTIONS] COMMAND [ARGS]

Options:
  -t, --tenant TEXT      Override default tenant
  -j, --json             Output in JSON format
  -v, --verbose          Show detailed output
  --no-color             Disable colored output
  --debug-log PATH       Write debug logs to file
  --help                 Show help message
```

## Examples

### User Management

```bash
# List all licensed users without phone numbers
teams-phone users list --licensed --unassigned

# Search for users by name
teams-phone users search "john" --field name

# Show user's complete voice configuration
teams-phone users show john.doe@contoso.com
```

### Phone Number Assignment

```bash
# Find available numbers
teams-phone numbers list --status unassigned --type callingPlan

# Assign with dry-run to preview
teams-phone numbers assign john@contoso.com +14255551234 --location "Seattle HQ" --dry-run

# Execute assignment
teams-phone numbers assign john@contoso.com +14255551234 --location "Seattle HQ"

# Bulk assign from CSV
teams-phone numbers bulk-assign assignments.csv --continue-on-error -o results.csv
```

### Policy Management

```bash
# List calling policies
teams-phone policies list calling

# Show user's current policies
teams-phone policies show john@contoso.com

# Assign a policy
teams-phone policies assign john@contoso.com calling AllowCalling
```

### Multi-Tenant Operations

```bash
# List configured tenants
teams-phone tenants list

# Switch to a different tenant
teams-phone tenants switch fabrikam

# Run a single command against a different tenant
teams-phone -t fabrikam users list
```

### JSON Output for Automation

```bash
# Get users as JSON
teams-phone users list --json | jq '.[] | .userPrincipalName'

# Get unassigned numbers as JSON
teams-phone numbers list --status unassigned --json > available-numbers.json
```

## Documentation

- [Installation Guide](docs/installation.md) - Prerequisites and setup
- [Configuration Guide](docs/configuration.md) - Config file and tenant profiles
- [Command Reference](docs/commands.md) - Full CLI documentation
- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions

## CSV Cache Setup

The CLI uses CSV files for location and policy data that isn't available via Graph API. Export this data using the provided PowerShell script:

```powershell
./scripts/Export-TeamsPhoneData.ps1 `
    -TenantId "your-tenant-id" `
    -ApplicationId "your-app-id" `
    -CertificateThumbprint "your-cert-thumbprint"
```

See [scripts/README.md](scripts/README.md) for detailed instructions.

## Development

```bash
# Clone the repository
git clone https://github.com/hvkc/teams-phone.git
cd teams-phone

# Install with development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest tests/

# Run linter and type checker
uv run ruff check src/ tests/
uv run mypy src/ tests/
```

## License

MIT License - see [LICENSE](LICENSE) for details.
