### Install oathtool via pip, pipx, or source

Source: https://context7.com/jaraco/oathtool/llms.txt

Provides instructions for installing the oathtool library using different package management methods. Users can choose to install from PyPI using `pip`, create an isolated CLI tool with `pipx`, or install directly from a local source clone after cloning the repository.

```bash
# Install from PyPI
pip install oathtool

# Install with pipx for isolated CLI tool
pipx install oathtool

# Install from source
git clone https://github.com/jaraco/oathtool.git
cd oathtool
pip install -e .
```

--------------------------------

### Install oathtool with pipx

Source: https://github.com/jaraco/oathtool/blob/main/README.rst

Installs the oathtool package globally using pipx, making the command-line tool readily available. After installation, the oathtool command can be used directly with a secret key.

```bash
pipx install oathtool
oathtool $key
```

--------------------------------

### Run oathtool script with pip-run

Source: https://github.com/jaraco/oathtool/blob/main/README.rst

Executes the oathtool generate-script module using pip-run, which allows running Python packages without explicit installation. This is useful for quick, temporary usage or testing.

```bash
pip-run oathtool -- -m oathtool.generate-script
./oathtool $key
```

--------------------------------

### Create standalone oathtool script

Source: https://github.com/jaraco/oathtool/blob/main/README.rst

Generates a standalone Unix script for oathtool, allowing OTP generation without needing to install the package system-wide. The script can be placed in a desired location using a target path.

```bash
python -m oathtool.generate-script
./oathtool $key
```

```bash
python -m oathtool.generate-script ~/bin/my-oathtool
```

--------------------------------

### Verify TOTP with Time Window Tolerance

Source: https://context7.com/jaraco/oathtool/llms.txt

Demonstrates an integration example for verifying TOTP codes within a time window using `oathtool.generate_otp`. The `verify_totp` function checks the user-provided code against expected codes generated for the current and adjacent 30-second intervals, returning `True` if a match is found within the specified `window`.

```python
import oathtool
import time

def verify_totp(user_provided_code, secret_key, window=1):
    """
    Verify TOTP code with time window tolerance.

    Args:
        user_provided_code: 6-digit code from user
        secret_key: Base32-encoded secret
        window: Number of 30-second windows to check (±window)

    Returns:
        True if code matches within window, False otherwise
    """
    current_time = int(time.time() / 30)

    for offset in range(-window, window + 1):
        test_hotp = current_time + offset
        expected_code = oathtool.generate_otp(secret_key, hotp_value=test_hotp)
        if user_provided_code == expected_code:
            return True
    return False

# Usage in login flow
user_key = 'JBSWY3DPEHPK3PXP'
user_input = '123456'
if verify_totp(user_input, user_key, window=1):
    print("Authentication successful")
else:
    print("Invalid code")
```

--------------------------------

### Generate OTP using oathtool command-line

Source: https://github.com/jaraco/oathtool/blob/main/README.rst

Generates a One-Time Password (OTP) using the oathtool module from the command line. Requires a secret key as input. This is a direct way to get an OTP without importing the module into a script.

```bash
python -m oathtool $key
```

--------------------------------

### Command-line Interface

Source: https://context7.com/jaraco/oathtool/llms.txt

Execute the oathtool module or installed script to generate TOTP codes from the command line. Accepts the secret key as a command-line argument or via stdin for secure input. Prints the 6-digit code to stdout.

```APIDOC
## Command-line Interface

### Description
Execute the oathtool module or installed script to generate TOTP codes from the command line. Accepts the secret key as a command-line argument or via stdin for secure input. Prints the 6-digit code to stdout.

### Method
`python -m oathtool <secret_key>` or `oathtool <secret_key>`

### Endpoint
Command Line

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **secret_key** (str) - Required - The base32-encoded secret key provided as a command-line argument or via stdin.

### Request Example
```bash
# Direct module execution with key argument
python -m oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Using installed script
oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Secure input via stdin (avoids shell history)
echo 'MZXW6YTBOJUWU23MNU' | python -m oathtool
# Output: 487656

# Using with pipx for isolated installation
pipx install oathtool
oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Error handling - no arguments provided
python -m oathtool
# Output: provide secret key as only arg or via stdin
# Exit code: 1
```

### Response
#### Success Response (200)
- **output** (str) - The generated 6-digit TOTP printed to stdout.

#### Response Example
```
487656
```
```

--------------------------------

### Create Standalone Executable Script (Command-line)

Source: https://context7.com/jaraco/oathtool/llms.txt

