Chronokey

A simple and secure CLI tool for managing and generating Time-based One-Time Password (TOTP) codes for two-factor authentication (2FA).

Features

• Store multiple TOTP secrets securely on your local machine
• Generate 6-digit TOTP codes instantly
• Interactive CLI with intuitive prompts
• Support for both base32-encoded and plain text secrets
• List, add, and remove TOTP entries easily

Installation

Via npm (Recommended)

The easiest way to install chronokey:

npm install -g chronokey

Via Homebrew (macOS/Linux)

Alternatively, you can install via Homebrew:

brew tap yashu183/chronokey
brew trust yashu183/chronokey
brew install chronokey

Note: The trust step is required for third-party Homebrew taps (this is a Homebrew security feature).

Local Development Setup

Prerequisites:

• Node.js (v14 or higher)
• npm or yarn

From Source

1. Clone the repository:

git clone https://github.com/yashu183/chronokey.git
cd chronokey

2. Install dependencies:

npm install

3. Run in development mode:

npm run dev -- <command>

Or build and link globally:

npm run build
npm link
chronokey <command>

Usage

Add a New TOTP Entry

Set up a new TOTP entry by providing a unique name and secret key:

chronokey setup

You'll be prompted to:

1. Enter a unique name for the entry (e.g., "GitHub", "Google", "AWS")
2. Enter the secret key (will be masked for security)
3. Confirm to save

Generate a TOTP Code

Generate a TOTP code for a saved entry:

# Interactive selection
chronokey generate

# Or specify the entry name directly
chronokey generate GitHub

# Using alias
chronokey gen GitHub

The code is valid for approximately 30 seconds.

List All Entries

View all saved TOTP entries:

chronokey list

# Using alias
chronokey ls

Remove an Entry

Delete a TOTP entry:

# Interactive selection
chronokey remove

# Or specify the entry name directly
chronokey remove GitHub

# Using alias
chronokey rm GitHub

You'll be asked to confirm before deletion.

Configuration

Chronokey stores your TOTP secrets locally in:

~/.chronokey/config.json

Security Note: Your secrets are stored in plain text in this file. Ensure proper file permissions are set and keep this directory secure.

How It Works

TOTP (Time-based One-Time Password) generates a unique 6-digit code that changes every 30 seconds based on:

1. A shared secret key (provided when you set up 2FA)
2. The current time

This tool uses the speakeasy library to generate standard TOTP codes compatible with most 2FA services.

Examples

# Add a new GitHub 2FA entry
chronokey setup
> Enter a unique name: GitHub
> Enter the secret key: ************
> Confirm? Yes
✓ Successfully added TOTP entry: GitHub

# Generate a code for GitHub
chronokey gen GitHub
🔑 TOTP Code for "GitHub": 123456
   Valid for ~30 seconds

# List all entries
chronokey list
📋 Saved TOTP Entries:
   1. GitHub
   2. Google
   3. AWS

# Remove an entry
chronokey rm GitHub
> Are you sure? Yes
✓ Successfully removed entry: GitHub

Development

Project Structure

chronokey/
├── src/
│   ├── index.ts      # Main CLI entry point with commands
│   ├── config.ts     # Configuration management
│   └── totp.ts       # TOTP generation logic
├── dist/             # Compiled JavaScript (generated)
├── package.json      # Project dependencies and scripts
├── tsconfig.json     # TypeScript configuration
└── README.md         # This file

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run in development mode with ts-node
• npm start - Run the compiled version

License

MIT

Author

Built with Commander.js, Inquirer.js, and Speakeasy.