# Command Group 1: Users

Manage and query user voice configurations.

### `users list`

List users with voice-related configuration fields and filtering (includes licensed/unlicensed and assigned/unassigned).

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

**Options:**
| Option | Description |
|--------|-------------|
| `--licensed` | Show only users with Teams Phone license |
| `--unlicensed` | Show only users without Teams Phone license |
| `--assigned` | Show only users with phone numbers assigned |
| `--unassigned` | Show only users without phone numbers |
| `--account-type <type>` | Filter by account type: `user`, `resource-account`, `guest` |
| `--limit <n>` | Limit results to n users (default: 50) |
| `--all` | Fetch all users (may be slow for large tenants) |

**Validation:**
- If both `--licensed` and `--unlicensed` are provided → error: "Cannot specify both --licensed and --unlicensed"
- If both `--assigned` and `--unassigned` are provided → error: "Cannot specify both --assigned and --unassigned"
- If both `--limit` and `--all` are provided → error: "Cannot specify both --limit and --all"

**Output Fields:**
- Display Name
- UPN (User Principal Name)
- Account Type (User/Resource Account/Guest)
- Phone Number (or "—" if none)
- License Status (Licensed/Unlicensed)
- Voice Enabled (Yes/No)
- Location

**Example:**
```bash
# List first 50 users (default limit)
teams-phone users list

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

# Output as JSON for scripting
teams-phone users list --json
```

---

### `users show <user>`

Show detailed voice configuration for a specific user.

```
teams-phone users show <user> [OPTIONS]
```

**Arguments:**
| Argument | Description |
|----------|-------------|
| `<user>` | User identifier: UPN, display name, or object ID |

**Resolution Behavior:**
- UPN (contains @): Exact match required
- Object ID (UUID format): Exact match required
- Display name: Partial match; if multiple matches found, error with candidate list

**Output Sections:**
1. **Identity**: Display name, UPN, Object ID, Account Type, Department, Location
2. **Licensing**: Teams Phone license status, license SKU
3. **Phone Number**: Assigned number, number type, assignment date
4. **Voice Policies**:
   - Calling Policy
   - Voicemail Policy
   - Emergency Calling Policy
   - Emergency Call Routing Policy
   - Caller ID Policy
   - Dial Plan
   - Voice Routing Policy (if Direct Routing)
5. **Voice Status**: Enterprise Voice enabled, Hosted Voicemail enabled

**Example:**
```bash
# Show user by UPN
teams-phone users show john.doe@contoso.com

# Show user by display name
teams-phone users show "John Doe"

# Show user with verbose API details
teams-phone users show john.doe@contoso.com --verbose
```

---

### `users search <query>`

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

```
teams-phone users search <query> [OPTIONS]
```

**Arguments:**
| Argument | Description |
|----------|-------------|
| `<query>` | Search term (partial match supported) |

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

**Example:**
```bash
# Search by partial name
teams-phone users search "john"

# Search by phone number ending
teams-phone users search "5678" --field phone

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

---

