Skip to content

Providers

Jump to bottom
James Wragg edited this page Feb 28, 2026 · 3 revisions

Viscosity OTP works with any CLI tool that outputs a TOTP code to stdout. Below are setup guides for common providers.

1Password

Prerequisites

Finding Your Item UUID

  1. Open 1Password desktop app
  2. Right-click the item containing your VPN OTP
  3. Select Copy UUID

Note: If "Copy UUID" isn't visible, go to 1Password → Settings → Advanced and enable Developer experience.

Configuration

defaults write net.skycmd.viscosity-otp "<connection-name>" "/usr/local/bin/op item get <uuid> --otp"

Replace <uuid> with the UUID you copied.

How It Works

When you connect, op item get fetches the TOTP code. If you have desktop app integration enabled, 1Password will authenticate via Touch ID or your system password. Approve the prompt quickly — Viscosity has a ~10 second timeout for Before Connect scripts.

Bitwarden

Prerequisites

Configuration

defaults write net.skycmd.viscosity-otp "<connection-name>" "/usr/local/bin/bw get totp <item>"

Where <item> is the item name, ID, or search term.

KeePassXC

Prerequisites

Configuration

defaults write net.skycmd.viscosity-otp "<connection-name>" "keepassxc-cli show -t <database-path> <entry-name>"

Note on Passwords

keepassxc-cli will prompt for the database password on stdin. This may not work well in the non-interactive context of a Viscosity Before Connect script. Consider using KeePassXC's secret service integration or a keyfile-based unlock instead.

oathtool

Prerequisites

  • oathtool installed (brew install oath-toolkit)

Configuration

defaults write net.skycmd.viscosity-otp "<connection-name>" "oathtool --totp --base32 <secret>"

Caution

This stores your TOTP secret in plaintext in the macOS preferences plist. Anyone with access to your user account can read it. This approach is not recommended for sensitive credentials. Prefer a password manager like 1Password or Bitwarden instead.

Securing the Secret (Optional)

You can store the secret in macOS Keychain and retrieve it at runtime:

security add-generic-password -a "my-vpn-totp" -s "my-vpn-totp" -w "<secret>"

Then configure:

defaults write net.skycmd.viscosity-otp "<connection-name>" "oathtool --totp --base32 \$(security find-generic-password -a my-vpn-totp -w)"

Custom Scripts

You can use any script or command as long as it:

  1. Outputs the OTP code (and only the OTP code) to stdout
  2. Exits with code 0 on success
  3. Exits with a non-zero code on failure (stderr will be shown in the error dialog)

Example: Custom Script

defaults write net.skycmd.viscosity-otp "<connection-name>" "/path/to/my-otp-script.sh"

Where my-otp-script.sh might be:

#!/bin/bash
# Fetch OTP from a custom API
curl -s https://internal.example.com/api/otp?vpn=my-vpn

Make sure the script is executable (chmod +x my-otp-script.sh).

Clone this wiki locally