Skip to main content

OTPilot

PyPI version Python versions PyPI Downloads License: MIT

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 --copy to 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 launchd LaunchAgent
  • Linux: systemd --user service (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):

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 --copy are 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). When true, otpilot watch and otpilot daemon use the configured global hotkey instead of periodic polling. Set via otpilot config set hotkey_enabled true.
  • poll_interval_seconds — Watch polling interval in seconds (default: 3.0, range: >0 to 3600). Set via otpilot config set poll_interval_seconds 5.0.

Documentation

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.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for otpilot 3.2.0
File Size Uploaded Provenance Actions
otpilot-3.2.0.tar.gz 93.5 kB With provenance Details for otpilot-3.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for otpilot 3.2.0
File Interpreter ABI Platform Actions
otpilot-3.2.0-py3-none-any.whl Python 3 none any Details for otpilot-3.2.0-py3-none-any.whl

Total release size: 180.3 kB

Release files / otpilot-3.2.0.tar.gz

Download URL otpilot-3.2.0.tar.gz
Size 93.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5042cc2018d13e6bb42bd24e062580448ba68fef48cb95eeeb7a3917e793288b
BLAKE2b-256 checksum
How to use checksums
d1e22caaae45ee95c9d3ce2af108653184cf6b6a7a5997646dacf26ee632e028
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 11, 2026.

Transparency log

Release files / otpilot-3.2.0-py3-none-any.whl

Download URL otpilot-3.2.0-py3-none-any.whl
Size 86.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75e7571328d844029d77b6f24c7def3097398becf9189b115c385def7344e7b9
BLAKE2b-256 checksum
How to use checksums
9d98c8d7432a86240ea09c1cf6af6aa3719173b0e9a5fe37aa0217012138ff33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 11, 2026.

Transparency log

Security for otpilot 3.2.0

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.

Select from 2 files

Attestation for otpilot-3.2.0.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 11, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page