OTPilot
Retrieve email OTPs from your terminal and copy them to your clipboard—without manually searching your inbox.
OTPilot is a local-first command-line tool for retrieving one-time passwords from Gmail over IMAP. Use it when you want a simpler workflow for email-based verification codes.
- Clipboard support: use
otpilot fetch --copyto copy the detected OTP without printing its value to terminal output. - Local-first design: email retrieval happens on your machine; OTPilot does not require a hosted relay or sync service.
- Opt-in telemetry: usage telemetry is disabled by default and is sent only if you explicitly enable it.
- Credential storage: credentials are stored through your operating system's credential vault rather than in the TOML configuration file.
- Cross-platform CLI: Windows, macOS, and Linux with X11 are supported. Linux Wayland is not currently supported.
- Background daemon: persistent OTP polling via
otpilot daemon(Windows, macOS, Linux). - Community messages: occasional randomized links to feedback, issues, and discussions (configurable).
Get started
1. Install
Requires Python 3.12 or newer.
python -m pip install --upgrade otpilot
2. Configure Gmail access
OTPilot currently supports Gmail through IMAP over SSL and a Google App Password. Enable IMAP for your Gmail account and create an App Password if your Google account is eligible. Never share your App Password or commit it to a repository.
3. Sign in and fetch
otpilot login you@gmail.com
otpilot fetch --copy
Follow the prompts shown by the CLI. The fetch --copy command copies the detected OTP to your clipboard when a suitable code is found.
Common commands
| Command | Purpose |
|---|---|
otpilot login |
Configure an email account (interactive prompts for email and App Password) |
otpilot fetch |
Fetch and identify OTP candidates |
otpilot fetch --copy |
Copy the selected OTP to the clipboard without printing the value |
otpilot watch |
Unified monitoring for new OTP messages. Mode determined by hotkey_enabled config |
otpilot config |
View or edit preferences |
otpilot doctor |
Diagnose common setup issues |
otpilot telemetry status |
Check telemetry status |
otpilot telemetry enable |
Explicitly enable optional telemetry |
otpilot telemetry disable |
Disable telemetry |
otpilot logout <account> |
Remove saved account credentials |
otpilot daemon start |
Start background OTP daemon |
otpilot daemon stop |
Stop background OTP daemon |
otpilot daemon status |
Check daemon status |
otpilot daemon install |
Install daemon service |
otpilot daemon enable-autostart |
Enable daemon on login |
Run otpilot --help or consult the CLI reference for details.
Background daemon
The otpilot daemon command manages a persistent background service that polls for new OTPs and copies them to the clipboard, similar to otpilot watch but running independently of your terminal session.
# Install and start the daemon
otpilot daemon install
otpilot daemon start
# Enable autostart on login
otpilot daemon enable-autostart
# Check status
otpilot daemon status
# Stop and uninstall
otpilot daemon stop
otpilot daemon uninstall
Platform implementations:
- Windows: Background process with PID file, optional Registry autostart
- macOS: Per-user
launchdLaunchAgent - Linux:
systemd --userservice (preferred) or background process fallback
The daemon reuses your existing configuration and credentials. Run otpilot doctor to diagnose daemon status.
Community messages
After successful interactive commands, OTPilot may occasionally display a randomized community message (default 15% probability):
- Review — "Enjoying OTPilot? Share your review: https://jenil-otpilot.vercel.app/feedback"
- Issues — "Found a bug or issue? Report it here: https://github.com/CodeWithJenil/otpilot3.0/issues"
- Discussions — "Have an idea or question? Join the discussion: https://github.com/CodeWithJenil/otpilot3.0/discussions"
This is a lightweight, offline feature. Configure or disable via:
otpilot config set preferences.community_messages_enabled false
otpilot config set preferences.community_message_probability 0.05
Platform notes
- Windows: supported.
- macOS: supported; Accessibility permission may be required for global hotkey capture.
- Linux: X11 is supported; Wayland is not currently supported.
Hotkey combinations can be configured in OTPilot's non-secret TOML configuration file. See the configuration guide.
Privacy and security
OTPilot is designed to keep email retrieval local and credentials out of plain-text configuration files.
- Credentials use the operating system credential vault through
keyring(macOS Keychain, Windows Credential Manager, or a supported Linux Secret Service backend). - OTP values copied with
fetch --copyare not printed to terminal output by that command. - Telemetry is off by default. You can inspect its status and enable or disable it with the commands above.
- Community messages make no network requests and collect no data.
- Feedback submissions are optional and use the existing website form.
- Review the privacy policy and security guidance before use.
As with any tool that accesses email, review the permissions you grant and protect your account credentials.
How it works
OTPilot is organized into layers that separate the CLI, application services, domain logic, providers, and infrastructure. Its current email provider is Gmail over IMAP. Other IMAP providers are architectural possibilities, not currently advertised as supported providers.
See architecture.md for the design and developer-guide.md for the development workflow.
Configuration
hotkey_enabled— Enable hotkey-based monitoring (default:false). Whentrue,otpilot watchandotpilot daemonuse the configured global hotkey instead of periodic polling. Set viaotpilot config set hotkey_enabled true.poll_interval_seconds— Watch polling interval in seconds (default:3.0, range:>0to3600). Set viaotpilot config set poll_interval_seconds 5.0.
Documentation
- Installation and development setup
- CLI reference
- Configuration
- Troubleshooting
- Architecture
- Security
- Privacy
- Contributing
- Roadmap
- Changelog
Contributing
Issues, bug reports, and thoughtful contributions are welcome. Please read contributing.md before opening a pull request. When reporting an issue, include your OS, Python version, OTPilot version, and the command involved—never include OTPs, passwords, App Passwords, or private email content.
License
OTPilot is released under the MIT License.
Metadata
Release files for otpilot 3.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| otpilot-3.2.1.tar.gz | 94.7 kB | With provenance | Details for otpilot-3.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| otpilot-3.2.1-py3-none-any.whl | Python 3 | none | any | Details for otpilot-3.2.1-py3-none-any.whl |
Total release size: 181.7 kB
Release files / otpilot-3.2.1.tar.gz
| Download URL | otpilot-3.2.1.tar.gz |
|---|---|
| Size | 94.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ff532b95b089ca914f8cb800182dad9a58a6196adc2f8cd3f96de19a235b1513
|
|
BLAKE2b-256 checksum How to use checksums |
7336a8b908749879f1f960b8399f3729a56862e1150da311e825dc06b2137481
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logRelease files / otpilot-3.2.1-py3-none-any.whl
| Download URL | otpilot-3.2.1-py3-none-any.whl |
|---|---|
| Size | 87.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0dd746c569a6a6b78bb580dca0f3699c3a31671b190e99a97b8b60e1eacedca2
|
|
BLAKE2b-256 checksum How to use checksums |
e49999b3290ceabdfa3cc22830baf05d982d1af6b52753f072543d29dfbec34c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logSecurity for otpilot 3.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for otpilot-3.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.