taskwarrior-tui

taskwarrior-tui is a state-driven terminal user interface built with ratatui.

Core Logic Flow:

1. Input: Keyboard events are read asynchronously and communicated via channels.
2. State Management: Most application logic resides in src/app.rs. Key press actions are handled by app.handle_input(&mut self, input: Key).
3. Rendering: The TUI renders the difference between the previous state and the current state every Tick. UI rendering is performed by various app.draw_... functions.

To begin using taskwarrior-tui, follow this recommended workflow:

1. Installation: Set up the application using your preferred package manager.
2. Quick Start: Follow the first-run workflow to get your environment ready.
3. Default Keybindings: Familiarize yourself with the built-in keyboard-first controls.

For more complex setups, you can explore Advanced Configuration for style and behavior options, or consult the Troubleshooting guide if you encounter issues with logs, timing, or path isolation.

To install taskwarrior-tui using pre-compiled binaries:

1. Ensure you have the latest version of taskwarrior installed on your system.
2. Download the .tar.gz file corresponding to your operating system from the latest release page.
3. Unzip the downloaded file.
4. Execute the binary using ./taskwarrior-tui.

The documentation site is built using Starlight/Astro and lives in the docs/ directory.

• Build the docs site locally:

  mise run taskwarrior-tui:docs-build

- **Start a local preview server** (for iterative work):
  ```bash
mise run taskwarrior-tui:docs-preview

• Regenerate the man page:

  mise run taskwarrior-tui:man

You can build the CLI using standard cargo commands:

• Debug Build:

  cargo build

- **Release Build**:
  ```bash
cargo build --release

To run the application in debug mode:

cargo run

To run the application in release mode:

cargo run --release

This project uses mise to manage its toolchain and environment. Follow these steps to install and activate it:

1. Install mise:

   curl https://mise.run | sh

2. Activate mise in your shell:

   • zsh:

     echo 'eval "$(mise activate zsh)"' >> "${ZDOTDIR-$HOME}/.zshrc"

   • bash:

     echo 'eval "$(mise activate bash)"' >> ~/.bashrc

   • fish:

     echo 'mise activate fish | source' >> ~/.config/fish/config.fish

3. Install project tools: Restart your shell, then run:

   mise install

Once activated, mise automatically handles pinned values (like Taskwarrior source tags and testdata refs) defined in .config/mise.toml.

To install taskwarrior-tui manually, download the appropriate tar.gz file for your operating system from the latest releases page. Once downloaded, unzip the file and execute the binary directly.

Prerequisite: You must have taskwarrior installed on your system before installing taskwarrior-tui.

Arch Linux users have two primary options:

1. Official Extra Repository: Use pacman to install the package directly.
2. AUR (Arch User Repository): Use an AUR helper like yay to install the -git version of the package.

Prerequisite: taskwarrior must be installed.

If you want to build the project from the source code using Cargo, clone the repository and run the build command with the --release flag. This requires the Rust toolchain to be installed.

git clone https://github.com/kdheepak/taskwarrior-tui.git
cd taskwarrior-tui
cargo build --release

You can map keys 1-9 to custom executable scripts by defining them in your taskrc using uda.taskwarrior-tui.shortcuts.N (where N is 1-9).

When a shortcut is triggered, the script is executed with the selected_tasks_uuid passed as the first argument.

Steps to implement:

1. Create a script (e.g., ~/.config/taskwarrior-tui/shortcut-scripts/my-script.sh).
2. Ensure the script is executable: chmod +x /path/to/script.
3. Add a shebang to the script (e.g., #!/usr/bin/env bash).
4. Reference the script in taskrc.
5. (Optional) Remap the shortcut key using uda.taskwarrior-tui.keyconfig.shortcut1=<key>.

uda.taskwarrior-tui.shortcuts.1=~/.config/taskwarrior-tui/shortcut-scripts/add-personal-tag.sh

# Example script content:
task rc.bulk=0 rc.confirmation=off rc.dependency.confirmation=off rc.recurrence.confirmation=off "$@" modify +personal

To run the full test suite, use the mise task runner. This command automatically fetches taskwarrior-testdata at a pinned commit to ensure deterministic test results.

mise run taskwarrior-tui:cargo-test