Generates a self-contained Python script that can generate TOTP codes without requiring the oathtool package installation. The script is marked executable and includes a shebang for direct execution on Unix-like systems.

```bash
# Generate default 'oathtool' script in current directory
python -m oathtool.generate-script
# Creates: ./oathtool (executable)

# Run the generated standalone script
./oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Generate script at custom location
python -m oathtool.generate-script ~/bin/my-oathtool
# Creates: ~/bin/my-oathtool (executable)

# Generate without installing oathtool using pip-run
pip-run oathtool -- -m oathtool.generate-script
./oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Use generated script with stdin for secure input
echo 'MZXW6YTBOJUWU23MNU' | ./oathtool
# Output: 487656
```

--------------------------------

### Generate OTP from Terminal (Command-line)

Source: https://context7.com/jaraco/oathtool/llms.txt

Execute the oathtool module or installed script to generate TOTP codes from the command line. Accepts the secret key as an argument or via stdin. Prints the 6-digit code to stdout and includes error handling for missing arguments.

```bash
# Direct module execution with key argument
python -m oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Using installed script
oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Secure input via stdin (avoids shell history)
echo 'MZXW6YTBOJUWU23MNU' | python -m oathtool
# Output: 487656

# Using with pipx for isolated installation
pipx install oathtool
oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Error handling - no arguments provided
python -m oathtool
# Output: provide secret key as only arg or via stdin
# Exit code: 1
```

--------------------------------

### Python API - generate-script

Source: https://context7.com/jaraco/oathtool/llms.txt

Generates a self-contained Python script that includes all necessary code to generate TOTP codes without requiring the oathtool package to be installed. The script is marked executable and includes a shebang for direct execution on Unix-like systems.

```APIDOC
## Python API - generate-script

### Description
Generates a self-contained Python script that includes all necessary code to generate TOTP codes without requiring the oathtool package to be installed. The script is marked executable and includes a shebang for direct execution on Unix-like systems.

### Method
`python -m oathtool.generate-script [output_path]`

### Endpoint
Module Execution

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **output_path** (str) - Optional - The path where the generated executable script will be saved. Defaults to `./oathtool` in the current directory.

### Request Example
```bash
# Generate default 'oathtool' script in current directory
python -m oathtool.generate-script
# Creates: ./oathtool (executable)

# Run the generated standalone script
./oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Generate script at custom location
python -m oathtool.generate-script ~/bin/my-oathtool
# Creates: ~/bin/my-oathtool (executable)

# Generate without installing oathtool using pip-run
pip-run oathtool -- -m oathtool.generate-script
./oathtool MZXW6YTBOJUWU23MNU
# Output: 487656

# Use generated script with stdin for secure input
echo 'MZXW6YTBOJUWU23MNU' | ./oathtool
# Output: 487656
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation that the script was generated successfully.

#### Response Example
```
Standalone script 'oathtool' generated successfully.
```
```

--------------------------------

### Main Entry Point with oathtool.main

Source: https://context7.com/jaraco/oathtool/llms.txt

Shows programmatic invocation of the `oathtool.main` function, simulating command-line usage for OTP generation. It covers scenarios with and without command-line arguments, demonstrating how the function reads keys from stdin or arguments and handles errors when no key is provided, exiting with code 1.

```python
import sys
import oathtool

# Programmatic invocation (simulating CLI usage)
original_argv = sys.argv.copy()
sys.argv = ['oathtool', 'MZXW6YTBOJUWU23MNU']
try:
    oathtool.main()
    # Output: 487656 (printed to stdout, varies with time)
except SystemExit:
    pass
finally:
    sys.argv = original_argv

# Error handling - no arguments
sys.argv = ['oathtool']
try:
    oathtool.main()
except SystemExit as e:
    print(f"Exit code: {e.code}")  # Output: Exit code: 1
    # Also prints: provide secret key as only arg or via stdin
finally:
    sys.argv = original_argv
```

--------------------------------

### Pad Base32 Keys with oathtool.pad

Source: https://context7.com/jaraco/oathtool/llms.txt

Demonstrates padding Base32 encoded keys using the `oathtool.pad` function. This function ensures keys meet the required length for OTP generation, including handling keys that are already correctly sized or require custom padding lengths. It accepts the key string and an optional `size` parameter.

```python
import oathtool

# Pad standard base32 key
key = 'MZXW6YTBOJUWU23MNU'
padded = oathtool.pad(key)
print(padded)  # Output: MZXW6YTBOJUWU23MNU======

