npm package: @papercraneai/cli
Description: CLI tool for managing OAuth credentials for LLM integrations
Latest version: 1.9.0

# papercrane

A CLI tool for managing OAuth credentials for LLM integrations.

## Features

- 🔐 Google OAuth 2.0 authentication using PKCE flow
- 💾 Secure credential storage in `~/.papercrane/google`
- 📋 List and manage stored credentials
- 🌐 Automatic browser-based authentication flow

## Installation

### Local Development

```bash
npm install
chmod +x bin/papercrane.js
npm link
```

### Global Installation

```bash
npm install -g papercrane
```

## Setup

Before using papercrane, you need to create OAuth 2.0 credentials in the Google Cloud Console:

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the APIs you want to access (e.g., Gmail API, Drive API, Calendar API)
4. Go to **APIs & Services** > **Credentials**
5. Click **Create Credentials** > **OAuth client ID**
6. Select **Desktop app** as the application type
7. Set the redirect URI to `http://127.0.0.1:8080/callback`
8. Save your **Client ID** and **Client Secret**

## Usage

### Authenticate with Google

```bash
papercrane google <scope1> [scope2] [...]
```

**Examples:**

```bash
# Authenticate for Gmail read-only access
papercrane google https://www.googleapis.com/auth/gmail.readonly

# Authenticate for multiple scopes
papercrane google https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/calendar.readonly

# Authenticate for Gmail and Drive
papercrane google https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/drive.file
```

The command will:
1. Prompt you for your Google OAuth Client ID and Client Secret
2. Generate PKCE credentials for secure authentication
3. Start a local server on port 8080
4. Open your browser to complete authentication
5. Store the credentials in `~/.papercrane/google/`

### List Stored Credentials

```bash
papercrane list
```

This shows all stored credentials including:
- File name and path
- Creation and expiration dates
- Token validity status
- Granted scopes
- Refresh token availability

### Help

```bash
papercrane help
papercrane --help
```

## Credential Storage

Credentials are stored as JSON files in:
```
~/.papercrane/google/credentials-<hash>.json
```

Each credential file contains:
- `access_token`: The OAuth access token
- `refresh_token`: The refresh token (if available)
- `expires_in`: Token lifetime in seconds
- `expires_at`: Absolute expiration timestamp
- `scope`: Granted OAuth scopes
- `token_type`: Token type (usually "Bearer")
- `created_at`: Creation timestamp

## Common OAuth Scopes

### Gmail
- `https://www.googleapis.com/auth/gmail.readonly` - Read-only access
- `https://www.googleapis.com/auth/gmail.compose` - Compose and send messages
- `https://www.googleapis.com/auth/gmail.modify` - Read, send, and modify emails

### Google Drive
- `https://www.googleapis.com/auth/drive.readonly` - Read-only access
- `https://www.googleapis.com/auth/drive.file` - Per-file access
- `https://www.googleapis.com/auth/drive` - Full access

### Google Calendar
- `https://www.googleapis.com/auth/calendar.readonly` - Read-only access
- `https://www.googleapis.com/auth/calendar` - Full access

See [Google OAuth 2.0 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) for a complete list.

## Security Considerations

- **PKCE Flow**: Uses Proof Key for Code Exchange for enhanced security
- **Local Storage**: Credentials are stored locally on your machine
- **Refresh Tokens**: Requested by default (`access_type=offline`) for long-term access
- **Localhost Only**: Callback server binds to `127.0.0.1` (localhost only)

## Development

### Project Structure

```
papercrane/
├── bin/
│   └── papercrane.js          # CLI entry point
├── lib/
│   ├── callback-server.js  # Local OAuth callback server
│   ├── google-auth.js      # Google OAuth flow implementation
│   ├── list-credentials.js # Credential listing
│   ├── pkce.js            # PKCE generation utilities
│   └── storage.js         # Credential storage management
├── package.json
└── README.md
```

### Technologies

- **Commander.js**: CLI framework
- **Axios**: HTTP client for token exchange
- **Chalk**: Terminal styling
- **Inquirer**: Interactive prompts
- **Open**: Cross-platform browser opening

## Troubleshooting

### Port 8080 already in use

If port 8080 is occupied, stop any processes using it or modify the `PORT` constant in `lib/google-auth.js`.

### Browser doesn't open automatically

Copy the authorization URL from the terminal and paste it into your browser manually.

### Invalid client error

Ensure your Client ID and Client Secret are correct and that the redirect URI `http://127.0.0.1:8080/callback` is registered in your Google Cloud Console OAuth credentials.

## License

MIT