{"id":24807373,"url":"https://github.com/yitsushi/totp-cli","last_synced_at":"2025-05-15T20:04:49.552Z","repository":{"id":41445855,"uuid":"68098216","full_name":"yitsushi/totp-cli","owner":"yitsushi","description":"Authy/Google Authenticator like TOTP CLI tool written in Go.","archived":false,"fork":false,"pushed_at":"2025-02-26T22:07:03.000Z","size":4264,"stargazers_count":291,"open_issues_count":8,"forks_count":28,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-19T02:14:57.692Z","etag":null,"topics":["cli","hacktoberfest","otp-generator","totp","totp-cli"],"latest_commit_sha":null,"homepage":"http://yitsushi.github.io/totp-cli/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yitsushi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-09-13T10:21:40.000Z","updated_at":"2025-04-17T06:33:19.000Z","dependencies_parsed_at":"2023-02-12T06:15:25.800Z","dependency_job_id":"2d5b1aef-50ea-4221-9f76-a2ef57e2705c","html_url":"https://github.com/yitsushi/totp-cli","commit_stats":{"total_commits":146,"total_committers":15,"mean_commits":9.733333333333333,"dds":0.452054794520548,"last_synced_commit":"b72e7108e1182494fb5a70aa781bbbb2b39c5c9e"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yitsushi%2Ftotp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yitsushi%2Ftotp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yitsushi%2Ftotp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yitsushi%2Ftotp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yitsushi","download_url":"https://codeload.github.com/yitsushi/totp-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","hacktoberfest","otp-generator","totp","totp-cli"],"created_at":"2025-01-30T09:18:28.879Z","updated_at":"2025-05-15T20:04:45.015Z","avatar_url":"https://github.com/yitsushi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go Report Card](https://goreportcard.com/badge/github.com/yitsushi/totp-cli)](https://goreportcard.com/report/github.com/yitsushi/totp-cli)\n[![Actions Status](https://github.com/yitsushi/totp-cli/actions/workflows/quality-check.yaml/badge.svg)](https://github.com/yitsushi/totp-cli/actions/workflows/quality-check.yaml)\n[![Coverage Status](https://coveralls.io/repos/github/yitsushi/totp-cli/badge.svg?branch=main)](https://coveralls.io/github/yitsushi/totp-cli?branch=main)\n\nThis is a simple TOTP _(Time-based One-time Password)_ CLI tool.\nTOTP is the most common mechanism for 2FA _(Two-Factor-Authentication)_.\nYou can manage and organize your accounts with namespaces\nand protect your data with a password.\n\n### Install\n\nDownload the latest version of the application\nfrom the [releases page](https://github.com/yitsushi/totp-cli/releases/latest) or using the `go` tool:\n\n```shell\ngo install github.com/yitsushi/totp-cli@latest\n```\n\n#### Alternative\n\nI'm not the maintainer of the MacPorts or the Homebrew package, if it's outdated\nplease contact with the maintainer.\n\n\nUsers on macOS can also install the package using [MacPorts](https://ports.macports.org/port/totp-cli/summary):\n```shell\nsudo port selfupdate\nsudo port install totp-cli\n```\n\nor [Homebrew](https://brew.sh/):\n\n```\nbrew install totp-cli\n```\n\n#### Signing key\n\nOn release, there is a checksum file for all generated artefacts. This file is\nsigned with the [66EA13043E6CDBA67A5D85AB71BD3AD93E8B6ABF](https://keys.openpgp.org/search?q=66EA13043E6CDBA67A5D85AB71BD3AD93E8B6ABF)\nGPG key.\n\n```\ngpg --keyserver keys.openpgp.org --recv-keys 66EA13043E6CDBA67A5D85AB71BD3AD93E8B6ABF\ngpg --verify totp-cli_{{.Version}}_checksums.txt.sig\n```\n\n#### Upgrading from totp-cli v1.2.7 or below\n\nStarting with totp-cli v1.2.8 a [more secure storage\nformat](https://github.com/FiloSottile/age) is used. The storage will be\nupgraded the first time it is written to by totp-cli. You can force this to\noccur by running `totp-cli change-password`.\n\n### Help output\n\n```shell\ntotp-cli help\n```\n\n```\nNAME:\n   totp-cli - Authy/Google Authenticator like TOTP CLI tool written in Go.\n\nUSAGE:\n   totp-cli [global options] command [command options] [arguments...]\n\nVERSION:\n   v1.8.0\n\nAUTHOR:\n   Efertone \u003cefertone@pm.me\u003e\n\nCOMMANDS:\n   add-token, add   Add new token.\n   change-password  Change password.\n   delete           Delete an account or a whole namespace.\n   dump             Dump all available accounts under all namespaces.\n   generate, g      Generate a specific OTP\n   import           Import tokens from a yaml file.\n   instant          Generate an OTP from TOTP_TOKEN or stdin without the Storage backend.\n   list             List all available namespaces or accounts under a namespace.\n   set-prefix       Set prefix for a token.\n   set-length       Set length for a token.\n   rename           Rename an account or namespace\n   help, h          Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --help, -h     show help\n   --version, -v  print the version\n```\n\n### Usage\n\nWhen you run the application for the first time, it will ask\nfor your password. **DO NOT FORGET IT!** There is no way to\nrecover your password if you forget it.\n\nYour first command _(after `help`)_ would be `add-token`. You can get\nyour token read a TOTP QR Code.\n\n```shell\ntotp-cli add-token\n```\n\n```\nNamespace: personal\nAccount: digitalocean\nToken: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nPassword: ***\n```\n\nYou can specify the namespace and the account name as a parameter:\n\n```shell\ntotp-cli add-token personal randomaccount\n```\n\n```\nToken: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\nPassword: ***\n```\n\nIf the provider uses a different length for tokens, you can set it on\n`add-token` or set with `set-length`.\n\n```\ntotp-cli add-token --length=8 personal randomaccount\ntotp-cli set-length personal randomaccount 6\n```\n\nIf you want to delete `randomaccount` _(because it was a test for example)_,\nyou can use `delete`:\n\n```shell\ntotp-cli delete personal.randomaccount\n```\n\n```\nPassword: ***\nYou want to delete 'personal.randomaccount' account.\nAre you sure? yes\n```\n\nAfter few accounts, it's a bit hard to remember what did you added,\nso you can list namespaces:\n\n```shell\ntotp-cli list\n```\n\n```\nPassword: ***\ncompany1 (Number of accounts: 3)\ncompany2 (Number of accounts: 5)\npersonal (Number of accounts: 8)\n```\n\nor you can list your accounts under a specific namespace:\n\n```shell\ntotp-cli list personal\n```\n\n```\nPassword: ***\npersonal.evernote\npersonal.google\npersonal.github\npersonal.ifttt\npersonal.digitalocean\npersonal.dropbox\npersonal.facebook\n```\n\nIf you want to change your password, you can do it with the `change-password`\ncommand.\n\nSome providers require the user to prefix the generated token with their\npassword or passphrase. You can set a prefix for each account with `set-prefix`,\nor set with `add-token`.\n\n```\ntotp-cli set-prefix ns account\nPrefix: myprefix\n\ntotp-cli add-token --prefix=asd personal randomaccount\ntotp-cli set-prefix personal randomaccount asd\n\n# Clear prefix\ntotp-cli set-prefix ns account --clear\n```\n\nTo generate an OTP, you simply use the `generate` command like:\n\n```shell\ntotp-cli generate namespace account\nPassword: ***\n889840\n```\n\nYou can also use the `--follow` flag on the `generate` command if you want to \nhave the OTP token automatically refreshed once expired:\n\n```shell\ntotp-cli generate --follow namespace account\nPassword: ***\n889840\n343555\n463346\n```\n\nIf the provider is very strict with the code, with the `--show-remaining` flag\nwill add extra information about how long the code will be valid.\n\n```\ntotp-cli generate --show-remaining namespace account\nPassword: ***\n316762 (remaining time: 17s)\n```\n\n### Changing the location of the credentials file\n\nSimply put this into your `.zshrc` (or `.{YourShell}rc` or `.profile`):\n\n```shell\nexport TOTP_CLI_CREDENTIAL_FILE=\"/mnt/mydrive/totp-credentials\"\n```\n\nOr call the client with `TOTP_CLI_CREDENTIAL_FILE`:\n\n```shell\n$ TOTP_CLI_CREDENTIAL_FILE=/mnt/mydrive/totp-credentials totp-cli list\n```\n\nThe default location is `${HOME}/.config/totp-cli/credentials`.\n\n**Note:** It's a filename not just a directory.\n\n**Note:** It does not traverse through the given path,\n      parent directory has to be there already.\n\n### Import\n\nYou can import tokens from a YAML file. The syntax is the same as the output of\nthe `dump` command.\n\n```yaml\n- name: ns1\n  accounts:\n    - name: acc1\n      token: updatedtoken\n    - name: acc2\n      token: mytoken\n    - name: acc3\n      token: tokenish\n- name: ns2\n  accounts:\n    - name: acc1\n      token: token\n      prefix: myprefix\n```\n\nIf a token already exists, it will ask you if you want to overwrite it or not.\n\n```shell\ntotp-cli import list.yaml\n```\n\n### Shell Completion\n\nDisclaimer: I don't have much expertise with auto-complete integrations. The\nfollowing instructions should be enough, but it is possible they are not. Feel\nfree to open a Pull Request with any additional suggestions/fixes either in the\ndocs or the autocomplete scripts.\n\n* Bash: `autocomplete/bash_autocomplete`\n* Zsh: `autocomplete/zsh_autocomplete`\n\n#### Zsh\n\nA function to provide tab-completion for zsh is in the file\n`autocomplete/zsh_autocomplete`. When installing or packaging totp-cli this\nshould preferably be installed in `$prefix/share/zsh/site-functions`. Otherwise,\nit can be installed by copying to a directory where zsh searches for completion\nfunctions (the `$fpath` array). If you, for example, put all completion\nfunctions into the folder `~/.zsh/completions` you must add the following to\nyour zsh main config file (`.zshrc`):\n\n```shell\ncp autocomplete/zsh_autocomplete ~/.zsh/functions/_totp_cli\nfpath=( ~/.zsh/completions $fpath )\nautoload -U compinit\ncompinit\n```\n\n#### Bash\n\n```\nmkdir -p ~/.local/share/bash-completion/completions\ncp autocomplete/bash_autocomplete ~/.local/share/bash-completion/completions/totp-cli\n```\n\n## About the password\n\nThe password should never be passed directly to any applications to unlock it.\nIf you save it in a variable it can be exposed if your `ENV` is exposed somehow,\nif you directly type in the password in the command line, it can end up in your\nbash/zsh/whatevershell history.\n\nMostly to support CI/CD automation, there is an option to set the\npassword/passphrase as an environment variable. **Please use it only if you know\nthe system is safe to store passwords in environment variables.**\n\nIf you really want to skip the password prompt, it reads from `stdin`, so you\ncan pipe the password.\n\n```\n❯ age \\\n  --encrypt \\\n  --armor \\\n  --recipient age15velesv0zwpsc5w0n4da5tv64u9fzuhl8hjpvdmeayjg00fdf4wsxl834c \\\n  \u003e \"${HOME}/.config/totp-cli/totp-password.age\"\nmyapssword\n^D\n\n❯ age --decrypt --identity ~/.age/efertone.txt ~/.config/totp-cli/totp-password.age | totp-cli list\nPassword: ***\n....list of namespaces\n\n❯ age --decrypt --identity ~/.age/efertone.txt ~/.config/totp-cli/totp-password.age | totp-cli generate xxxxx xxxxx\nPassword: ***\n166307\n\n❯ alias totp-pass-in=\"age --decrypt --identity ~/.age/efertone.txt ~/.config/totp-cli/totp-password.age\"\n\n❯ totp-pass-in| totp-cli generate xxxxx xxxxx\nPassword: ***\n889840\n```\n\nOther option is to use an environment variable:\n\n```\n❯ age \\\n  --encrypt \\\n  --armor \\\n  --recipient age15velesv0zwpsc5w0n4da5tv64u9fzuhl8hjpvdmeayjg00fdf4wsxl834c \\\n  \u003e \"${HOME}/.config/totp-cli/totp-password.age\"\nmyapssword\n^D\n\n❯ export TOTP_PASS=$(age --decrypt --identity ~/.age/efertone.txt ~/.config/totp-cli/totp-password.age)\nPassword: ***\n\n❯ totp-cli generate xxxxx xxxxx\n166307\n```\n\nBut I'm really against it, it's a password that can access all your stored 2FA\ntokens. With the password (even without the `totp-cli` application) and the\ncredentials files, that file is not really encrypted anymore as it can be\ndecrypted with the password.\n\n**Please, never store your password as clear-text. Never. Pretty please.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyitsushi%2Ftotp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyitsushi%2Ftotp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyitsushi%2Ftotp-cli/lists"}