doxa/doxa-todo/MANUAL.md

DOXA-TODO User Manual

Introduction

DOXA-TODO is a terminal-based todo manager that helps you organize your tasks with support for categories, priorities, and tags. This manual provides detailed information about all features and usage patterns.

Getting Started

First Run

When you run doxa-todo for the first time:

1. The application creates a configuration directory at ~/.doxa-todo/
2. An empty todo list file doxa_todo.json is created
3. You're presented with the startup screen

Press Enter to start using the application.

Main Interface

The main interface displays:

• Application title
• Status messages (if any)
• Menu options
• List of todos
• Help information

Menu Options

• 1: Add - Add a new todo
• 2: Edit - Edit the selected todo
• 3: Export - Export the selected todo to a text file
• 4: Delete - Delete the selected todo
• /: Search - Search todos by title, description, or tags
• b: Tags - Browse all tags
• c: Filter - Filter todos by category
• l: EN/CS - Toggle language between English and Czech
• q: Quit - Exit the application

Adding a Todo

1. Press 1 to add a new todo
2. Fill in the fields:
   • Title (required): The name of your todo
   • Description (optional): Detailed description
   • Tags (optional): Comma-separated list of tags
3. The todo is automatically assigned:
   • Medium priority
   • Personal category
   • Current timestamp
4. Press Enter to save (when not in description field)
5. Use + key to cycle through priority levels

Editing a Todo

1. Navigate to the todo you want to edit using ↑/↓ or j/k
2. Press 2 to edit
3. Modify the fields as needed
4. Press Enter to save changes

Priority Levels

Todos have 3 priority levels with color coding:

• Low (Green ●): For tasks that can wait
• Medium (Orange ●): Default priority for new tasks
• High (Red ●): For urgent tasks

Use the + key when adding/editing to cycle through priority levels.

Categories

Todos can be categorized as:

• Personal (🏠 Blue): For personal tasks
• Work (💼 Purple): For work-related tasks

Filtering by Category

1. Press c to open the category filter
2. Select:
   • 1: Show only Personal todos
   • 2: Show only Work todos
   • 0: Show all todos (remove filter)
3. The filter remains active until you change it or clear it

Tags

Tags help you organize and find todos quickly.

Adding Tags

When adding or editing a todo, enter comma-separated tags in the Tags field:

work, urgent, project-x

Browsing Tags

1. Press b to browse all tags
2. Navigate with ↑/↓ or j/k
3. Press Enter to filter todos by the selected tag
4. Press q or Esc to return to the main list

Searching

1. Press / to open search
2. Type your search query
3. Press Enter to search
4. The list will show only todos matching your query in title, description, or tags
5. Press Esc to clear the search

Viewing a Todo

1. Navigate to the todo using ↑/↓ or j/k
2. Press Enter to view details
3. In the detail view:
   • q: Close and return to list
   • 2: Edit the todo
   • ↑/↓: Scroll the content

Exporting a Todo

1. Select the todo you want to export
2. Press 3 to export
3. The todo is saved as a text file in ~/doxa-todo-export/
4. The filename format is: {title}_{id}.txt

The exported file contains:

• Title
• Category
• Priority
• Tags
• Creation date
• Description

Deleting a Todo

1. Select the todo you want to delete
2. Press 4 to open delete confirmation
3. Press y to confirm deletion
4. Press n or Esc to cancel

Keyboard Shortcuts Summary

Navigation

• ↑/↓ or j/k: Move cursor up/down
• Enter: Select/Confirm
• Esc: Go back/Cancel
• q: Quit

Actions

• 1: Add new todo
• 2: Edit selected todo
• 3: Export selected todo
• 4: Delete selected todo
• /: Search
• b: Browse tags
• c: Filter by category
• l: Toggle language
• +: Increase priority (when adding/editing)
• Tab: Switch between fields

Data Storage

All todos are stored in JSON format at:

~/.doxa-todo/doxa_todo.json

The file is automatically created on first run and updated with every change.

Backup

To backup your todos:

cp ~/.doxa-todo/doxa_todo.json ~/.doxa-todo/doxa_todo_backup.json

Restore

To restore from backup:

cp ~/.doxa-todo/doxa_todo_backup.json ~/.doxa-todo/doxa_todo.json

Export Directory

Exported todos are saved to:

~/doxa-todo-export/

Each exported file contains the complete todo information in a readable text format.

Troubleshooting

Application doesn't start

Make sure you have:

1. Go installed (version 1.26+)
2. The application compiled and installed
3. ~/.local/bin in your PATH

Todos not saving

Check:

1. Write permissions for ~/.doxa-todo/
2. The directory exists
3. No errors are displayed when saving

Language not switching

Make sure you're pressing l from the main todo list view, not from other screens.

Command Line Usage

Basic Usage

doxa-todo

Running from source

cd doxa-todo
go run .

Configuration

The application uses the following directories:

• ~/.doxa-todo/: Configuration and data storage
• ~/doxa-todo-export/: Exported todos

You can modify the source code to change these paths if needed.

Updates

To update to the latest version:

cd doxa-todo
git pull origin master
go build -o doxa-todo .
cp doxa-todo ~/.local/bin/

Uninstall

To uninstall:

rm ~/.local/bin/doxa-todo
rm -rf ~/.doxa-todo/
rm -rf ~/doxa-todo-export/

License

MIT License - Copyright (c) 2026 Kankys

Support

For issues, questions, or contributions, please visit the project repository: https://codeberg.org/Kankys/doxa-todo