zora-cli 0.1.3__tar.gz → 0.2__tar.gz

{zora_cli-0.1.3/zora_cli.egg-info → zora_cli-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zora-cli
-Version: 0.1.3
+Version: 0.2
 Summary: Cryptographically secure generator of random keys with tons of options and customizations.
 Author: zscopuv
 License: ZORA SOURCE-AVAILABLE LICENSE
@@ -227,14 +227,16 @@ Requires-Dist: colorama==0.4.6
 Requires-Dist: packaging>=24.0
 Dynamic: license-file
 
-# ![Logo](zora.jpg)
-> **Early release (`v0.1.3`)**
+# ![Logo](https://i.ibb.co/21JfnbBZ/zora.jpg)
 
-Zora generates random keys using Python's cryptographically secure
-`secrets` module by default. It supports customizable character sets,
-charset presets, prefixes, suffixes, grouping, multiple outputs, file
-output, entropy estimation, and an optional deterministic PRNG mode.
+> **Early release (`v0.2`)**
 
+Zora is a command-line tool for generating random keys using Python's
+cryptographically secure `secrets` module by default.
+
+It supports customizable character sets, composable charset presets,
+prefixes, suffixes, grouping, multiple output formats, file output,
+entropy estimation, benchmarking, and an optional deterministic PRNG mode.
 
 ---
 
@@ -245,32 +247,66 @@ output, entropy estimation, and an optional deterministic PRNG mode.
 - 🎲 **Deterministic generation** with `--seed` in unsafe mode
 - 🔤 **Custom character sets**
 - 🧩 **Composable charset presets** such as `@letters@digits`
-- 🔢 **Built-in hexadecimal, octal, binary, digit, and symbol presets**
+- ⚡ **Fast charset shorthand** with `-x`
+- 🔢 **28 built-in charset presets**
 - ➕ Add **custom characters** to presets
 - 📏 Configurable **key length**
 - 📦 Generate **multiple keys** at once
 - 🔗 Add **prefixes and suffixes**
 - 📐 **Group keys with custom separators**
 - 💾 Write generated **keys to a file**
+- 📤 Multiple output formats: **Text, JSON, CSV, XML, YAML**
 - 📊 Calculate **theoretical entropy**
 - 💪 **Estimate key strength** from entropy
 - ⏱️ Display **generation time**
+- 🏁 **Benchmark key generation**
 - 🤫 **Quiet mode** for scripting
 - 📋 **Charset preset listing**
+- 🔍 **Charset and argument validation**
+- ℹ️ Display the installed version with `--version`
+
+---
+
+# Installation
+
+## Requirements
+
+Python 3.9 or newer is recommended.
+
+Install Zora from PyPI:
+
+```bash
+pip install zora-cli
+````
+
+Run Zora:
+
+```bash
+zora 32
+```
+
+### Optional YAML support
 
+YAML output requires PyYAML:
+
+```bash
+pip install pyyaml
+```
+
+---
 
 # Usage
 
 Basic usage:
 
 ```bash
-python zora.py LENGTH [OPTIONS]
+zora LENGTH [OPTIONS]
 ```
 
 For example:
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 Example output:
@@ -279,6 +315,7 @@ Example output:
 GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
 
 Timer: 13ms elapsed
+
 Charset: 52
 Entropy: 182.41 bits
 Strength: Very strong
@@ -294,51 +331,130 @@ Generator: CSPRNG
 The length of the random portion of the generated key.
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 The value must be greater than `0`.
 
 ---
 
-## `--charset`
+## `--version`
 
-Select the character set used to generate keys.
+Display the currently installed Zora version:
 
 ```bash
-python zora.py 32 --charset @digits
+zora --version
 ```
 
-By default:
+Example:
+
+```text
+zora 0.2.0
+```
+
+---
+
+## `--charset` / `-x`
+
+Select the character set used to generate keys.
+
+The default charset is:
 
 ```text
 @letters
 ```
 
-is used.
+Long form:
+
+```bash
+zora 32 --charset @digits
+```
+
+Short form:
+
+```bash
+zora 32 -x @digits
+```
+
+The `-x` option is provided as a convenient shorthand for faster charset selection.
 
 Zora supports both predefined charset presets and literal characters.
 
-### Presets
+---
 
-Use `--charset-list` to display all available presets:
+## Charset presets
+
+Use:
 
 ```bash
-python zora.py --charset-list
+zora --charset-list
 ```
 
-Currently available presets:
+to display all available presets.
 
-| Preset     | Characters                    |
-| ---------- | ----------------------------- |
-| `@digits`  | `0-9`                  |
-| `@letters` | `a-zA-Z`                      |
-| `@lower`   | `a-z`                         |
-| `@upper`   | `A-Z`                         |
-| `@hex`     | `0-9ABCDEFabcdef`        |
-| `@oct`     | `01234567`              |
-| `@bin`     | `01`                          |
-| `@special` | all punctuation/symbol characters |
+## Basic
+
+| Preset     | Characters              |
+| ---------- | ----------------------- |
+| `@digits`  | `0-9`                   |
+| `@letters` | `a-zA-Z`                |
+| `@lower`   | `a-z`                   |
+| `@upper`   | `A-Z`                   |
+| `@special` | Punctuation and symbols |
+
+## Numeric
+
+| Preset    | Characters               |
+| --------- | ------------------------ |
+| `@bin`    | `01`                     |
+| `@oct`    | `01234567`               |
+| `@hex`    | `0123456789ABCDEF`       |
+| `@lhex`   | `0123456789abcdef`       |
+| `@allhex` | `0123456789ABCDEFabcdef` |
+
+## URL / filename friendly
+
+| Preset      | Characters                       |
+| ----------- | -------------------------------- |
+| `@url`      | URL-friendly characters          |
+| `@urlsafe`  | URL-safe alphanumeric characters |
+| `@filename` | Filename-safe characters         |
+
+## Human-friendly
+
+These presets avoid characters that can easily be confused with one another.
+
+| Preset        | Description                   |
+| ------------- | ----------------------------- |
+| `@lowersafe`     | Lowercase without `l`         |
+| `@uppersafe`     | Uppercase without `I` and `O` |
+| `@digitssafe` | Digits without `0` and `1`    |
+
+## Base encodings
+
+| Preset     | Description               |
+| ---------- | ------------------------- |
+| `@base32`  | Uppercase Base32 alphabet |
+| `@base32x` | Lowercase Base32 alphabet |
+| `@base36` | Uppercase Base36 alphabet |
+| `@base36x`  | Lowercase Base36 alphabet |
+| `@base62`  | Base62 alphabet           |
+
+## Base64
+
+| Preset       | Description              |
+| ------------ | ------------------------ |
+| `@base64`    | Standard Base64 alphabet |
+| `@base64url` | URL-safe Base64 alphabet |
+
+## Symbols
+
+| Preset      | Characters                  |
+| ----------- | --------------------------- |
+| `@symbols`  | Punctuation and symbols     |
+| `@brackets` | `()[]{}<>`                  |
+| `@quotes`   | Quote characters            |
+| `@math`     | Common mathematical symbols |
 
 ---
 
@@ -347,15 +463,15 @@ Currently available presets:
 Presets can be combined:
 
 ```bash
-python zora.py 32 --charset @letters@digits
+zora 32 --charset @letters@digits
 ```
 
 This creates an alphanumeric character set.
 
-Multiple presets can be combined:
+Multiple presets can also be combined:
 
 ```bash
-python zora.py 32 --charset @upper@lower@digits
+zora 32 --charset @upper@lower@digits
 ```
 
 Duplicate characters are automatically removed.
@@ -368,6 +484,12 @@ For example:
 
 does not contain uppercase characters twice.
 
+The short `-x` form can be used as well:
+
+```bash
+zora 32 -x @upper@lower@digits
+```
+
 ---
 
 ## Custom characters
@@ -377,7 +499,7 @@ Literal characters can be included alongside presets.
 For example:
 
 ```bash
-python zora.py 32 --charset @hexXYZ
+zora 32 --charset @hexXYZ
 ```
 
 This means:
@@ -389,7 +511,7 @@ This means:
 Another example:
 
 ```bash
-python zora.py 32 --charset XYZ@hex
+zora 32 --charset XYZ@hex
 ```
 
 means:
@@ -398,56 +520,55 @@ means:
 X + Y + Z + @hex
 ```
 
-This allows arbitrary character sets without needing to add a new preset.
+This allows arbitrary character sets without requiring a new preset.
 
 ---
 
-# `--charset-list`
+## `--charset-list`
 
-Display the available charset presets:
+Display all available charset presets:
 
 ```bash
-python zora.py --charset-list
+zora --charset-list
 ```
 
+The output includes the preset name and its characters.
+
 Example:
 
 ```text
 Available charsets:
-
-  @digits
-  @letters
-  @lower
-  @upper
-  @hex
-  @oct
-  @bin
-  @special
+  @digits       = 0123456789
+  @letters      = abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
+  @lower        = abcdefghijklmnopqrstuvwxyz
+  @upper        = ABCDEFGHIJKLMNOPQRSTUVWXYZ
+  ...
 
 Use as:
-
   zora --charset @digits
   zora --charset @letters@digits
   zora --charset @hexXYZ
 ```
 
+This mode exits immediately after displaying the available presets.
+
 ---
 
 # Multiple keys
 
-Use `-n` or `--count`:
+Use `-n` or `--count` to generate multiple keys:
 
 ```bash
-python zora.py 32 --count 10
+zora 32 --count 10
 ```
 
 or:
 
 ```bash
-python zora.py 32 -n 10
+zora 32 -n 10
 ```
 
-Zora generates each key independently.
+Each key is generated independently.
 
 When using the secure default generator, each key is generated using the
 cryptographically secure random generator.
@@ -459,7 +580,7 @@ cryptographically secure random generator.
 Add a prefix:
 
 ```bash
-python zora.py 32 --prefix "AUTH_"
+zora 32 --prefix "AUTH_"
 ```
 
 Example:
@@ -471,13 +592,13 @@ AUTH_GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
 Add a suffix:
 
 ```bash
-python zora.py 32 --suffix "_KEY"
+zora 32 --suffix "_KEY"
 ```
 
 Both can be used together:
 
 ```bash
-python zora.py 32 --prefix "AUTH_" --suffix "_KEY"
+zora 32 --prefix "AUTH_" --suffix "_KEY"
 ```
 
 > Prefixes and suffixes are not random and therefore do not contribute to
@@ -492,7 +613,7 @@ Use `--group` to insert a separator every N characters.
 For example:
 
 ```bash
-python zora.py 32 --group 4
+zora 32 --group 4
 ```
 
 Output:
@@ -510,7 +631,7 @@ The default separator is:
 Use `--sep` to change it:
 
 ```bash
-python zora.py 32 --group 4 --sep ":"
+zora 32 --group 4 --sep ":"
 ```
 
 Output:
@@ -524,24 +645,96 @@ entropy.
 
 ---
 
-# File output
+# Output formats
+
+Zora supports multiple output formats through `--format`.
+
+Available formats:
+
+* `text`
+* `json`
+* `csv`
+* `xml`
+* `yml`
+
+The default format is `text`.
 
-Use `-o` or `--output` to write generated keys to a file:
+## Text
 
 ```bash
-python zora.py 32 -n 10 --output keys.txt
+zora 32 --format text
 ```
 
-The generated keys are written one per line.
+This is the default output format.
+
+## JSON
+
+```bash
+zora 32 -n 3 --format json
+```
 
 Example:
 
-```text
-GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr
-aQmXzPjLtVrNsYkBcWdHgFqAeUxRoZiLp
-...
+```json
+{
+  "keys": [
+    "GxKqTnJpYwRzLhBcVfQmNsXeUaPkTdWr",
+    "...",
+    "..."
+  ]
+}
+```
+
+## CSV
+
+```bash
+zora 32 -n 3 --format csv
+```
+
+The generated CSV contains a `key` column.
+
+## XML
+
+```bash
+zora 32 -n 3 --format xml
 ```
 
+## YAML
+
+```bash
+zora 32 -n 3 --format yml
+```
+
+YAML output requires PyYAML:
+
+```bash
+pip install pyyaml
+```
+
+---
+
+# File output
+
+Use `-o` or `--output` to write generated output to a file:
+
+```bash
+zora 32 -n 10 --output keys.txt
+```
+
+The output format can be selected independently:
+
+```bash
+zora 32 -n 10 --format json -o keys.json
+```
+
+```bash
+zora 32 -n 10 --format csv -o keys.csv
+```
+
+Generated files use UTF-8 encoding.
+
+Text-based CLI output uses a conventional final newline.
+
 ---
 
 # Secure generation
@@ -552,7 +745,7 @@ This is the recommended mode when generating authentication tokens,
 API keys, secrets, or other security-sensitive random values.
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 The output will report:
@@ -568,7 +761,7 @@ Generator: CSPRNG
 Use:
 
 ```bash
-python zora.py 32 --unsafe
+zora 32 --unsafe
 ```
 
 to use Python's normal pseudo-random number generator instead of the
@@ -603,7 +796,7 @@ This is intentional.
 The following will fail:
 
 ```bash
-python zora.py 32 --seed example
+zora 32 --seed example
 ```
 
 because Zora's secure generator should not be made deterministic through
@@ -612,7 +805,7 @@ the normal CLI.
 Instead:
 
 ```bash
-python zora.py 32 --unsafe --seed example
+zora 32 --unsafe --seed example
 ```
 
 A seed can be useful for testing reproducibility.
@@ -620,7 +813,7 @@ A seed can be useful for testing reproducibility.
 For example:
 
 ```bash
-python zora.py 32 --unsafe --seed test
+zora 32 --unsafe --seed test
 ```
 
 will produce the same deterministic sequence when run with the same
@@ -631,12 +824,51 @@ rather than being reseeded for every key.
 
 ---
 
+# Benchmarking
+
+Use `--benchmark` to benchmark key generation:
+
+```bash
+zora 32 --benchmark
+```
+
+The benchmark reports:
+
+* Generator
+* Key length
+* Number of keys
+* Charset size
+* Total characters generated
+* Keys per second
+* Characters per second
+
+Example:
+
+```text
+Zora Benchmark
+────────────────────────────────
+Generator: CSPRNG
+Length: 32
+Count: 1
+Charset: 52
+Characters: 32
+Keys/sec: ...
+Characters/sec: ...
+```
+
+Benchmarking does not produce normal key output.
+
+The benchmark respects `--unsafe`, `--seed`, `--count`, and the selected
+charset.
+
+---
+
 # Quiet mode
 
 Use `-q` or `--quiet` to suppress non-essential output:
 
 ```bash
-python zora.py 32 --quiet
+zora 32 --quiet
 ```
 
 This is useful when using Zora inside scripts or shell pipelines.
@@ -644,28 +876,34 @@ This is useful when using Zora inside scripts or shell pipelines.
 For example:
 
 ```bash
-python zora.py 32 --quiet > key.txt
+zora 32 --quiet > key.txt
 ```
 
+Quiet mode suppresses the timer, entropy, strength, generator information,
+and update notification.
+
 ---
 
 # Entropy
 
-Zora calculates the theoretical entropy of the random portion of the
-key.
+Zora calculates the theoretical entropy of the random portion of the key.
 
 The formula is:
 
-$entropy = length \times \log{_2}{(charset size)}$
+```text
+entropy = length × log₂(charset size)
+```
 
 For example, using 52 possible characters:
 
-$32 \times log{_2}\space 52$
+```text
+32 × log₂(52)
+```
 
 produces approximately:
 
 ```text
-182.17 bits
+182.41 bits
 ```
 
 The entropy calculation only considers random characters.
@@ -676,13 +914,13 @@ entropy.
 For example:
 
 ```bash
-python zora.py 32 --prefix "AUTH_"
+zora 32 --prefix "AUTH_"
 ```
 
 has the same theoretical entropy as:
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 assuming the same charset and length.
@@ -720,108 +958,157 @@ PRNG
 
 ---
 
+# Argument validation
+
+Zora validates command-line arguments before generating keys.
+
+Examples of invalid arguments include:
+
+* A key length of `0` or less
+* A key length missing when generation is requested
+* A `--group` value greater than the key length
+* Using `--seed` without `--unsafe`
+* An unknown charset preset
+* An empty final charset
+* A charset containing fewer than two unique characters
+
+Invalid arguments result in a clear command-line error instead of
+attempting to generate invalid output.
+
+---
+
 # Example commands
 
 ### Basic key
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 ### Digits only
 
 ```bash
-python zora.py 32 --charset @digits
+zora 32 -x @digits
 ```
 
 ### Lowercase only
 
 ```bash
-python zora.py 32 --charset @lower
+zora 32 -x @lower
 ```
 
 ### Uppercase only
 
 ```bash
-python zora.py 32 --charset @upper
+zora 32 -x @upper
 ```
 
 ### Alphanumeric
 
 ```bash
-python zora.py 32 --charset @letters@digits
+zora 32 -x @letters@digits
 ```
 
 ### Hexadecimal
 
 ```bash
-python zora.py 32 --charset @hex
+zora 32 -x @hex
 ```
 
 ### Hexadecimal plus custom characters
 
 ```bash
-python zora.py 32 --charset @hexXYZ
+zora 32 -x @hexXYZ
 ```
 
 ### Uppercase, lowercase and digits
 
 ```bash
-python zora.py 32 --charset @upper@lower@digits
+zora 32 -x @upper@lower@digits
+```
+
+### Human-friendly digits
+
+```bash
+zora 32 -x @digitssafe
 ```
 
 ### Symbols
 
 ```bash
-python zora.py 32 --charset @special
+zora 32 -x @symbols
 ```
 
 ### Group the output
 
 ```bash
-python zora.py 32 --group 4
+zora 32 --group 4
 ```
 
 ### Custom separator
 
 ```bash
-python zora.py 32 --group 4 --sep ":"
+zora 32 --group 4 --sep ":"
 ```
 
 ### Generate multiple keys
 
 ```bash
-python zora.py 32 -n 10
+zora 32 -n 10
 ```
 
 ### Save to a file
 
 ```bash
-python zora.py 32 -n 100 -o keys.txt
+zora 32 -n 100 -o keys.txt
+```
+
+### JSON output
+
+```bash
+zora 32 -n 10 --format json
+```
+
+### Benchmark
+
+```bash
+zora 32 --benchmark
+```
+
+### Show available charsets
+
+```bash
+zora --charset-list
+```
+
+### Show version
+
+```bash
+zora --version
 ```
 
 ### Prefix
 
 ```bash
-python zora.py 32 --prefix "AUTH_"
+zora 32 --prefix "AUTH_"
 ```
 
 ### Secure generation
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
 ### Reproducible testing
 
 ```bash
-python zora.py 32 --unsafe --seed test
+zora 32 --unsafe --seed test
 ```
 
 ### Quiet output
 
 ```bash
-python zora.py 32 --quiet
+zora 32 --quiet
 ```
 
 ---
@@ -881,7 +1168,9 @@ random output space.
 For example, a 32-character key selected uniformly from 62 possible
 characters has:
 
-$32 \times log{_2}\space 62$
+```text
+32 × log₂(62)
+```
 
 bits of theoretical entropy.
 
@@ -890,7 +1179,7 @@ However, entropy alone does not prove that a generator is secure.
 For example:
 
 ```bash
-python zora.py 32 --unsafe
+zora 32 --unsafe
 ```
 
 can still report a high entropy value because the theoretical output
@@ -902,8 +1191,8 @@ The generator is nevertheless explicitly marked:
 Generator: PRNG
 ```
 
-and the entropy/strength display is visually marked when `--unsafe` is
-used.
+and the entropy and strength display is visually marked when `--unsafe`
+is used.
 
 ---
 
@@ -925,42 +1214,33 @@ pip install -r requirements.txt
 Run:
 
 ```bash
-python zora.py 32
+zora 32
 ```
 
----
-
-# Project structure
-
-A minimal installation currently looks like:
+For YAML output, install PyYAML:
 
-```text
-Zora/
-├── zora.py
-├── zora.jpg
-├── LICENSE
-├── README.md
-└── requirements.txt
+```bash
+pip install pyyaml
 ```
 
-Future versions may introduce a package structure and automated tests.
-
 ---
 
 # Roadmap
 
 Possible future improvements include:
 
-* [ ] Automated test suite
-* [ ] More charset presets
-* [ ] Better charset parsing errors
+* [x] More charset presets
+* [x] Improved documentation
+* [x] Installation through `pip`
+* [x] Packaging with `pyproject.toml`
+* [x] Better charset parsing errors
+* [x] Multiple output formats
+* [x] Benchmarking mode
+* [x] Version information
+* [x] Argument validation
+* [x] Automated test suite
 * [ ] Configuration files
-* [ ] Packaging with `pyproject.toml`
-* [ ] Installation through `pip`
 * [ ] Shell completion
-* [ ] More output formats
-* [ ] Benchmarking mode
-* [ ] Improved documentation
 * [ ] Cross-platform terminal improvements
 * [ ] API/library usage
 * [ ] More extensive security testing
@@ -980,7 +1260,7 @@ MAJOR.MINOR.PATCH
 For example:
 
 ```text
-v0.1.0
+v0.2.0
 ```
 
 The `0.x` versions indicate that the CLI and features may still change