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 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.

---

TABLE OF CONTENTS

1. Installation & Execution
2. Storage Architecture & Schema
3. Interactive Interface & States
4. Keyboard Shortcuts Reference
5. Export System Details
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:

   git clone https://codeberg.org/Kankys/doxa-cli.git
   cd doxa-cli
   

2. Run the installation script:

   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):

   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:

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:

\#\!/usr/bin/env bash

2. Running the installation

Standard cloning and running procedure:

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:

echo 'export PATH="$PATH:$HOME/.local/bin"' \>\> \~/.profile

2. Load the changes into the current terminal (using a dot, not the source command):

. ~/.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:

[
  {
    "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). 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).

  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:

   rm ~/.local/bin/doxa-cli
   

2. Remove the configuration and local database (Warning: This will delete all of your notes!):

   rm -rf ~/.doxa-cli