# Command Reference

Complete reference for all Teams Phone CLI commands.

## Global Options

Available on all commands:

| Option | Short | Description |
|--------|-------|-------------|
| `--tenant <name>` | `-t` | Override default tenant for this command |
| `--json` | `-j` | Output in JSON format for automation |
| `--verbose` | `-v` | Show detailed output and debug information |
| `--no-color` | | Disable colored output |
| `--debug-log <path>` | | Write debug logs to file (JSON Lines format) |
| `--help` | | Show help for the command |

## Users Commands

Manage Teams users and their voice configuration.

### users list

List users with voice configuration.

```bash
teams-phone users list [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--licensed` / `--unlicensed` | Filter by Teams Phone license status |
| `--assigned` / `--unassigned` | Filter by phone number assignment |
| `-a`, `--account-type <type>` | Filter by account type: `user`, `resourceAccount`, `guest`, `sfbOnPremUser`, `ineligibleUser`, `unknown` |
| `-l`, `--limit <n>` | Limit results to n users |
| `--all` | Fetch all users (may be slow for large tenants) |

**Examples:**

```bash
# List first 50 users (default)
teams-phone users list

# List unlicensed users
teams-phone users list --unlicensed

# List users without phone numbers
teams-phone users list --unassigned

# List resource accounts
teams-phone users list --account-type resourceAccount

# List all users as JSON
teams-phone users list --all --json
```

### users show

Show detailed voice configuration for a specific user.

```bash
teams-phone users show <USER>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `USER` | User identifier: UPN (email), display name, or object ID |

**Examples:**

```bash
teams-phone users show john.doe@contoso.com
teams-phone users show "John Doe"
teams-phone users show 12345678-1234-1234-1234-123456789012
```

### users search

Search for users by name, UPN, or phone number.

```bash
teams-phone users search <QUERY> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `QUERY` | Search term (partial match supported) |

**Options:**

| Option | Description |
|--------|-------------|
| `-f`, `--field <field>` | Limit search to: `name`, `upn`, `phone` |
| `-l`, `--limit <n>` | Maximum results (default: 25) |

**Examples:**

```bash
# Search by any field
teams-phone users search "john"

# Search by phone number
teams-phone users search "+1425" --field phone

# Search by UPN
teams-phone users search "@contoso.com" --field upn
```

## Numbers Commands

Manage phone number inventory and assignments.

### numbers list

List phone numbers in inventory.

```bash
teams-phone numbers list [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-s`, `--status <status>` | Filter by status: `unassigned`, `userAssigned`, `conferenceAssigned`, `voiceApplicationAssigned` |
| `-t`, `--type <type>` | Filter by type: `directRouting`, `callingPlan`, `operatorConnect` |
| `-c`, `--city <city>` | Filter by city (case-sensitive) |
| `-l`, `--limit <n>` | Limit results to n numbers |
| `--all` | Fetch all numbers (may be slow) |

**Examples:**

```bash
# List unassigned numbers
teams-phone numbers list --status unassigned

# List Calling Plan numbers
teams-phone numbers list --type callingPlan

# List numbers in Seattle
teams-phone numbers list --city Seattle

# List all numbers as JSON
teams-phone numbers list --all --json
```

### numbers show

Show detailed information for a specific phone number.

```bash
teams-phone numbers show <NUMBER>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NUMBER` | Phone number in E.164 format or partial |

**Examples:**

```bash
teams-phone numbers show +14255551234
teams-phone numbers show 4255551234
```

### numbers search

Search phone numbers by pattern.

```bash
teams-phone numbers search <PATTERN> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `PATTERN` | Search pattern with wildcards: `206*` (prefix), `*1234` (suffix), `*555*` (contains) |

**Options:**

| Option | Description |
|--------|-------------|
| `-l`, `--limit <n>` | Maximum results (default: 25) |

**Examples:**

```bash
# Find numbers starting with area code
teams-phone numbers search "206*"

# Find numbers ending with extension
teams-phone numbers search "*1234"

# Find numbers containing pattern
teams-phone numbers search "*555*"
```

### numbers assign

Assign a phone number to a user.

```bash
teams-phone numbers assign <USER> <NUMBER> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `USER` | User identifier (UPN, display name, or object ID) |
| `NUMBER` | Phone number to assign (E.164 format or partial) |

**Options:**

| Option | Description |
|--------|-------------|
| `-l`, `--location <location>` | Emergency location ID or description. Required for Calling Plan numbers |
| `-t`, `--type <type>` | Number type: `directRouting`, `callingPlan`, `operatorConnect` (default: callingPlan) |
| `--dry-run` | Preview assignment without making changes |
| `--no-wait` | Return immediately without waiting for operation to complete |
| `-f`, `--force` | Skip confirmation prompt |

