# Command Line Reference Complete reference for the `chaoscrypt` command. ``` chaoscrypt # no arguments -> interactive TUI chaoscrypt [options] # with arguments -> scriptable CLI ``` The same behaviour is available as `python -m chaoscrypt`. --- ## Global options These apply before the subcommand. | Option | Description | |---|---| | `-h`, `--help` | Show help and exit | | `-V`, `--version` | Show the version and exit | | `-j`, `--json` | Emit machine-readable JSON on stdout | | `-q`, `--quiet` | Suppress non-essential human-readable output | ```bash chaoscrypt --version chaoscrypt --json info -k my.key -P keypass ``` **Exit codes** | Code | Meaning | |---|---| | `0` | Success | | `1` | Runtime error — a `ChaosCryptError` was raised | | `2` | Usage error — argument parsing failed | --- ## Password options Every command that needs a password accepts three forms of each. The pattern repeats for the **encryption password** and the **key file password**: | Encryption password | Key file password | Source | |---|---|---| | `-p`, `--pwd PWD` | `-P`, `--key-pwd PWD` | Inline on the command line | | `--pwd-env VAR` | `--key-pwd-env VAR` | Environment variable `VAR` | | `--pwd-file PATH` | `--key-pwd-file PATH` | Last non-empty line of `PATH` | Precedence is inline, then environment, then file. The password file form reads the **last non-empty line**, so a trailing newline is harmless: ```bash echo 'correct horse battery staple' > ~/.cc-encryption-pwd chaoscrypt encrypt "data" --pwd-file ~/.cc-encryption-pwd -k my.key -P keypass ``` > **Distinguish the two passwords.** `-p`/`--pwd` is the *encryption > password* protecting your data. `-P`/`--key-pwd` is the *key file password* > that unlocks the key file. They are independent, and you need both. Inline passwords appear in shell history. Prefer an environment variable or a password file, particularly on shared systems. --- ## `chaoscrypt keygen` Generate a new key file. ``` chaoscrypt keygen [-k PATH] [-f] [-P PWD | --key-pwd-env VAR | --key-pwd-file PATH] ``` | Option | Description | |---|---| | `-k`, `--key-file PATH` | Output path (default `encryption.key`) | | `-f`, `--force` | Overwrite an existing file | ```bash chaoscrypt keygen -k my.key -P "key-file-password" chaoscrypt keygen -k my.key --key-pwd-env CC_KEY_PWD -f ``` Output: ``` Key file created: /home/user/my.key ``` With `--json`: ```json { "ok": true, "key_file": "/home/user/my.key" } ``` --- ## `chaoscrypt encrypt` Encrypt a string into a hexadecimal ciphertext. ``` chaoscrypt encrypt [TEXT] [-i PATH] [-o PATH] [-k PATH] [-p PWD | --pwd-env VAR | --pwd-file PATH] [-P PWD | --key-pwd-env VAR | --key-pwd-file PATH] ``` | Argument | Description | |---|---| | `TEXT` | Plaintext. Use `-` or omit to read from stdin | | `-i`, `--in PATH` | Read plaintext from a file | | `-o`, `--out PATH` | Write ciphertext to a file instead of stdout | | `-k`, `--key-file PATH` | Key file (default `encryption.key`) | ```bash # Direct chaoscrypt encrypt "hello world" -p mypass -k my.key -P keypass # From a file chaoscrypt encrypt -i note.txt -p mypass -k my.key -P keypass # Into a file chaoscrypt encrypt "hello" -o out.cc -p mypass -k my.key -P keypass # From stdin echo "hello" | chaoscrypt encrypt - -p mypass -k my.key -P keypass ``` --- ## `chaoscrypt decrypt` Decrypt a hexadecimal ciphertext back into text. ``` chaoscrypt decrypt [TEXT] [-i PATH] [-o PATH] [-k PATH] [-p PWD | --pwd-env VAR | --pwd-file PATH] [-P PWD | --key-pwd-env VAR | --key-pwd-file PATH] ``` Options are identical to `encrypt`. ```bash chaoscrypt decrypt "516a0410..." -p mypass -k my.key -P keypass chaoscrypt decrypt -i ciphertext.cc -p mypass -k my.key -P keypass chaoscrypt decrypt - -p mypass -k my.key -P keypass < ciphertext.cc ``` A wrong password, a mismatched key file, or an altered ciphertext all raise `ChaosCrypt_ERR_DecryptionFailed_E011` and exit with code `1`. --- ## `chaoscrypt file` Encrypt and decrypt whole files. Binary-safe: the input is read as raw bytes, so images, archives and executables are handled correctly. ### `chaoscrypt file encrypt` ``` chaoscrypt file encrypt SRC [-o PATH] [-k PATH] [password options] ``` Writes UTF-8 hexadecimal ciphertext. Without `-o`, the output path is `SRC.cc`. ```bash chaoscrypt file encrypt photo.png -p mypass -k my.key -P keypass # -> photo.png.cc ``` ### `chaoscrypt file decrypt` ``` chaoscrypt file decrypt SRC [-o PATH] [-k PATH] [password options] ``` Without `-o`, a trailing `.cc` is stripped. ```bash chaoscrypt file decrypt photo.png.cc -p mypass -k my.key -P keypass # -> photo.png chaoscrypt file decrypt data.cc -o restored.bin -p mypass -k my.key -P keypass ``` --- ## `chaoscrypt info` Show key file metadata. Substitution tables are redacted unless you ask for them explicitly. ``` chaoscrypt info [-k PATH] [--show-maps] [-P PWD | --key-pwd-env VAR | --key-pwd-file PATH] ``` | Option | Description | |---|---| | `--show-maps` | Also print the substitution tables (sensitive) | ```bash chaoscrypt info -k my.key -P keypass ``` ``` ============================================================== ChaosCrypt key information ============================================================== key_file : my.key version : 1 upper_mapping : lower_mapping : digit_mapping : equal_mapping : flip_pattern : [1, 0, 1, 0, 0, 1, 0, 0, 1, 0] long_key_length : 4096 short_key_length : 512 loaded : True ============================================================== ``` The substitution tables describe the structure of your key file. Only use `--show-maps` when you are certain the output is not being logged or displayed publicly. --- ## `chaoscrypt chpwd` Change the key file password. The key material is unchanged, so previously encrypted data remains readable. ``` chaoscrypt chpwd [-k PATH] [-P PWD | --key-pwd-env VAR | --key-pwd-file PATH] [--new-pwd PWD | --new-pwd-env VAR | --new-pwd-file PATH] ``` ```bash chaoscrypt chpwd -k my.key -P oldpass --new-pwd newpass chaoscrypt chpwd -k my.key -P oldpass --new-pwd-env CC_NEW_KEY_PWD ``` --- ## `chaoscrypt tui` Launch the interactive interface. Identical to running `chaoscrypt` with no arguments. ```bash chaoscrypt tui ``` --- ## JSON output Every command supports `--json`, which prints a single JSON object on stdout and reports errors as JSON on stderr. This is the recommended mode for scripts and integration. ```bash chaoscrypt --json encrypt "data" -p pw -k my.key -P kp ``` ```json { "ok": true, "mode": "encrypt", "ciphertext": "516a0410415613117b10770111604074..." } ``` On failure: ```json { "ok": false, "error": "ChaosCrypt_ERR_DecryptionFailed_E011", "code": "E011" } ``` Parsing with `jq`: ```bash CT=$(chaoscrypt --json encrypt "data" -p pw -k my.key -P kp | jq -r .ciphertext) chaoscrypt decrypt "$CT" -p pw -k my.key -P kp ``` --- ## Pipelines The CLI composes cleanly with standard shell tools. `TEXT` set to `-`, or omitted entirely, reads from stdin; the absence of `-o` writes to stdout. ```bash # Encrypt a tar stream without touching disk. tar czf - ./project | chaoscrypt encrypt - -p pw -k my.key -P kp > project.tgz.cc # Restore it. chaoscrypt decrypt - -p pw -k my.key -P kp < project.tgz.cc | tar xzf - -C ./restored # Encrypt every .txt file in a directory. for f in *.txt; do chaoscrypt file encrypt "$f" -p pw -k my.key -P kp done ``` --- ## Shell completion Bash, added to `~/.bashrc`: ```bash _chaoscrypt_complete() { local commands="keygen encrypt decrypt file info chpwd tui" COMPREPLY=( $(compgen -W "$commands" -- "${COMP_WORDS[COMP_CWORD]}") ) } complete -F _chaoscrypt_complete chaoscrypt ``` PowerShell, added to your profile: ```powershell Register-ArgumentCompleter -Native -CommandName chaoscrypt -ScriptBlock { param($wordToComplete) 'keygen','encrypt','decrypt','file','info','chpwd','tui' | Where-Object { $_ -like "$wordToComplete*" } } ``` --- ## Examples ### First-time setup ```bash chaoscrypt keygen -k ~/.chaoscrypt/prod.key --key-pwd-env CC_KEY_PWD mkdir -p ~/.chaoscrypt echo 'my-encryption-password' > ~/.chaoscrypt/pwd chmod 600 ~/.chaoscrypt/pwd ``` ### Daily use ```bash alias ccenc='chaoscrypt encrypt --pwd-file ~/.chaoscrypt/pwd \ -k ~/.chaoscrypt/prod.key --key-pwd-env CC_KEY_PWD' alias ccdec='chaoscrypt decrypt --pwd-file ~/.chaoscrypt/pwd \ -k ~/.chaoscrypt/prod.key --key-pwd-env CC_KEY_PWD' ccenc "sensitive note" echo "note" | ccenc - ``` ### Backing up a directory ```bash tar czf - ./documents \ | chaoscrypt encrypt - --pwd-file ~/.chaoscrypt/pwd \ -k ~/.chaoscrypt/prod.key --key-pwd-env CC_KEY_PWD \ > documents-$(date +%F).tgz.cc ``` ### Rotating the key file password ```bash chaoscrypt chpwd -k ~/.chaoscrypt/prod.key \ -P "$OLD_KEY_PWD" --new-pwd "$NEW_KEY_PWD" ``` --- ## Troubleshooting | Symptom | Cause | Resolution | |---|---|---| | `ChaosCrypt_ERR_KeyFileNotFound_E001` | Wrong key file path | Check `-k` and the working directory | | `ChaosCrypt_ERR_KeyPasswordIncorrect_E003` | Wrong key file password | Verify the `-P` value | | `ChaosCrypt_ERR_DecryptionFailed_E011` | Wrong encryption password, mismatched key file, or altered ciphertext | Confirm `-p`, `-k` and that the ciphertext is intact | | `ChaosCrypt_ERR_MalformedCiphertext_E010` | Ciphertext is not valid hexadecimal, or has an odd length | Check for truncation or stray whitespace | | `ChaosCrypt_ERR_EmptyPassword_E006` | No password supplied | Provide one of the three password forms | | `ChaosCrypt_ERR_InvalidArgument_E013` | Environment variable unset, or password file unreadable | Verify the variable is exported and the file is readable | | Exit code `2` with usage text | Argument parsing failed | Run `chaoscrypt --help` | Because the CLI reports the error class in the message, you can branch on the code rather than parsing prose: ```bash if ! chaoscrypt decrypt "$CT" -p pw -k my.key -P kp; then case "$?" in 1) echo "check your passwords and key file" ;; 2) echo "check the command syntax" ;; esac fi ```