Metadata-Version: 2.4
Name: otpilot
Version: 2.1.1
Summary: Background CLI utility that copies OTPs from Gmail to clipboard on hotkey trigger
Author: Jenil
Author-email: Jenil <mail2jenil.pokar19@gmail.com>
License: MIT License
        
        Copyright (c) 2026 OTPilot Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/CodeWithJenil/otpilot
Project-URL: Documentation, https://github.com/CodeWithJenil/otpilot/tree/main/docs
Project-URL: Repository, https://github.com/CodeWithJenil/otpilot
Project-URL: Issues, https://github.com/CodeWithJenil/otpilot/issues
Keywords: otp,gmail,clipboard,hotkey,automation,2fa
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-api-python-client>=2.100.0
Requires-Dist: google-auth>=2.23.0
Requires-Dist: pynput>=1.7.6
Requires-Dist: pystray>=0.19.5
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: plyer>=2.1.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: keyring>=24.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

![OTPilot Demo](assets/demo.gif)

# OTPilot

> Press a hotkey. Your OTP is already copied.
```bash
pip install otpilot
```

---

<p align="center">
  <strong>✈ OTPilot v2.1</strong>
</p>

<p align="center">
  <em>The new era of private OTP fetching. Background utility that copies OTPs from Gmail to your clipboard with a single hotkey.</em>
</p>

<p align="center">
  <a href="https://github.com/codewithjenil/otpilot">GitHub</a> •
  <a href="#installation">Install</a> •
  <a href="#quickstart">Quickstart</a> •
  <a href="SETUP.md">Supabase Auth Setup</a> •
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

---

## How It Works

1. **OTPilot sits silently in your system tray** — no polling loop, runs only when needed.
2. **Press your hotkey** (e.g. `Ctrl+Shift+O`) or run `otpilot fetch` — OTPilot fetches recent Gmail emails and extracts an OTP.
3. **OTP is copied to your clipboard** — and optionally auto-pasted. A desktop notification confirms the action.

## Installation

```bash
pip install otpilot
```

### Requirements

- **Python 3.8+**
- **Gmail account**
- **Supabase-backed auth endpoint** (default is OTPilot hosted auth)
- **OS**: macOS, Windows, or Linux

> **Linux users**: Make sure `xclip` or `xsel` is installed for clipboard support.
> ```bash
> sudo apt install xclip  # Debian/Ubuntu
> ```

## Quickstart

### 1. Configure Auth (if self-hosting)

For most users, no extra setup is required. OTPilot uses its hosted auth endpoint by default.

If you run your own OTPilot auth API, follow [SETUP.md](SETUP.md) and set `OTPILOT_AUTH_BASE_URL`.

### 2. Run Setup

```bash
otpilot setup
```

The wizard will:
- Open your browser for Supabase Google sign-in
- Request Gmail read-only access
- Let you set your preferred hotkey
- Configure copy/paste and scan preferences
- Save your configuration and token locally

### 3. Start OTPilot

```bash
otpilot start
```

OTPilot runs in the background with a system tray icon. Press your hotkey whenever you need an OTP.

### 4. Daily Use

1. Receive an OTP email in Gmail
2. Press your hotkey (default: `Ctrl+Shift+O`) or run `otpilot fetch`
3. Paste the OTP — done!

## Authentication Setup

OTPilot uses Supabase Auth for Google OAuth.

1. Hosted mode (default): run `otpilot setup`
2. Self-hosted mode: deploy the auth API and set `OTPILOT_AUTH_BASE_URL`
3. Complete browser auth and OTPilot stores your token locally

See [**SETUP.md**](SETUP.md) for full instructions.

## CLI Commands

| Command              | Description                              |
| -------------------- | ---------------------------------------- |
| `otpilot setup`      | Run or re-run the interactive setup      |
| `otpilot start`      | Start the background service             |
| `otpilot fetch`      | Trigger one OTP fetch immediately        |
| `otpilot status`     | Show auth state, hotkey, and config path |
| `otpilot hotkey`     | View or reconfigure the global hotkey    |
| `otpilot update`     | Check PyPI and upgrade via pip           |
| `otpilot version`    | Print the version number                 |