**Examples:**

```bash
# Assign number to user
teams-phone numbers assign john@contoso.com +14255551234

# Assign with location (required for Calling Plan)
teams-phone numbers assign john@contoso.com +14255551234 --location "Seattle HQ"

# Preview without changes
teams-phone numbers assign john@contoso.com +14255551234 --dry-run

# Skip confirmation
teams-phone numbers assign john@contoso.com +14255551234 --location "Seattle HQ" --force
```

### numbers unassign

Unassign a phone number from its current user.

```bash
teams-phone numbers unassign <NUMBER> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NUMBER` | Phone number to unassign (E.164 format or partial) |

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview unassignment without making changes |
| `--no-wait` | Return immediately without waiting for operation to complete |
| `-f`, `--force` | Skip confirmation prompt |

**Examples:**

```bash
teams-phone numbers unassign +14255551234
teams-phone numbers unassign +14255551234 --force
teams-phone numbers unassign +14255551234 --dry-run
```

### numbers update

Update phone number location or network site settings.

```bash
teams-phone numbers update <NUMBER> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NUMBER` | Phone number to update (E.164 format or partial) |

**Options:**

| Option | Description |
|--------|-------------|
| `-l`, `--location <location>` | Emergency location ID or description to set |
| `--clear-location` | Clear the emergency location |
| `-n`, `--network-site <site>` | Network site ID to set |
| `--clear-network-site` | Clear the network site |
| `--dry-run` | Preview update without making changes |
| `-f`, `--force` | Skip confirmation prompt |

**Examples:**

```bash
# Update location
teams-phone numbers update +14255551234 --location "Seattle HQ"

# Clear location
teams-phone numbers update +14255551234 --clear-location

# Update network site
teams-phone numbers update +14255551234 --network-site "Site-001"

# Preview changes
teams-phone numbers update +14255551234 --location "NYC Office" --dry-run
```

### numbers bulk-assign

Bulk assign phone numbers from a CSV file.

```bash
teams-phone numbers bulk-assign <CSV_FILE> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `CSV_FILE` | Path to CSV file |

**CSV Format:**

```csv
user,phone_number,location
john@contoso.com,+14255551234,Seattle-HQ
jane@contoso.com,+14255555678,
```

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run` | Validate and preview without executing |
| `--continue-on-error` | Continue processing after individual failures |
| `--default-location <location>` | Default location for rows without one |
| `-o`, `--output <path>` | Path to write results CSV |
| `-y`, `--yes` | Skip confirmation prompt |

**Examples:**

```bash
# Preview bulk assignment
teams-phone numbers bulk-assign assignments.csv --dry-run

# Execute with default location
teams-phone numbers bulk-assign assignments.csv --default-location "Seattle-HQ"

# Continue on errors and save results
teams-phone numbers bulk-assign assignments.csv --continue-on-error -o results.csv
```

## Policies Commands

Manage voice policies and assignments.

### policies list

List available voice policies from CSV cache.

```bash
teams-phone policies list [POLICY_TYPE]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `POLICY_TYPE` | (Optional) Filter by type: `calling`, `voicemail`, `emergency`, `emergency-routing`, `caller-id`, `dial-plan`, `voice-routing` |

**Examples:**

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

# List calling policies
teams-phone policies list calling

# List emergency policies as JSON
teams-phone policies list emergency --json
```

### policies show

Show all policy assignments for a user.

```bash
teams-phone policies show <USER>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `USER` | User identifier: UPN, display name, or object ID |

**Examples:**

```bash
teams-phone policies show john.doe@contoso.com
teams-phone policies show "John Doe"
```

### policies assign

Assign a policy to a user.

```bash
teams-phone policies assign <USER> <POLICY_TYPE> <POLICY_NAME> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `USER` | User identifier: UPN, display name, or object ID |
| `POLICY_TYPE` | Policy type: `calling`, `voicemail`, `emergency`, `emergency-routing`, `caller-id`, `dial-plan`, `voice-routing` |
| `POLICY_NAME` | Name of the policy (use `Global` for default) |

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run` | Preview assignment without making changes |
| `-f`, `--force` | Skip confirmation prompt |

**Examples:**

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

# Preview emergency policy assignment
teams-phone policies assign "John Doe" emergency "High Priority" --dry-run

# Assign global dial plan
teams-phone policies assign john@contoso.com dial-plan Global --force
```

### policies bulk-assign

Bulk assign policies from a CSV file.