# Already properly sized input (no padding needed)
complete = 'ABCDEFGH'
padded = oathtool.pad(complete)
print(padded)  # Output: ABCDEFGH

# Custom padding size
padded_16 = oathtool.pad('test', size=16)
print(f"Padded to 16: '{padded_16}'")  # Output: Padded to 16: 'test============'
```

--------------------------------

### Python API - generate_otp

Source: https://context7.com/jaraco/oathtool/llms.txt

Generates a 6-digit one-time password using the provided base32-encoded secret key. It can use the current Unix timestamp divided by 30 seconds as the time step or accept a custom HOTP counter value for testing. Returns the OTP as a zero-padded string.

```APIDOC
## Python API - generate_otp

### Description
Generates a 6-digit one-time password using the provided base32-encoded secret key. By default, uses the current Unix timestamp divided by 30 seconds as the time step, or accepts a custom HOTP counter value for testing. Returns the OTP as a zero-padded string.

### Method
`oathtool.generate_otp(key, hotp_value=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (str) - Required - The base32-encoded secret key.
- **hotp_value** (int) - Optional - A specific HOTP counter value for testing purposes. If not provided, the current time-based counter is used.

### Request Example
```python
import oathtool

# Generate current TOTP with time-based counter
key = 'MZXW6YTBOJUWU23MNU'
code = oathtool.generate_otp(key)
print(f"Current OTP: {code}")

# Generate TOTP with specific HOTP value for testing
fixed_hotp = 52276810
code = oathtool.generate_otp(key, hotp_value=fixed_hotp)
print(f"Fixed OTP: {code}")

# Handle longer keys (useful for high-security applications)
long_key = 'MZXW6YTBOJUWU23MNU' * 10
code = oathtool.generate_otp(long_key, hotp_value=fixed_hotp)
print(f"Long key OTP: {code}")

# Keys with spaces are automatically cleaned
spaced_key = 'MZXW 6YTB OJUW U23M NU'
code = oathtool.generate_otp(spaced_key)
print(f"Spaced key OTP: {code}")
```

### Response
#### Success Response (200)
- **code** (str) - The generated 6-digit TOTP, zero-padded.

#### Response Example
```json
{
  "code": "487656"
}
```
```

--------------------------------

### Python API - pad

Source: https://context7.com/jaraco/oathtool/llms.txt

Adds RFC 3548 compliant padding to base32-encoded strings. Ensures the input length is a multiple of 8 by appending '=' characters. Used internally for base32 decoding but available for manual base32 processing.

```APIDOC
## Python API - pad

### Description
Adds RFC 3548 compliant padding to base32-encoded strings. Ensures the input length is a multiple of 8 by appending '=' characters. Used internally for base32 decoding but available for manual base32 processing.

### Method
`oathtool.pad(base32_string)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **base32_string** (str) - Required - The base32-encoded string to pad.

### Request Example
```python
import oathtool

# Pad short string
padded = oathtool.pad('foo')
print(padded)
```

### Response
#### Success Response (200)
- **padded_string** (str) - The base32 string with RFC 3548 padding.

#### Response Example
```
foo=====
```
```

--------------------------------

### Generate OTP using oathtool API

Source: https://github.com/jaraco/oathtool/blob/main/README.rst

Generates a One-Time Password (OTP) programmatically using the oathtool library's API. This method is suitable for integrating OTP generation into Python applications. It takes a secret key as an argument.

```python
import oathtool

oathtool.generate_otp(key)
```

--------------------------------

### Base32 Padding Utility (Python API)

Source: https://context7.com/jaraco/oathtool/llms.txt

Adds RFC 3548 compliant padding ('=') to base32-encoded strings, ensuring the input length is a multiple of 8. Used internally for base32 decoding but available for manual base32 processing.

```python
import oathtool

# Pad short string
padded = oathtool.pad('foo')
print(padded)  # Output: foo=====
```

--------------------------------

### Generate TOTP Code from Secret Key (Python API)

Source: https://context7.com/jaraco/oathtool/llms.txt

Generates a 6-digit one-time password using a base32-encoded secret key. Supports time-based counters and custom HOTP values for testing. Handles key cleaning and longer keys.

```python
import oathtool

# Generate current TOTP with time-based counter
key = 'MZXW6YTBOJUWU23MNU'
code = oathtool.generate_otp(key)
print(f"Current OTP: {code}")  # Output: '487656' (varies with time)

# Generate TOTP with specific HOTP value for testing
fixed_hotp = 52276810
code = oathtool.generate_otp(key, hotp_value=fixed_hotp)
print(f"Fixed OTP: {code}")  # Output: '487656'

