Togo

togo is a command line task/todo management utility designed to be simple, fast, and easy to use.

• Features
• Installation
  • Arch Linux
  • Pre-built Binaries (Recommended)
  • Go CLI
  • Build from Source
• Usage
  • 1. Interactive Mode
  • 2. Command-Line Operations
    • a) Direct selection by partial name
    • b) Interactive selection list
    • c) Shell completion integration
  • Available Commands
• Features in Depth
  • Shell Completion

---

Features

• CLI & TUI Interfaces: A CLI for single-task operations and an interactive TUI for bulk operations and list view. TUI is fully compatible with system default fonts and does not require nerd fonts to be installed
• Vim Keybinds: A handful of Vim actions are built into the TUI (more will be added soon).
• Fuzzy Search & Filtering: Find tasks quickly with partial name matching.
• Tab Completion: Shell completion with fuzzy matching support built into the completion script.
• Project/Global Sources: Load/save from the closest .togo file in the project tree, with a global fallback. Force with --source project|global.

Installation

Arch Linux

togo is available on the Arch User Repository (AUR)

paru -S togo-bin

Pre-built Binaries (Recommended)

Download the latest pre-built binaries from the Releases page.

[!NOTE] Don't forget to set the PATH environment variable.

export PATH="$HOME/.local/bin:$PATH"

Go CLI

go install github.com/prime-run/togo@latest

Build from Source

# Clone the repository
git clone https://github.com/prime-run/togo.git
cd togo
make
# And follow the prompts

All make installation methods should set up shell completion out of the box. In case your shell isn't detected, you can run togo completion --help.

Usage

To add a task:

togo add "Task description"
# or without quotes, it's treated as stdin!
togo add Call the client about project scope

Storage: project vs global

Togo tasks can be loaded/saved in 2 levels:

• project (default): Uses a todos.json file in project directory. Togo searches upward through parent directories to find the nearest todos.json file, creating a hierarchical task structure. If no project file is found, it falls back to the global storage.
• global: Reads personal task file under ~/.config/togo/todos.json.

Control the storage location with the --source flag:

# project (default)
togo list
togo add "Write docs" -s project

# force global
togo list --source global

Initialize project-local storage in current working directory:

togo init   # initializes todos.json file in the current directory (project level)

In the TUI, the header shows the active source as source: project or source: global.

Managing Tasks

Togo provides two primary modes of operation:

1. Interactive Mode (TUI)

The TUI allows managing todos visually and allows for bulk actions:

togo
# or
togo list           # Active todos only
togo list --all     # All todos
togo list --archived # Archived todos only

2. Command-Line Operations

Togo offers flexible command syntax with three usage patterns:

All commands accept the persistent --source|-s flag: project (default) or global.

a) Direct selection by partial name

togo toggle meeting
# force using global source
togo toggle meeting --source global

If only one task contains "meeting," it executes immediately—no selection needed. If multiple tasks match (e.g., "team meeting" and "client meeting"), Togo automatically opens the selection list so you can choose the one you meant.

b) Interactive selection list

togo toggle
# against project-local source explicitly
togo toggle -s project

Opens a selection list where you can choose from available tasks:

As you type, Togo searches through tasks and filters the results.

c) Shell completion integration

If you've configured shell completion (see below), you can use tab-completion:

togo toggle [TAB]

Your shell will present available tasks. Type a few letters to filter by name:

togo toggle me[TAB]

The shell will show only tasks containing "me"—perfect for quick selection.

--source also supports completion to project and global.

[!TIP] This really speeds up task management since fuzzy matching is supported by the completion script. For example, to mark the task Auto ***snapshot*** /boot ... as completed, just running togo toggle snap would toggle it. If snap matches more than one task, you'll be prompted to select from the matches.

Available Commands

• togo add "Task description" - Add a new task
• togo toggle [task] - Toggle completion status
• togo archive [task] - Archive a completed task
• togo unarchive [task] - Restore an archived task
• togo delete [task] - Remove a task permanently
• togo list [flags] - View tasks (--all, --archived)
• togo init - Create an empty todos.json file in the current directory (enable project-local storage)

Notes:

• All commands accept --source|-s {project|global} to control where tasks are read/written.

Features in Depth

Shell Completion

Enabling shell completion allows for tab-completion of commands and task names, improving efficiency.

Zsh

# 1. Create completion directory
mkdir -p ~/.zsh/completion
echo "fpath=(~/.zsh/completion \$fpath)" >> ~/.zshrc

# 2. Enable completions
echo "autoload -Uz compinit && compinit" >> ~/.zshrc

# 3. Apply Togo completion
togo completion zsh > ~/.zsh/completion/_togo
source ~/.zshrc

Bash

# 1. Ensure completion is sourced
echo "[ -r /usr/share/bash-completion/bash_completion ] && . /usr/share/bash-completion/bash_completion" >> ~/.bashrc
source ~/.bashrc

# 2. Install Togo completion
togo completion bash > ~/.bash_completion
source ~/.bash_completion

Fish

mkdir -p ~/.config/fish/completions
togo completion fish > ~/.config/fish/completions/togo.fish

Storage locations:

• Project: nearest ./todos.json file (JSON).
• Global: $XDG_CONFIG_HOME/togo/todos.json (or $HOME/.config/togo/todos.json).

Built With 🔧

License

This project is licensed under MIT - see the LICENSE file for details.