doxa/doxa-cli/MANUAL.md

# 🦅 USER MANUAL (DOXA-CLI)

**DOXA-CLI** is a minimalist, local-first command-line notes management tool. It is designed to bring the same philosophy of focus and utility from the web-based [DOXA Notes](https://doxa-notes.org/) into your terminal, utilizing the exact same open JSON data standard without relying on external clouds. Written in **Go**, it offers a modern Terminal User Interface (**TUI**) built with Charm's Bubble Tea and Lip Gloss.

<p align="center">
  <img src="https://img.shields.io/badge/go-1.22+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.22+">
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
  <img src="https://img.shields.io/badge/tested-Linux-brightgreen?style=flat-square" alt="Tested on Linux">
</p> 
<p align="center"> 
   <img src="https://img.shields.io/badge/freebsd-AB2B28?style=for-the-badge&logo=freebsd&logoColor=white" alt="freeBSD">
</p>


---

## TABLE OF CONTENTS
1. [Installation & Execution](#1-installation--execution)
2. [Storage Architecture & Schema](#2-storage-architecture--schema)
3. [Interactive Interface & States](#3-interactive-interface--states)
4. [Keyboard Shortcuts Reference](#4-keyboard-shortcuts-reference)
5. [Export System Details](#5-export-system-details)
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)
1. **Clone the repository:**
   ```bash
   git clone https://codeberg.org/Kankys/doxa-cli.git
   cd doxa-cli
   ```
2. **Run the installation script:**
   ```bash
   chmod +x install.sh
   ./install.sh
   ```
   *The script checks your Go installation, downloads all Go modules, compiles the binary, installs the executable `doxa-cli` to `~/.local/bin/`, and prepares an empty JSON database file at `~/.doxa-cli/doxa_notes.json`.*

3. **Add to PATH (if necessary):**
   If the `doxa-cli` 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-cli
```

# **Operation and installation of doxa-cli on FreeBSD**

Building the application for FreeBSD does not always work correctly, if the instructions below do not help you, you can run it directly from the repository. And in .bashrc, make an alias for `doxa-cli`. You can run the application from the repository directly from the directory where it is cloned with the command `go run .`.

The FreeBSD system has its own specifics - it uses different default shells, kernel module management and interpreter paths than Linux. For a problem-free operation of the application, proceed as follows:

## **1\. Editing the installation script (install.sh)**

Before running the installation, it is necessary to check the header (shebang) of the install.sh script, because FreeBSD strictly requires the correct path to the command interpreter:

> * Open install.sh and make sure that the first line refers to the universal path, not hard-coded to the Linux bash:
```bash
\#\!/usr/bin/env bash
```

## **2\. Running the installation**

Standard cloning and running procedure:

```bash
git clone https://codeberg.org/Kankys/doxa-cli.git
cd doxa-cli
chmod \+x install.sh
./install.sh
rm \-rf doxa-cli
```
*The script will automatically compile the application and place the binary file in the \~/.local/bin/ directory.*

## **3\. Setting the PATH environment variable for FreeBSD (sh shell)**

FreeBSD uses /bin/sh as the default shell, which does not support the source command. To permanently and immediately enable the doxa-cli command, follow these steps:

> 1. **Add the path to the profile:**
```bash
echo 'export PATH="$PATH:$HOME/.local/bin"' \>\> \~/.profile
```
> 2. **Load the changes into the current terminal (using a dot, not the source command):**
```bash
. ~/.profile
```

---

## 2. STORAGE ARCHITECTURE & SCHEMA

The application runs **strictly locally**, keeping all your ideas entirely on your machine.

- **Storage Location:** `~/.doxa-cli/doxa_notes.json` (falls back to a local `doxa_notes.json` in the current working directory if the user home directory cannot be resolved).
- **Backups:** To backup your notes, simply copy `doxa_notes.json` to a backup location regularly.

### JSON Data Structure
Notes are written using a standardized JSON schema, ensuring perfect interoperability with the DOXA web client:
```json
[
  {
    "id": 1722240000000,
    "name": "My Note",
    "content": "Note content with support for multi-line strings.",
    "tags": ["personal", "work"],
    "folder": "", // unused/empty
    "created_at": "2026-07-29T14:30:00Z",
    "modified_at": "2026-07-29T14:35:00Z"
  }
]
```

---

## 3. INTERACTIVE INTERFACE & STATES

The application automatically scales and adjusts to your active terminal window size:

### A. Notes List (Main View) (`StateViewNotes`)
The dashboard displays your list of notes.
- Scroll through notes using the arrow keys or `j`/`k`.
- The selected note expands to display its full content, ID, and tags.
- The bottom bar contains available key shortcuts and a colored status bar showing operation confirmations.

### B. Add / Edit Note Forms (`StateAddNote` / `StateEditNote`)
An interactive form with three inputs:
1. **Name:** (Required) Name of the note.
2. **Content:** (Required) Large multi-line text input.
3. **Tags:** (Optional) Comma-separated list of tags.

*Use the `Tab` or `Shift+Tab` keys to traverse between form inputs.*

### C. Search Field (`StateSearch`)
Allows you to perform a case-insensitive full-text filter on the notes database. Matches are evaluated across names, contents, and tags.

### D. Browse Tags Screen (`StateBrowse`)
A specialized menu that displays a unique collection of all tags currently in use.
- Press `t` to list all tags.
- Select an item and press `Enter` to filter the main note list by your choice.

### E. Delete Confirmation Dialogue (`StateConfirmDelete`)
A safety box showcasing the name and a snippet of the note selected for deletion, requiring a strict `y` (Yes) or `n` (No) keypress to prevent accidental loss of data.

---

## 4. KEYBOARD SHORTCUTS REFERENCE

### Global Commands
| Key | Action |
| :--- | :--- |
| `ctrl + c` | Instantly exit the application from any screen |
| `q` / `esc` | Go back to the previous screen / Cancel current action / Quit application (from the main view) |

### Notes List (Main View) Commands (`StateViewNotes`)
| Key | Action |
| :--- | :--- |
| `↑` / `k` | Move selection up |
| `↓` / `j` | Move selection down |
| `1` | Create a new note |
| `2` / `Enter` | Edit the selected note |
| `3` | Export the selected note to a raw text file |
| `4` | Delete the selected note (requires confirmation) |
| `/` | Start searching |
| `b` | Browse by Tag |
| `l` | Toggle user interface language (CS <=> EN) |

### Form Inputs (Add / Edit Note)
| Key | Action |
| :--- | :--- |
| `Tab` | Move cursor focus to the next field (Name -> Content -> Tags -> Name...) |
| `Shift + Tab` | Move cursor focus to the previous field |
| `Enter` | **Inside Content field:** Inserts a new line (carriage return).<br>**Inside any other field:** Saves/submits the form. |

### Browse Mode (`StateBrowse`)
| Key | Action |
| :--- | :--- |
| `t` | Display **Tags** list |
| `↑` / `k` / `↓` / `j` | Scroll through the items |
| `Enter` | Filter main note list by the selected tag |

---

## 5. EXPORT SYSTEM DETAILS

Pressing key `3` on a note in the main list outputs its contents to a plain `.txt` file:

- **Export Directory:** `~/doxa-cli-txt/` (automatically created).
- **Output Filename:** `<Note_Name>_<ID>.txt` (spaces are automatically escaped into underscores).
- **Exported File Schema:**
  *(Note: The exported header fields are written using Czech labels as hardcoded in the Go export engine).*
  ```text
  Název: <Note Name>
  Tagy: <tag1, tag2, ...>
  Vytvořeno: YYYY-MM-DD HH:MM

  <Full Text Note Content>
  ```

---

## 6. UNINSTALLATION

To fully uninstall DOXA-CLI from your machine:

1. **Remove the executable binary:**
   ```bash
   rm ~/.local/bin/doxa-cli
   ```
2. **Remove the configuration and local database (Warning: This will delete all of your notes!):**
   ```bash
   rm -rf ~/.doxa-cli
   ```