Skip to main content

OTPilot

OTPilot is a local-first CLI application for fetching one-time passwords from email accounts.

The first supported provider target is Gmail via IMAP over SSL with Google App Passwords. The architecture is intentionally not Gmail-specific: Gmail is a provider configuration layered on a generic IMAP transport so Outlook, Yahoo, Proton Bridge, and custom IMAP servers can be added without changing the CLI or application services.

OTPilot is available on PyPI:

pip install otpilot

Platform Support

OTPilot supports cross-platform execution on:

  • Windows
  • macOS
  • Linux X11 (Wayland is unsupported)

Product Principles

  • Local only: no server, hosted API, relay, sync service, or cloud dependency.
  • Telemetry is optional and opt-in: OTPilot does not collect usage, diagnostics, crash reports, or analytics unless you explicitly enable it with otpilot telemetry enable. Telemetry is disabled by default.
  • No OAuth: email access uses IMAP over SSL and provider-specific app passwords.
  • Secure credentials: passwords are stored in the operating system credential vault via keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service), never in config files.
  • Documentation first: public behavior is incomplete unless docs are updated with code.

Current Status

Version 3.0.0 features credential-backed Gmail IMAP fetching, candidate-based OTP extraction, optional clipboard copying via otpilot fetch --copy (which copies the OTP to the clipboard without printing it to terminal output), synchronous polling watch mode, and cross-platform global hotkey support.

CLI

otpilot fetch
otpilot fetch --copy
otpilot watch
otpilot hotkey
otpilot login user@gmail.com
otpilot logout user@gmail.com
otpilot config
otpilot doctor
otpilot version
otpilot telemetry status
otpilot telemetry enable
otpilot telemetry disable

See docs/cli-reference.md for command behavior and documentation details.

Global Hotkey

otpilot hotkey registers a system-wide hotkey using a cross-platform pynput adapter so it works while another application has focus:

  • Windows & Linux (X11): Ctrl+Shift+O by default.
  • macOS: Cmd+Shift+O or Ctrl+Shift+O by default.

Configure another supported combination in OTPilot's non-secret TOML configuration file, for example:

hotkey = "cmd+shift+o"

Note: On macOS, Accessibility permissions are required for hotkey capturing. On Linux, only X11 display servers are supported (Wayland is unsupported).

Press Ctrl+C to unregister the hotkey and exit. Each invocation copies the OTP to the clipboard; OTPilot never prints it in hotkey mode and does not paste it automatically.

Privacy Guarantee (fetch --copy)

When using otpilot fetch --copy or running in hotkey mode, OTPilot copies the extracted OTP directly to your system clipboard without printing the value to terminal output.

Architecture

OTPilot is layered:

CLI
Application Services
Domain
Providers
Infrastructure

The provider architecture is:

OTP Source
  -> IMAP Provider
      -> Gmail
      -> Outlook
      -> Yahoo
      -> Custom IMAP

See architecture.md for the complete architecture, dependency graph, and design decisions.

Documentation

Development

python -m pip install -e ".[dev]"
pytest
ruff check .
mypy src/otpilot

License

MIT.

Metadata

Release files for otpilot 3.1.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.1.0
File Size Uploaded Provenance Actions
otpilot-3.1.0.tar.gz 68.9 kB With provenance Details for otpilot-3.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 135.1 kB

Release files / otpilot-3.1.0.tar.gz

Download URL otpilot-3.1.0.tar.gz
Size 68.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e11356a66f73f8015c50bd540222f7f0664ce22624055a49c5392555314f869e
BLAKE2b-256 checksum
How to use checksums
4e9a357d2406637ac196b00adacc495a6aab5828b2b07a5535dd257ac741aea7
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 Sep 27, 2026.

Transparency log

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

Download URL otpilot-3.1.0-py3-none-any.whl
Size 66.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0a9a8b7ebad1f1623555d459e774b444aedf5a00927fa99846b9142ee1b7adf7
BLAKE2b-256 checksum
How to use checksums
637dc98fd4ac62d792e053f4a1faf727f81e8f088da8778b8d793ba7edede445
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 Sep 27, 2026.

Transparency log

Security for otpilot 3.1.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.1.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 Sep 27, 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