## Configuration

OTPilot stores its configuration at `~/.otpilot/config.json`:

```json
{
  "hotkey": "ctrl+shift+o",
  "notify_on_copy": true,
  "otp_max_age_minutes": 10,
  "email_fetch_count": 10,
  "auto_paste": false,
  "auto_start_on_boot": false,
  "notification_sound": false,
  "mask_otp_in_notification": true,
  "check_updates_on_start": true,
  "theme": "default",
  "setup_complete": false
}
```

| Field                      | Type    | Default          | Description                                    |
| -------------------------- | ------- | ---------------- | ---------------------------------------------- |
| `hotkey`                   | string  | `ctrl+shift+o`   | Global hotkey combination                      |
| `notify_on_copy`           | bool    | `true`           | Show desktop notification when OTP is copied   |
| `otp_max_age_minutes`      | int     | `10`             | Ignore emails older than this (minutes)        |
| `email_fetch_count`        | int     | `10`             | Number of recent emails to scan                |
| `auto_paste`               | bool    | `false`          | Auto-paste OTP after copying                   |
| `auto_start_on_boot`       | bool    | `false`          | Register OTPilot to start on login             |
| `notification_sound`       | bool    | `false`          | Reserved for future sound behavior             |
| `mask_otp_in_notification` | bool    | `true`           | Mask middle OTP digits in notifications        |
| `check_updates_on_start`   | bool    | `true`           | Check PyPI for updates on startup              |
| `theme`                    | string  | `default`        | Reserved for future UI themes                  |
| `setup_complete`           | bool    | `false`          | Indicates setup wizard completion              |

### Files Stored Locally

| File / Store                      | Purpose                              |
| --------------------------------- | ------------------------------------ |
| `~/.otpilot/config.json`          | Hotkey and runtime settings          |
| System keyring (`otpilot`)        | Preferred token storage              |
| `~/.otpilot/token.json`           | Fallback token storage               |

## Platform Support

| Platform | Status | Notes                                  |
| -------- | ------ | -------------------------------------- |
| macOS    | ✅     | Full support                           |
| Windows  | ✅     | Full support                           |
| Linux    | ✅     | Requires `xclip`/`xsel` for clipboard  |

## How OTP Extraction Works

OTPilot scans the subject line and body of your recent emails for:

- **4–8 digit standalone numbers** near context words like *OTP*, *code*, *verify*, *verification*, *one-time*, *passcode*, *authentication*
- Only emails within the configured time window are considered
- If multiple OTPs are found, subject matches are prioritized, then body matches

## Security & Privacy

- **OAuth via Supabase**: browser sign-in is handled through Supabase Auth + Google provider.
- **Read-only access**: OTPilot only reads your emails — it cannot send, delete, or modify anything.
- **Local storage only**: OAuth token is stored in system keyring when available, otherwise `~/.otpilot/token.json`.
- **On-demand fetching**: Emails are fetched only when triggered by hotkey or `otpilot fetch`.

## Troubleshooting

| Issue                             | Solution                                                       |
| --------------------------------- | -------------------------------------------------------------- |
| "Not authenticated" error         | Run `otpilot setup` to re-authenticate                         |
| No OTP found                      | Check `otp_max_age_minutes` — the email might be too old       |
| Clipboard not working (Linux)     | Install `xclip`: `sudo apt install xclip`                      |
| Hotkey not working                | Run `otpilot hotkey` or `otpilot setup`                        |
| Tray icon not visible             | Check your system tray / menu bar settings                     |
| Update notice appears repeatedly  | Run `otpilot update` or disable `check_updates_on_start`       |

## Contributing

Contributions are welcome! See [**CONTRIBUTING.md**](CONTRIBUTING.md) for guidelines on setting up the development environment, running tests, and submitting pull requests.

## License

[MIT](../LICENSE) — use it freely.
