# 🦅 USER MANUAL (DOXA-SECRET)
**DOXA-SECRET** is a minimalist, local-first command-line text encryption and decryption tool. Designed with security and privacy in mind, it allows you to convert plain text messages into secret, encrypted strings using unique 5-character cipher codes stored locally as JSON files. Written in **Go**, it offers a modern Terminal User Interface (**TUI**) built with Charm's Bubble Tea and Lip Gloss.
---
## TABLE OF CONTENTS
1. [Installation & Execution](#1-installation--execution)
2. [Cipher Architecture & Schema](#2-cipher-architecture--schema)
3. [Interactive Interface & States](#3-interactive-interface--states)
4. [Keyboard Shortcuts Reference](#4-keyboard-shortcuts-reference)
5. [Cipher Distribution & Import/Export](#5-cipher-distribution--importexport)
6. [Uninstallation](#6-uninstallation)
---
## 1. INSTALLATION & EXECUTION
### Prerequisites
Before installing, make sure you have **Go** installed on your system (version **1.20** or higher is recommended).
### Installation Steps (Linux / macOS / FreeBSD)
1. **Clone the repository:**
```bash
git clone https://codeberg.org/Kankys/doxa-secret.git
cd doxa-secret
```
2. **Run the installation script:**
```bash
chmod +x install.sh
./install.sh
```
*The script checks your Go installation, downloads all dependencies, compiles the binary, installs the executable `doxa-secret` to `~/.local/bin/`, and prepares the config directory `~/.doxa-secret/`.*
3. **Add to PATH (if necessary):**
If the `doxa-secret` command is not recognized, add the following line to your shell profile (e.g., `~/.bashrc` or `~/.zshrc`):
```bash
export PATH=$PATH:$HOME/.local/bin
```
Then restart your terminal or reload your profile using `source ~/.bashrc`.
### Post-Installation Cleanup
Once completed, you can safely remove the cloned repository directory:
```bash
rm -rf doxa-secret
```
---
## 2. CIPHER ARCHITECTURE & SCHEMA
All ciphers are stored as JSON files inside the configuration directory `~/.doxa-secret/`.
When the application starts for the first time, a `default.json` cipher is automatically generated.
### Cipher JSON Structure
Each cipher maps basic Latin characters (excluding accents/diacritics, which are automatically normalized to basic Latin to avoid cross-system character encoding issues, and including spaces, commas, periods, numbers) to unique, randomly-generated **5-character alphanumeric codes**:
```json
{
"version": "1.0",
"mappings": {
" ": "k9#pA",
",": "L5z2M",
".": "q7R1o",
"a": "H3nK9",
"b": "8vX1m"
}
}
```
---
## 3. INTERACTIVE INTERFACE & STATES
The application supports multiple interactive states within the Terminal User Interface:
### A. Main Menu
Allows you to choose from three main options:
1. **Write Message**: Compose a plaintext message and save its encrypted output as a `.txt` file into the `~/doxa-secret/export/` directory.
2. **Decrypt Message**: Load an encrypted message from a `.txt` file (placed in the `~/doxa-secret/import/` directory) and read its decrypted contents.
3. **Manage Ciphers**: Create, switch, import, or export cipher keys.
### B. Write Screen
Includes a large message editor field and a filename input field. Switching between these fields is done with the `[Tab]` key. Pressing `[Ctrl+S]` encrypts the message and saves it to `~/doxa-secret/export/`.
### C. Decrypt Screen
Prompts you to enter the name of an encrypted `.txt` file (to be read from `~/doxa-secret/import/`) or an absolute path to a file. The application loads the file, decrypts it using the currently active cipher, and opens a viewport for reading.
---
## 4. KEYBOARD SHORTCUTS REFERENCE
| Key | Context | Action |
|-----|---------|--------|
| `ctrl+c` | Global | Force Quit |
| `l` | Main Menu | Toggle Language (Czech / English) |
| `1` | Main Menu | Open Write Message screen |
| `2` | Main Menu | Open Decrypt/Read Message screen |
| `3` | Main Menu | Open Cipher Management screen |
| `q` / `esc` | Main Menu | Quit application |
| `tab` | Write Screen | Toggle between message content and filename field |
| `ctrl+s` | Write Screen | Save encrypted message to file |
| `esc` | Editor / Forms | Cancel and return to previous menu |
| `up` / `down` / `k` / `j` | Ciphers List | Navigate through ciphers list |
| `enter` | Ciphers List | Activate selected cipher |
| `c` | Ciphers List | Create a new custom cipher |
| `i` | Ciphers List | Import a cipher file |
| `e` | Ciphers List | Export the active cipher file |
| `d` | Ciphers List | Delete the selected cipher |
---
## 5. CIPHER DISTRIBUTION & IMPORT/EXPORT
To share encrypted messages with another person, they must have the exact same cipher JSON file loaded in their `doxa-secret` configuration directory.
### Exporting a Cipher
1. In the **Cipher Management** screen, select the cipher you want to export and make sure it is active.
2. Press `e` to export.
3. Enter the destination path (e.g. `/path/to/my_cipher.json`).
4. Share this file with the recipient.
### Importing a Cipher
1. In the **Cipher Management** screen, press `i` to import.
2. Enter the path to the JSON file you received.
3. The cipher will be automatically validated, copied to your configuration folder, and made active.
---
## 6. UNINSTALLATION
To fully remove the tool and its configuration files from your system, execute:
```bash
rm ~/.local/bin/doxa-secret
rm -rf ~/.doxa-secret
```
*Caution: Deleting `~/.doxa-secret` will permanently erase all your cipher keys.*