nerv

Nerv

Nerv is a small terminal todo application written in Go.

There are already a lot of todo apps, but this project exists for a more personal reason: building a custom one makes it easy to change the workflow, behavior, and interface whenever needed. It is also a learning project for practicing Go and improving by building something useful from scratch.

Features

• Add todo items from the command line.
• List todo items by status.
• Toggle tasks between todo and done.
• Remove tasks by ID.
• Use interactive terminal views when toggling or removing without IDs.
• Store tasks locally in ~/.local/share/nerv/tasks.json.

Requirements

• Go 1.26.3 or newer, based on the version in go.mod.

Installation

Clone the repository and build the binary:

go build -o nerv .

Run it from the project directory:

./nerv --help

You can also run it directly without building:

go run . --help

Usage

Usage: nerv <command>

Flags:
  -h, --help    Show context-sensitive help.

Commands:
  add <task> ...
    Add a new task

  list [<filter>]
    List all tasks

  toggle [<ids> ...]
    Toggle the status of tasks

  rm [<ids> ...]
    Remove tasks

Run "nerv <command> --help" for more information on a command.

Commands

add

Adds a new task.

nerv add Buy milk

The full text after add becomes the task description.

Usage: nerv add <task> ...

Add a new task

Arguments:
  <task> ...    Task description

list

Lists tasks. The optional filter can be todo, done, or all.

nerv list
nerv list todo
nerv list done
nerv list all

If no filter is provided, Nerv lists todo tasks by default.

Usage: nerv list [<filter>]

List all tasks

Arguments:
  [<filter>]    Filter listing

toggle

Toggles tasks between todo and done.

nerv toggle 1
nerv toggle 1 3 4

If you run toggle without IDs, Nerv opens an interactive terminal view where you can select tasks.

nerv toggle

Interactive controls:

• space or enter: toggle the selected task
• q or ctrl+c: quit

Usage: nerv toggle [<ids> ...]

Toggle the status of tasks

Arguments:
  [<ids> ...]    IDs of tasks to toggle

rm

Removes tasks by ID.

nerv rm 2
nerv rm 1 3 5

If you run rm without IDs, Nerv opens an interactive terminal view where you can mark tasks for removal.

nerv rm

Interactive controls:

• space or enter: mark or unmark the selected task for removal
• q or ctrl+c: quit and remove the marked tasks

Usage: nerv rm [<ids> ...]

Remove tasks

Arguments:
  [<ids> ...]    IDs of tasks to remove

Data

Tasks are saved in ~/.local/share/nerv/tasks.json by default, or under $XDG_DATA_HOME/nerv/tasks.json when XDG_DATA_HOME is set. Each task stores:

• desc: the task description
• done: whether the task is completed

Example:

[
  {
    "desc": "Buy milk",
    "done": false
  }
]

Tech Stack

• Go
• Kong for CLI parsing
• Bubble Tea and Bubbles for interactive terminal views
• Lip Gloss for terminal styling