# Google Drive

## Install

```bash
pip install nexus-fs[gdrive]
```

This installs `google-api-python-client` and `google-auth-oauthlib`.

## Credential setup

Google Drive requires OAuth authentication. You need a Google Cloud
project with the Drive API enabled and OAuth 2.0 credentials.

### Step 1: Create OAuth credentials

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project (or select an existing one)
3. Enable the **Google Drive API**
4. Go to **APIs & Services > Credentials**
5. Create an **OAuth 2.0 Client ID** (type: Desktop app)
6. Note the **Client ID** and **Client Secret**

### Step 2: Set environment variables

```bash
export NEXUS_OAUTH_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export NEXUS_OAUTH_GOOGLE_CLIENT_SECRET="your-client-secret"
```

!!! warning
    Both environment variables are required. The OAuth flow will fail
    without them.

### Step 3: Connect your account

```bash
nexus-fs auth connect google-drive oauth --user-email you@example.com
```

This starts the OAuth flow:

1. Opens your browser to Google's consent screen
2. You authorize nexus-fs to access your Drive files
3. Tokens are encrypted and stored locally at `~/.nexus/`

### Step 4: Verify

```bash
nexus-fs auth test google-drive --user-email you@example.com
```

Or check everything at once:

```bash
nexus-fs doctor
```

### Disconnect

To remove stored credentials:

```bash
nexus-fs auth disconnect google-drive
```

## Mount

```python
# skip-test
import nexus.fs

fs = nexus.fs.mount_sync("gdrive://my-drive")
```

## Common patterns

### List files in Drive

```python
# skip-test
import nexus.fs

fs = nexus.fs.mount_sync("gdrive://my-drive")

# List root
files = fs.ls("/gdrive/my-drive/")
for f in files:
    print(f)
```

### Read a file

```python
# skip-test
import nexus.fs

fs = nexus.fs.mount_sync("gdrive://my-drive")

content = fs.read("/gdrive/my-drive/notes.txt")
print(content.decode())
```

### Write a file

```python
# skip-test
import nexus.fs

fs = nexus.fs.mount_sync("gdrive://my-drive")

fs.write("/gdrive/my-drive/output.txt", b"Generated by nexus-fs")
```

## Auth commands reference

| Command | Description |
|---------|-------------|
| `nexus-fs auth connect google-drive oauth --user-email EMAIL` | Start OAuth flow |
| `nexus-fs auth test google-drive --user-email EMAIL` | Validate stored credentials |
| `nexus-fs auth disconnect google-drive` | Remove stored credentials |
| `nexus-fs auth list` | List all configured services |
| `nexus-fs auth doctor` | Auth-specific diagnostics |

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NEXUS_OAUTH_GOOGLE_CLIENT_ID` | Yes | Google OAuth 2.0 Client ID |
| `NEXUS_OAUTH_GOOGLE_CLIENT_SECRET` | Yes | Google OAuth 2.0 Client Secret |

See also the [nexus-fs doctor](../cli/doctor.md) for diagnostic output.
