> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client

> Initialize and configure the TapKit client

The `TapKitClient` is your main entry point for interacting with TapKit. It handles authentication, connection management, and provides access to your phones.

## Basic Usage

```python theme={null}
from tapkit import TapKitClient

# Initialize with API key
client = TapKitClient(api_key="your-api-key")

# Or use environment variable TAPKIT_API_KEY
client = TapKitClient()
```

## Configuration Options

```python theme={null}
client = TapKitClient(
    api_key="your-api-key",  # Your TapKit API key
    timeout=65.0              # Request timeout in seconds (default: 65)
)
```

| Parameter | Type          | Default | Description                                          |
| --------- | ------------- | ------- | ---------------------------------------------------- |
| `api_key` | `str \| None` | `None`  | Your API key. Falls back to `TAPKIT_API_KEY` env var |
| `timeout` | `float`       | `65.0`  | Request timeout in seconds                           |

## Context Manager

Use the client as a context manager for automatic cleanup:

```python theme={null}
with TapKitClient() as client:
    phone = client.get_phone()
    phone.tap(phone.screen.center)
# Connection automatically closed
```

Or manually close when done:

```python theme={null}
client = TapKitClient()
try:
    phone = client.get_phone()
    phone.tap(phone.screen.center)
finally:
    client.close()
```

## System Status

Check the overall system status:

```python theme={null}
status = client.status()

print(f"Mac app running: {status.mac_app_running}")
print(f"Phone connected: {status.phone_connected}")
print(f"Phone name: {status.phone_name}")
print(f"Switch Control enabled: {status.switch_control_enabled}")
print(f"Screen locked: {status.screen_locked}")
print(f"Streaming: {status.streaming}")
```

### Status Fields

| Field                    | Type          | Description                              |
| ------------------------ | ------------- | ---------------------------------------- |
| `mac_app_running`        | `bool`        | Whether the Mac companion app is running |
| `phone_connected`        | `bool`        | Whether a phone is connected             |
| `phone_name`             | `str \| None` | Name of the connected phone              |
| `switch_control_enabled` | `bool`        | Whether Switch Control is enabled        |
| `screen_locked`          | `bool`        | Whether the device screen is locked      |
| `streaming`              | `bool`        | Whether screen streaming is active       |

## Client-Level Actions

You can execute actions directly on the client when you've set a default phone:

```python theme={null}
client = TapKitClient()

# Set a default phone
client.use_phone("iPhone 15 Pro")

# Now call actions directly on client
client.tap((100, 200))
client.home()
screenshot = client.screenshot()
```

This is convenient when working with a single phone throughout your script.

## Error Handling

The SDK raises `TapKitError` for API errors:

```python theme={null}
from tapkit import TapKitClient, TapKitError

try:
    client = TapKitClient(api_key="invalid-key")
    phone = client.get_phone()
except TapKitError as e:
    print(f"TapKit error: {e}")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Managing Phones" icon="mobile" href="/sdk/phones">
    Learn how to list and select phones
  </Card>

  <Card title="Screenshots" icon="camera" href="/sdk/screenshots">
    Capture screenshots from your phone
  </Card>
</CardGroup>