```bash
teams-phone policies bulk-assign <CSV_FILE> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `CSV_FILE` | Path to CSV file |

**CSV Format:**

```csv
user,policy_type,policy_name
john@contoso.com,calling,AllowCalling
jane@contoso.com,dial-plan,US-DialPlan
```

**Options:**

| Option | Description |
|--------|-------------|
| `--dry-run` | Validate and preview without executing |
| `--continue-on-error` | Continue processing after individual failures |
| `-o`, `--output <path>` | Path to write results CSV |
| `-y`, `--yes` | Skip confirmation prompt |

**Examples:**

```bash
# Preview bulk assignment
teams-phone policies bulk-assign assignments.csv --dry-run

# Execute bulk assignment
teams-phone policies bulk-assign assignments.csv

# Continue on errors
teams-phone policies bulk-assign assignments.csv --continue-on-error -o results.csv
```

## Locations Commands

Manage emergency locations (read from CSV cache).

### locations list

List emergency locations from CSV cache.

```bash
teams-phone locations list [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-c`, `--city <city>` | Filter by city |
| `-l`, `--limit <n>` | Limit results to n locations |
| `--all` | Fetch all locations (default behavior) |

**Examples:**

```bash
teams-phone locations list
teams-phone locations list --city Seattle
teams-phone locations list --json
```

### locations show

Show detailed information for a specific emergency location.

```bash
teams-phone locations show <LOCATION>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `LOCATION` | Location identifier: ID (GUID) or description |

**Examples:**

```bash
teams-phone locations show "Seattle HQ"
teams-phone locations show 12345678-1234-1234-1234-123456789012
```

### locations search

Search emergency locations by name, address, or city.

```bash
teams-phone locations search <QUERY> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `QUERY` | Search term (partial match, case-insensitive) |

**Options:**

| Option | Description |
|--------|-------------|
| `-f`, `--field <field>` | Limit search to: `name`, `address`, `city`, `company` |
| `-l`, `--limit <n>` | Maximum results (default: 25) |

**Examples:**

```bash
teams-phone locations search "Seattle"
teams-phone locations search "Main" --field name
```

## Tenants Commands

Manage tenant profiles in local configuration.

### tenants list

List all configured tenant profiles.

```bash
teams-phone tenants list
```

### tenants current

Show the currently active tenant.

```bash
teams-phone tenants current
```

### tenants switch

Switch to a different tenant profile.

```bash
teams-phone tenants switch <NAME>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NAME` | Tenant profile name |

**Examples:**

```bash
teams-phone tenants switch fabrikam
```

### tenants add

Add a new tenant profile.

```bash
teams-phone tenants add <NAME> <TENANT_ID> <CLIENT_ID> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NAME` | Profile name for the tenant |
| `TENANT_ID` | Microsoft Entra tenant ID (UUID) |
| `CLIENT_ID` | App registration client ID (UUID) |

**Options:**

| Option | Description |
|--------|-------------|
| `-d`, `--display-name <name>` | Human-readable display name (required) |
| `-a`, `--auth-method <method>` | Authentication method: `certificate`, `client-secret` (default: certificate) |
| `-c`, `--cert-path <path>` | Path to certificate file |
| `-l`, `--default-location <location>` | Default emergency location for number assignments |

**Examples:**

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

# Add tenant with client-secret auth
teams-phone tenants add fabrikam \
    "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" \
    "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" \
    --display-name "Fabrikam Inc" \
    --auth-method client-secret
```

### tenants remove

Remove a tenant profile.

```bash
teams-phone tenants remove <NAME>
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NAME` | Tenant profile name to remove |

### tenants test

Test connection to a tenant.

```bash
teams-phone tenants test [NAME]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `NAME` | (Optional) Tenant profile name (default: current tenant) |

## Auth Commands

Manage authentication tokens.

### auth status

Show current authentication status.

```bash
teams-phone auth status
```

### auth login

Authenticate with the current tenant.

```bash
teams-phone auth login [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-f`, `--force` | Force new authentication even if token exists |

### auth logout

Clear cached authentication tokens.

```bash
teams-phone auth logout
```

### auth refresh

Refresh cached authentication tokens.

```bash
teams-phone auth refresh
```

## API Check Command

Validate API contracts against live Graph API responses.

```bash
teams-phone api-check [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-e`, `--endpoint <endpoint>` | Check specific endpoint: `userConfigurations`, `numberAssignments` |
| `-V`, `--verbose` | Show detailed validation error output |

This command fetches sample data from Graph API and validates it against the CLI's Pydantic models. Useful for detecting API contract drift when Microsoft updates their API.

**Exit Codes:**

- `0` - All validations passed
- `8` - Contract validation failures detected

**Examples:**

```bash
# Check all endpoints
teams-phone api-check

# Check specific endpoint
teams-phone api-check --endpoint userConfigurations

# Show detailed errors
teams-phone api-check --verbose
```
