# Configuration

The Teams Phone CLI uses a TOML configuration file and environment variables for settings.

## Configuration File Location

```
~/.teams-phone/config.toml
```

On Windows: `%USERPROFILE%\.teams-phone\config.toml`

## Configuration File Structure

```toml
[default]
tenant = "contoso"           # Default tenant profile name
output_format = "table"      # Default output format: table or json
color = true                 # Enable colored output

[cache]
users_ttl = 300              # User cache TTL in seconds (5 min)
numbers_ttl = 300            # Numbers cache TTL in seconds (5 min)
policies_ttl = 600           # Policies cache TTL in seconds (10 min)
tenant_ttl = 3600            # Tenant info cache TTL in seconds (1 hour)

[tenants.contoso]
tenant_id = "12345678-1234-1234-1234-123456789012"
client_id = "87654321-4321-4321-4321-210987654321"
display_name = "Contoso Ltd"
auth_method = "certificate"                    # certificate or client-secret
cert_path = "/path/to/certificate.pem"         # Path to private key/certificate
default_location = "Seattle-HQ"                # Default E911 location for number assignments

[tenants.fabrikam]
tenant_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
client_id = "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
display_name = "Fabrikam Inc"
auth_method = "client-secret"
# Secret stored in TEAMS_PHONE_CLIENT_SECRET environment variable
default_location = "NYC-Main"
```

## Tenant Profile Settings

Each tenant profile supports the following settings:

| Setting | Required | Description |
|---------|----------|-------------|
| `tenant_id` | Yes | Microsoft Entra (Azure AD) tenant ID (GUID) |
| `client_id` | Yes | App registration client ID (GUID) |
| `display_name` | Yes | Human-readable name for the tenant |
| `auth_method` | No | `certificate` (default) or `client-secret` |
| `cert_path` | No | Path to certificate file (for certificate auth) |
| `cert_thumbprint` | No | Certificate thumbprint (Windows cert store) |
| `default_location` | No | Default emergency location for number assignments |

## Authentication Methods

### Certificate Authentication (Recommended)

Certificate authentication is more secure than client secrets and is recommended for production use.

```toml
[tenants.myorg]
tenant_id = "..."
client_id = "..."
display_name = "My Organization"
auth_method = "certificate"
cert_path = "/path/to/private-key.pem"
```

The `cert_path` should point to a PEM file containing the private key.

#### Windows Certificate Store

On Windows, you can use a certificate installed in the current user's certificate store:

```toml
[tenants.myorg]
tenant_id = "..."
client_id = "..."
display_name = "My Organization"
auth_method = "certificate"
cert_thumbprint = "ABC123DEF456789..."
```

The certificate must be in `Cert:\CurrentUser\My` with the private key accessible.

### Client Secret Authentication

Client secrets are simpler to set up but less secure. The secret should never be stored in the config file.

```toml
[tenants.myorg]
tenant_id = "..."
client_id = "..."
display_name = "My Organization"
auth_method = "client-secret"
# No secret in config - uses TEAMS_PHONE_CLIENT_SECRET env var
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `TEAMS_PHONE_CLIENT_SECRET` | Client secret for client-secret authentication |
| `TEAMS_PHONE_CONFIG_PATH` | Override config file location |
| `TEAMS_PHONE_CACHE_PATH` | Override cache directory location |
| `NO_COLOR` | Disable colored output (standard env var) |

## Cache Directory

The CLI caches data in `~/.teams-phone/cache/`:

```
~/.teams-phone/cache/
├── locations.csv           # Emergency locations (from PowerShell export)
├── policies.csv            # Voice policies (from PowerShell export)
└── export-metadata.json    # Export timestamp and counts
```

### CSV Cache for Locations and Policies

The Graph API doesn't provide read access to all location and policy data, so the CLI uses CSV files exported via PowerShell. See [scripts/README.md](../scripts/README.md) for export instructions.

The CLI warns if CSV files are older than 30 days. Re-export periodically or after making changes in Teams Admin Center.

## Managing Tenants

### Add a New Tenant

```bash
teams-phone tenants add <name> <tenant-id> <client-id> \
    --display-name "Display Name" \
    --cert-path "/path/to/cert.pem"
```

### List Configured Tenants

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

### Switch Active Tenant

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

### Remove a Tenant

```bash
teams-phone tenants remove fabrikam
```

### Test Tenant Connection

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

## Global Options

Override configuration settings on any command:

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

Example:

```bash
# Use fabrikam tenant for this command only
teams-phone -t fabrikam users list

# Output as JSON
teams-phone users list --json

# Enable verbose output
teams-phone numbers assign user@example.com +14255551234 --verbose
```

## Example Configurations

### Single Tenant

```toml
[default]
tenant = "myorg"

[tenants.myorg]
tenant_id = "12345678-1234-1234-1234-123456789012"
client_id = "87654321-4321-4321-4321-210987654321"
display_name = "My Organization"
auth_method = "certificate"
cert_path = "~/.teams-phone/certs/myorg.pem"
default_location = "Main-Office"
```

### Multiple Tenants (MSP/Consultant)

```toml
[default]
tenant = "client-a"
output_format = "table"
color = true

[tenants.client-a]
tenant_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
client_id = "11111111-1111-1111-1111-111111111111"
display_name = "Client A Corporation"
auth_method = "certificate"
cert_path = "~/.teams-phone/certs/client-a.pem"

[tenants.client-b]
tenant_id = "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"
client_id = "22222222-2222-2222-2222-222222222222"
display_name = "Client B Inc"
auth_method = "certificate"
cert_path = "~/.teams-phone/certs/client-b.pem"

[tenants.client-c]
tenant_id = "cccccccc-cccc-cccc-cccc-cccccccccccc"
client_id = "33333333-3333-3333-3333-333333333333"
display_name = "Client C LLC"
auth_method = "client-secret"
```
