OATHTOOL(1)

💅 NAME 💅

ok so bestie, this is oathtool — the Open AuTHentication (OATH) one-time password tool. it's the thing that makes your little six-digit codes go brrr. we're in section 1 of the manual, and yes, this whole page is about you finally understanding it. 🎀

✨ SYNOPSIS ✨

oathtool [OPTION]... [KEY [OTP]]...

🦋 DESCRIPTION 🦋

Generate and validate OATH one-time passwords. that's the whole vibe. 💫

so about KEY and OTP — each one of those is literally one of three things, no cap:

• the string -, which means "read it from standard input"
• @FILE, which means "read it from the indicated filename"
• a hex encoded value — and ngl, hex on the command line is not recommended on multi-user systems (we'll get to why, keep reading, it's giving security ick 🙈)

---

okay here's the option menu, and yes every single one is here, i did not skip a thing 👑

• -h, --help — print help and exit. the "i'm lost" button 🫶
• -V, --version — print version and exit. the "wait which version am i even on" button
• --hotp — use event-based HOTP mode (default=on). this is the default bestie, it's already on 💅
• --totp[=MODE] — use time-variant TOTP mode. MODE is one of "SHA1", "SHA256", or "SHA512", and the default is SHA1. this is the one everyone actually uses ✨
• -b, --base32 — use base32 encoding of KEY instead of hex (default=off)
• --hex — use hex encoding of KEY (default=on). the classic.
• -c, --counter=COUNTER — HOTP counter value. for when you need to point at one specific OTP 👉
• -s, --time-step-size=DURATION — TOTP time-step duration (default=30s)
• -S, --start-time=TIME — when to start counting time steps for TOTP (default=1970-01-01 00:00:00 UTC)
• -N, --now=TIME — use this time as current time for TOTP (default=now). time travel but make it CLI 🕰️
• -d, --digits=DIGITS — number of digits in the one-time password
• -w, --window=WIDTH — number of additional OTPs to generate or validate against
• -v, --verbose — explain what is being done (default=off). the "tell me everything" flag, we love a transparent king 👑

🌸 EXAMPLES 🌸

okay this is the fun part. to generate a time-based (TOTP) one-time password from a key that's protected by GnuPG:

$ gpg --decrypt --quiet ~/.my-totp-secret.asc | oathtool --totp -

how to actually create that encrypted file is outside of scope of this manual — go read gpg(1) — but these two commands may help you encrypt the secret symmetrically (using a password) or asymmetrically (if you have created a private key), respectively. you'll need to provide the secret from the terminal after invoking the commands. 🧚

$ gpg --symmetric > ~/.my-totp-secret.asc
$ gpg --encrypt --default-recipient-self > ~/.my-totp-secret.asc

for easier reading, the rest of this man page provides the KEY and OTP on the command line. keep in mind that this usage is not recommended — on most multi-user systems, command-line parameters of running processes can be seen by other users. like, literally anyone can peek. 💀

---

to generate the first event-based (HOTP) one-time password for an all-zero key:

$ echo 00 | oathtool -
328482
$

sometimes you want more than a single OTP. to generate 10 additional event-based one-time passwords, with the secret key used in the examples of RFC 4226, use the -w (--window) parameter:

$ oathtool -w 10 3132333435363738393031323334353637383930
755224
287082
359152
969429
338314
254676
287922
162583
399871
520489
403154
$

in that last output, the counter for the first OTP was 0, the second OTP had a counter of 1, and so on up to 10. count 'em, they're all there 🔥

---

in order to use keys encoded in Base32 instead of hex, you may provide the -b (--base32) parameter:

$ oathtool --base32 -w 3 GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
755224
287082
359152
969429
$

the tool ignores whitespace in base32 data and re-adds padding if necessary, so you may supply keys formatted like the one below. spaces are just decoration, she doesn't care 🎀

$ oathtool --base32 --totp "gr6d 5br7 25s6 vnck v4vl hlao re"
977872
$

---

to generate a particular OTP, use the -c (--counter) parameter to give the exact position directly:

$ oathtool -c 5 3132333435363738393031323334353637383930
254676
$

to validate a HOTP one-time password, supply the OTP last on the command line:

$ oathtool -w 10 3132333435363738393031323334353637383930 969429
3
$

