otplib-cli 1.0.1 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2017 Gerald Yeo
+Copyright (c) 2026 Gerald Yeo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,59 +1,102 @@
 # otplib-cli
 
-> Command-line tool for OTP token generation and verification
+A Command Line tool for OTP operations.
+It provides stateless, scriptable and storage agnostic tooling.
 
-[![npm][npm-badge]][npm-link]
+## Installation
 
-## Install
-
-```
-$ npm install -g otplib-cli
+```bash
+npm install -g otplib-cli
 ```
 
-## Usage
+Two commands are available:
 
-```
-Usage: otplib [options] [command]
+- **`otplibx`** - Includes an encrypted `.env` based storage
+- **`otplib`** - Stateless CLI for scripting and custom backends
 
+## Quick Start
 
-Commands:
+### otplibx
 
-  init [options]            initialise a new configuration
-  generate [options]        generate new tokens
-  verify [options] [token]  validate a token against the setting or configuration
-  qrcode [options]          generate a QR Code from configuration
-  encrypt [secret]          encrypt secret to store in config
-  decrypt [secret]          decrypt secret from config
+```bash
+# Initialize secrets file
+otplibx init
 
-Options:
+# Add entry from file or clipboard
+cat otp-uri.txt | otplibx add
+pbpaste | otplibx add
 
-  -h, --help                 output usage information
-  -V, --version              output the version number
-  -p, --password [password]  password to encrypt/decrypt the secret
-  -k, --secret [key]         provide a secret key
-  -c, --config [path]         path to configuration file
-  -m, --mode [mode]          operation mode. (hotp | totp | authenticator)
-  -d, --digits [number]      number of digits in token
-  -a, --algorithm [type]     algorithm to generate for totp (sha1 | sha256 | sha512)
-  -s, --step [number]        time step (totp / authenticator)
-```
+# Generate token
+otplibx token A1B2C3D4
 
-For individual command options, you can run `-h` for each of them. i.e.
+# List entries
+otplibx list
+otplibx list --filter github
 
+# Interactive selection with fzf
+npx otplibx token -n "$(npx otplibx list | fzf | cut -f2)" | pbcopy
+# OR
+npx otplibx list | fzf | cut -f2 | xargs -I {} npx otplibx token -n {} | pbcopy
 ```
-$ otplib init -h
-$ otplib generate -h
-$ otplib verify -h
-$ otplib qrcode -h
+
+### otplib
+
+For scripting or custom secret backends, use the stateless `otplib` CLI.
+
+```bash
+# Encode an otpauth URI into internal format
+cat otp-uri.txt | otplib encode
+# Output: A1B2C3D4=eyJkYXRhIjp7...}}
+
+# Store the output in a JSON file (storage.json)
+# { "A1B2C3D4": "eyJkYXRhIjp7...}}" }
+
+# Generate token
+cat storage.json | otplib token A1B2C3D4
+
+# List entries
+cat storage.json | otplib list
+cat storage.json | otplib list --filter github
+
+# Verify a token
+cat storage.json | otplib verify A1B2C3D4 123456
 ```
 
-## Related
+## Commands
 
--   [otplib](https://github.com/yeojz/otplib) - API for this module
+### otplibx
 
-## License
+| Command                        | Description                       |
+| ------------------------------ | --------------------------------- |
+| `init [file]`                  | Initialize encrypted secrets file |
+| `add`                          | Add entry (reads from stdin)      |
+| `token [-n] [id]`              | Generate token                    |
+| `type [-n] [id]`               | Output entry type                 |
+| `hotp update-counter <id> [n]` | Update HOTP counter               |
+| `verify <id> <token>`          | Verify token                      |
+| `list [--filter <query>]`      | List entries                      |
+| `guard update <key> <value>`   | Update guardrail                  |
+| `guard rm <key>`               | Remove guardrail                  |
+| `guard show`                   | Show guardrails                   |
+
+Options: `-f, --file <path>` (default: `.env.otplibx`)
+
+### otplib
 
-`otplib-cli` is [MIT licensed](./LICENSE)
+| Command                        | Description                                |
+| ------------------------------ | ------------------------------------------ |
+| `encode [--save-uid <file>]`   | Encode otpauth URI/JSON to internal format |
+| `list [-f, --filter <query>]`  | List entries                               |
+| `token [-n] <id>`              | Generate token (auto-detect)               |
+| `type [-n] <id>`               | Output entry type                          |
+| `hotp update-counter <id> [n]` | Update HOTP counter                        |
+| `verify <id> <token>`          | Verify token                               |
+| `guard show`                   | Show guardrails                            |
+
+## Documentation
+
+See the [full documentation](https://otplib.yeojz.dev/guide/cli) for detailed usage, architecture, and integration with other secret managers.
+
+## License
 
-[npm-badge]: https://img.shields.io/npm/v/otplib-cli.svg?style=flat-square
-[npm-link]: https://www.npmjs.com/package/otplib-cli
+[MIT](./LICENSE)