Build a CLI with Tea

You already know how to program. Now you want to find out what writing a real program in Tea feels like. In this tutorial, you'll build a small command-line task list from an empty file, adding one useful feature at a time.

By the end, you'll be able to do this:

./bin/tasks add "Learn Tea"
./bin/tasks add "Build something useful"
./bin/tasks done 1
./bin/tasks list --all

Starting with an empty list, the final command prints:

1. [x] Learn Tea
2. [ ] Build something useful

Your tasks survive between runs in a local text file. You'll also have tests for the program's logic and a native executable you can run on a compatible machine.

Before you begin

You should be comfortable editing a text file and running commands in a terminal. We'll assume you know what variables, loops, and functions are, but explain Tea's spelling and behavior as they appear.

Install Tea, including the host C toolchain described there, then check your installation:

tea --version

Create a directory just for this project:

mkdir tea-tasks
cd tea-tasks

Run the tutorial commands from this directory. You'll start with tasks.tea; later you'll add tasks.txt for data and task_list.tea for reusable code. You do not need to clone the Tea repository.

How to follow along

Each chapter starts from the previous chapter's finished program. Read the explanation, make the changes, and run the command shown. The complete source at the end of a chapter is a recovery point: you can copy it over your files if you get stuck. Longer listings are expandable.

Commands and their output appear in separate blocks, so you can copy a command without copying a shell prompt. Sample output assumes you've followed the steps in order. Each chapter also has a small optional exercise; the next chapter always starts from the main walkthrough, not your exercise solution.

The first four chapters work with sample tasks in memory. From chapter 5 onward, the program reads tasks.txt in your current directory. We'll make that transition explicitly so you know which data you're looking at.

Your route through the project

1. 1. Display your first task

   Run a Tea file and turn a binding into useful output.

2. 2. Display several tasks

   Use a list and a loop to number your tasks.

3. 3. Track task status

   Model tasks with structs and format them with a function.

4. 4. Accept commands

   Read arguments, filter tasks, and explain how to use the tool.

5. 5. Read saved tasks

   Load a text file and handle failures with typed errors.

6. 6. Add tasks

   Validate a title and save a new task between runs.

7. 7. Complete tasks

   Find a task by number and update its status safely.

8. 8. Organize and test

   Extract a module and test the logic behind your CLI.

9. 9. Build your executable

   Check, format, and compile the finished tool.

What you'll have learned

You'll use bindings, lists, loops, functions, structs, imports, typed errors, file operations, and tests in one program. Follow the reference links when you want more detail. You can explore generics, lambdas, and the rest of the standard library after you've finished your first tool.

This is a local, single-user task list. Features such as deletion, due dates, and concurrent writers are useful follow-up projects, rather than prerequisites for learning Tea.