the output indicates the counter that was used. it works by starting with counter 0 and incrementing until it finds a match (or not), within the supplied window of 10 OTPs. lowkey a little search party 🔍

---

the tool supports time-variant one-time passwords too, in so called TOTP mode. usage is similar, but --totp needs to be provided:

$ oathtool --totp 00
943388
$

don't be alarmed if you do not get the same output — this is because the output depends on the current time. to generate a TOTP for a particular fixed time, use the -N (--now) parameter:

$ oathtool --totp --now "2008-04-23 17:42:17 UTC" 00
974945
$

the format is a mostly free format human readable date string such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29 16:21:42" or even "next Thursday". it's the same format used as the --date parameter of the date(1) tool. yes, "next Thursday" genuinely works, she's flexible like that 💅

---

the default MAC algorithm to use with TOTP is HMAC-SHA1, and this is what is usually used. the tool supports two other MACs, namely HMAC-SHA256 and HMAC-SHA512 as well. to use either of these, qualify the --totp parameter with a value: use "SHA256" for HMAC-SHA256 and "SHA512" for HMAC-SHA512. the following demonstrates generating one of the RFC 6238 test vectors:

$ oathtool --totp=SHA256 --digits=8 --now "2009-02-13 23:31:30 UTC" 3132333435363738393031323334353637383930313233343536373839303132
91819424
$

you may generate several TOTPs by specifying the --window parameter, similar to how it works for HOTP. the OTPs generated here will be for the initial time (normally current time) and then each following time step (e.g., 30 second window). ✨

$ oathtool --totp 00 -w5
815120
003818
814756
184042
582326
733842
$

you can validate a TOTP one-time password by supplying the secret and a window parameter (number of time steps before or after current time):

$ oathtool --totp -w 5 00 `oathtool --totp 00`
0
$

similar when generating TOTPs, you can use a -N (--now) parameter to specify the time to use instead of the current time:

$ oathtool --totp --now="2005-03-18 01:58:29 UTC" -w 10000000 3132333435363738393031323334353637383930 89005924
4115227
$

the previous test uses values from the TOTP specification and will stress test the tool because the expected window is around 4 million time-steps. she's gonna be working overtime, hydrate her 😭💧

---

there are two system parameters for TOTP: the time-step size and the time start.

by default the time-step size is 30 seconds, which means you get a new OTP every 30 seconds. you may modify this with the -s (--time-step-size) parameter:

$ oathtool --totp --time-step-size=45s 00
109841
$

the values are valid ISO-8601 durations, see: http://en.wikipedia.org/wiki/ISO_8601#Durations

the time start is normally 1970-01-01 00:00:00 UTC but you may change it using the -S (--start-time):

$ oathtool --totp --start-time "1980-01-01 00:00:00 UTC" 00
273884
$

---

to get more information about what the tool is using, use the -v (--verbose) parameter. finally, to generate the last TOTP (for SHA-1) in the test vector table of RFC 6238, you can invoke the tool like this:

$ oathtool --totp -v -N "2033-05-18 03:33:20 UTC" -d8 3132333435363738393031323334353637383930
Hex secret: 3132333435363738393031323334353637383930
Base32 secret: GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ
Digits: 8
Window size: 0
TOTP mode: SHA1
Step size (seconds): 30
Start time: 1970-01-01 00:00:00 UTC (0)
Time now: 2033-05-18 03:33:20 UTC (2000000000)
Counter: 0x3F940AA (66666666)

69279037
$

like, look at all that info. main character energy, honestly 👑✨

🫶 AUTHOR 🫶

Written by Simon Josefsson. (the icon who did this. respect. 🎀)

🙈 REPORTING BUGS 🙈

Report bugs to: <oath-toolkit-help@nongnu.org>.

OATH Toolkit home page: <https://oath-toolkit.codeberg.page/>

👑 COPYRIGHT 👑

Copyright © 2009-2026 Simon Josefsson. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it.

There is NO WARRANTY, to the extent permitted by law. (fr fr, none, zero, don't come for her 💀)

---

and that's the page bestie!! 🦋 this was OATHTOOL(1) from OATH Toolkit 2.6.15, dated October 2026. go forth and generate your little codes, you've got this 💖✨🌸