# Installation

This guide covers installing and setting up the Teams Phone CLI.

## Prerequisites

### System Requirements

- **Python 3.10 or later** - Check with `python --version`
- **pip** - Python package manager (included with Python)
- **Microsoft Entra ID App Registration** - With appropriate permissions

### Azure/Microsoft Requirements

1. **Azure AD App Registration** with the following permissions (Application type, not Delegated):

   | Permission | Purpose |
   |------------|---------|
   | `TeamsUserConfiguration.Read.All` | Read user voice configuration |
   | `TeamsTelephoneNumber.Read.All` | Read phone number inventory |
   | `TeamsTelephoneNumber.ReadWrite.All` | Assign/unassign phone numbers |
   | `TeamsPolicyUserAssign.ReadWrite.All` | Assign policies to users |
   | `User.Read.All` | Read user profiles |
   | `Directory.Read.All` | Read tenant information |
   | `RoleManagement.Read.Directory` | Required as of Sept 2025 |
   | `GroupMember.Read.All` | Required as of Sept 2025 |

2. **Teams Administrator role** assigned to the app registration's service principal

3. **Certificate or client secret** for authentication (certificate recommended)

## Installation

### Install from PyPI

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

### Install from Source

```bash
git clone https://github.com/hvkc/teams-phone.git
cd teams-phone
pip install -e .
```

### Verify Installation

```bash
teams-phone --help
```

You should see the CLI help output listing available commands.

## Initial Setup

### 1. Create Configuration Directory

The CLI stores configuration in `~/.teams-phone/`:

```bash
# Linux/macOS
mkdir -p ~/.teams-phone

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:USERPROFILE\.teams-phone" -Force
```

### 2. Add Your First Tenant

Use the CLI to add a tenant profile:

```bash
# Certificate authentication (recommended)
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"

# Or client-secret authentication
teams-phone tenants add contoso \
    "12345678-1234-1234-1234-123456789012" \
    "87654321-4321-4321-4321-210987654321" \
    --display-name "Contoso Ltd" \
    --auth-method client-secret
```

Where:
- First argument is the profile name (e.g., `contoso`)
- Second argument is your Azure AD tenant ID (GUID)
- Third argument is your app registration client ID (GUID)

### 3. Set Up Client Secret (if using client-secret auth)

Store your client secret in an environment variable:

```bash
# Linux/macOS
export TEAMS_PHONE_CLIENT_SECRET="your-client-secret"

# Windows (PowerShell)
$env:TEAMS_PHONE_CLIENT_SECRET = "your-client-secret"

# Windows (Command Prompt)
set TEAMS_PHONE_CLIENT_SECRET=your-client-secret
```

Never store secrets directly in the configuration file.

### 4. Test the Connection

```bash
teams-phone tenants test
```

### 5. Authenticate

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

### 6. Export CSV Cache (Optional)

For locations and policies commands, you need to export data via PowerShell:

```powershell
# See scripts/README.md for full instructions
./scripts/Export-TeamsPhoneData.ps1 `
    -TenantId "12345678-1234-1234-1234-123456789012" `
    -ApplicationId "87654321-4321-4321-4321-210987654321" `
    -CertificateThumbprint "ABC123DEF456789..."
```

This creates CSV files in `~/.teams-phone/cache/` that the CLI uses for location and policy lookups.

## Certificate Setup

### Generate a Self-Signed Certificate (Development)

```bash
# Generate private key and certificate
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
    -subj "/CN=TeamsPhoneCLI"

# Combine into PFX for Windows (optional)
openssl pkcs12 -export -out TeamsPhoneCLI.pfx -inkey key.pem -in cert.pem
```

### Upload Certificate to Azure AD

1. Go to Azure Portal → App Registrations → Your App
2. Click "Certificates & secrets"
3. Click "Upload certificate"
4. Upload the `cert.pem` file (public key only)
5. Note the thumbprint displayed

### Configure CLI to Use Certificate

```bash
# Using certificate file path
teams-phone tenants add myorg "tenant-id" "client-id" \
    --display-name "My Organization" \
    --cert-path "/path/to/key.pem"
```

On Windows, you can also use a certificate installed in the certificate store by specifying the thumbprint in the config file.

## Next Steps

- [Configuration Guide](configuration.md) - Advanced configuration options
- [Command Reference](commands.md) - Full CLI command documentation
- [Troubleshooting](troubleshooting.md) - Common issues and solutions
