roy-tty-cli

ROY-TTY

A terminal based todo app, built from scratch to understand how cli tools actually work under the hood.

Why this exists

I built this not because i needed another todo app but because i wanted to understand things. Things like how a cli command gets installed globally on a machine, how npm publishing works, how you can persist data without touching a database, and how terminal ui libraries behave when you actually use them in a real project.

This is not a product. It is a learning artifact.

Everything runs inside your terminal and everything gets saved to a local json file on your system. No server. No cloud. No account.

What it can do

Add tasks from the command line directly or through an interactive menu.

List everything with category grouping and current status so you can see whats done and whats still pending.

Toggle task state between done and pending whenever you need to.

Delete tasks cleanly from the list.

Organize by category so tasks like backend work, dsa practice, and system design stuff dont all pile into the same undifferentiated list.

Check your stats to see a simple progress breakdown of how many tasks you have finished.

Interactive mode gives you a menu driven interface inside the terminal using inquirer so you dont have to remember any commands.

Direct cli mode lets you just fire commands if you know what you want.

How to install

npm install -g roy-tty-cli

How to use it

Run it without any arguments to open interactive mode:

roy-tty

Or use it directly from the command line:

roy-tty add "finish the auth module"
roy-tty list
roy-tty list --done
roy-tty list --pending
roy-tty list --category backend
roy-tty done 1
roy-tty delete 1

Where your data lives

All your tasks are stored in a single json file at:

~/.roy-tty/todos.json

Nothing leaves your machine. Its just the node fs module reading and writing a file. Thats the entire database layer.

How its structured

index.js      entry point, wires up the cli
menu.js       interactive mode and the inquirer ui
commands.js   all the actual command logic lives here
store.js      the file based data layer
ui.js         terminal rendering and table formatting

What this project actually is

This is not production ready and it was never meant to be. No sync, no auth, no cloud backup, no fancy error handling for edge cases that probably dont matter.

What it does do is show how all these pieces fit together. The bin field in package.json, how global commands work, how inquirer handles menu interactions, how chalk styles terminal output, how you can build something genuinely usable with just node and a handful of libraries.

If you are trying to understand how cli tools work from first principles, the codebase is intentionally small enough to read in one sitting.

Tech used

• Node.js
• inquirer
• chalk
• figlet
• cli-table3
• fs module