# Handle longer keys (useful for high-security applications)
long_key = 'MZXW6YTBOJUWU23MNU' * 10
code = oathtool.generate_otp(long_key, hotp_value=fixed_hotp)
print(f"Long key OTP: {code}")  # Output: '295635'

# Keys with spaces are automatically cleaned
spaced_key = 'MZXW 6YTB OJUW U23M NU'
code = oathtool.generate_otp(spaced_key)
print(f"Spaced key OTP: {code}")
```

--------------------------------

### HMAC-SHA1 Implementation (Python API)

Source: https://context7.com/jaraco/oathtool/llms.txt

Implements HMAC-SHA1 hashing according to RFC 2104 with a 64-byte block size. Handles key padding and performs a two-pass hash computation. Used internally by generate_otp but available for custom cryptographic operations.

```python
import oathtool

# Basic HMAC-SHA1 computation
key = b'secret_key'
message = b'Hello, World!'
hash_value = oathtool.hmac(key, message)
print(hash_value.hex()) # Output: hexadecimal representation of 20-byte SHA1 hash

# HMAC with long key (automatically hashed to fit block size)
long_key = b'x' * 100
message = b'test message'
hash_value = oathtool.hmac(long_key, message)
print(f"Hash length: {len(hash_value)}")  # Output: Hash length: 20

# HMAC used in TOTP generation
import struct
hotp_bytes = struct.pack('>q', 52276810)
key_bytes = b'decoded_secret_key_bytes'
hmac_result = oathtool.hmac(key_bytes, hotp_bytes)
cut_offset = hmac_result[-1] & 0x0F
print(f"Truncation offset: {cut_offset}")
```

--------------------------------

### Python API - hmac

Source: https://context7.com/jaraco/oathtool/llms.txt

Implements HMAC-SHA1 hashing according to RFC 2104 with a 64-byte block size. Used internally by generate_otp but available for custom cryptographic operations. Handles key padding and performs the two-pass hash computation.

```APIDOC
## Python API - hmac

### Description
Implements HMAC-SHA1 hashing according to RFC 2104 with a 64-byte block size. Used internally by generate_otp but available for custom cryptographic operations. Handles key padding and performs the two-pass hash computation.

### Method
`oathtool.hmac(key, message)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (bytes) - Required - The secret key for the HMAC.
- **message** (bytes) - Required - The message to hash.

### Request Example
```python
import oathtool

# Basic HMAC-SHA1 computation
key = b'secret_key'
message = b'Hello, World!'
hash_value = oathtool.hmac(key, message)
print(hash_value.hex())

# HMAC with long key (automatically hashed to fit block size)
long_key = b'x' * 100
message = b'test message'
hash_value = oathtool.hmac(long_key, message)
print(f"Hash length: {len(hash_value)}")

# HMAC used in TOTP generation
import struct
hotp_bytes = struct.pack('>q', 52276810)
key_bytes = b'decoded_secret_key_bytes'
hmac_result = oathtool.hmac(key_bytes, hotp_bytes)
cut_offset = hmac_result[-1] & 0x0F
print(f"Truncation offset: {cut_offset}")
```

### Response
#### Success Response (200)
- **hash_value** (bytes) - The resulting HMAC-SHA1 hash as bytes.

#### Response Example
```
'a94a8fe5ccb19ba61c4c0873d391e987982fbbd3'
```
```

--------------------------------

### Clean Whitespace from Keys with oathtool.clean

Source: https://context7.com/jaraco/oathtool/llms.txt

Illustrates removing whitespace characters from secret keys using `oathtool.clean`. This is useful for normalizing human-readable keys that may contain spaces, before they are used in OTP generation workflows. It processes the input string and returns a version without any space characters.

```python
import oathtool
import base64

# Clean grouped key format
grouped_key = 'MZXW 6YTB OJUW U23M NU'
cleaned = oathtool.clean(grouped_key)
print(cleaned)  # Output: MZXW6YTBOJUWU23MNU

# Use in OTP generation workflow
spaced_key = 'JBSW Y3DP EHPK 3PXP'
clean_key = oathtool.clean(spaced_key)
padded_key = oathtool.pad(clean_key)
decoded = base64.b32decode(padded_key, casefold=True)
print(f"Decoded key length: {len(decoded)}")  # Output: Decoded key length: 10

# No spaces present
clean_already = oathtool.clean('ABCDEFGH12345678')
print(clean_already)  # Output: ABCDEFGH12345678
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.