CLI Task Manager

Build a command-line to-do app that reads and writes tasks to a JSON file.

StructsFile I/OJSON

Overview

A CLI task manager is the project where Go's explicit, no-surprises philosophy first becomes obvious: there is no exception system to silently swallow a missing file, no implicit constructor doing hidden work behind your back. A `Task` is a plain `struct` — a handful of named fields with no behavior baked into the type itself — and every operation that can go wrong, from opening a file to parsing JSON, returns an `error` value that the calling code must check explicitly with `if err != nil`. Nothing happens by accident in Go, and this project is small enough to feel that discipline in every function you write.

By the end of this tutorial you will have a command-line application that stores its to-do list as a JSON file on disk, using Go's `encoding/json` package to marshal a slice of `Task` structs into readable JSON and unmarshal it straight back into memory on the next run. You will also see the idiomatic Go pattern of returning `(value, error)` pairs from nearly every function, and why that convention exists in a language with no `try`/`catch` at all.

What You'll Build

A `Task` struct with `ID`, `Title`, and `Done` fields, tagged for JSON serialization.
A `loadTasks()` function that reads `tasks.json` and unmarshals it into a `[]Task`.
A `saveTasks()` function that marshals the current `[]Task` back to `tasks.json`.
An `addTask()` function that appends a new task and assigns it the next unused id.
A `completeTask()` function that marks a task done by id, and a `deleteTask()` that removes one.
A menu-driven command loop tying every operation together into one running program.

Prerequisites

Structs — defining a `struct` with named, typed fields and struct tags.
Slices — `append()`, indexing, and looping with `for range`.
Error handling — functions returning `(T, error)` and the `if err != nil` check.
The `encoding/json` package — `json.Marshal` and `json.Unmarshal`.
Basic file I/O — `os.ReadFile` and `os.WriteFile`.

Project Structure

The whole program lives in a single file, `main.go`, in package `main`. A `Task` struct models one to-do item, and every function that touches the task list — `loadTasks`, `saveTasks`, `addTask`, `completeTask`, `deleteTask` — operates on a `[]Task` slice passed in and, where the list changes shape, returned back out. Go slices are not pointers to a fixed collection the way a Java `ArrayList` reference is; `append()` can return a slice backed by an entirely new underlying array, so every function that adds or removes a task returns the updated `[]Task` rather than mutating one in place.

`main()` owns the one long-lived copy of the task slice and the menu loop around it. Every helper function is stateless — it takes the current slice as an argument and returns the next one — which keeps the file-load/file-save boundary in exactly two places instead of scattered across every command.

Step 1: Define the Task Struct

Each field name starts with an uppercase letter, which in Go is not a style preference — it is what makes a field exported (visible outside the package, and to `encoding/json`). The backtick-delimited string after each field is a struct tag; `json:"id"` tells `encoding/json` to use the lowercase key `"id"` in the JSON output instead of the Go field name `ID`, which is the idiomatic way to keep Go's exported-field capitalization convention separate from conventional lowercase JSON keys.

package main

// Task represents one to-do item. Fields must start with an uppercase
// letter to be "exported" — visible to other packages and, critically,
// to encoding/json, which only ever sees exported fields.
type Task struct {
	ID    int    `json:"id"`    // Unique, auto-incrementing id assigned by addTask()
	Title string `json:"title"` // What the task is
	Done  bool   `json:"done"`  // Whether the task has been completed
}

Step 2: Load and Save Tasks as JSON

`loadTasks()` reads the raw bytes of `tasks.json` with `os.ReadFile`, then hands them to `json.Unmarshal` to decode into a `[]Task`. The very first run of the program has no file yet, so `loadTasks()` treats `os.IsNotExist(err)` as "start with an empty list" rather than a fatal error — every other read error is still returned up to the caller, since silently ignoring a corrupt or unreadable file would be worse than crashing loudly.

import (
	"encoding/json" // Marshal/Unmarshal between []Task and JSON bytes
	"os"            // ReadFile/WriteFile for the tasks.json file
)

// loadTasks reads tasks.json and decodes it into a []Task. A missing file
// is treated as "no tasks yet" rather than an error, since that is exactly
// the state of a brand-new install that has never saved anything.
func loadTasks(filename string) ([]Task, error) {
	data, err := os.ReadFile(filename)
	if err != nil {
		if os.IsNotExist(err) { // First run: no file yet is expected, not an error
			return []Task{}, nil
		}
		return nil, err // Any other read failure (permissions, etc.) is a real error to report
	}

	var tasks []Task
	if err := json.Unmarshal(data, &tasks); err != nil { // &tasks: Unmarshal writes into the slice via a pointer
		return nil, err
	}
	return tasks, nil
}

// saveTasks encodes the current task list as indented JSON and writes it
// to filename, overwriting whatever was there before.
func saveTasks(filename string, tasks []Task) error {
	data, err := json.MarshalIndent(tasks, "", "  ") // Indented output so tasks.json stays human-readable
	if err != nil {
		return err
	}
	return os.WriteFile(filename, data, 0644) // 0644: owner read/write, everyone else read-only
}

Example Usage

Click Run to see what this code prints.

Step 3: Add and List Tasks

`addTask()` computes the next id by scanning the existing tasks for the current maximum rather than just using `len(tasks)+1` — that way, ids stay unique even after a task with a high id has been deleted, instead of a new task accidentally reusing a freed slot's id. It returns the updated `[]Task`, since `append()` may allocate a new backing array under the hood; the caller must always use the returned slice, never assume the original variable was mutated in place.

import "fmt"

// addTask appends a new, not-done task and returns the updated slice.
// The caller must reassign its variable to this return value, since
// append() can return a slice backed by a different underlying array.
func addTask(tasks []Task, title string) []Task {
	nextID := 1
	for _, t := range tasks { // Find the highest existing id so new ids never collide with a deleted one's old id
		if t.ID >= nextID {
			nextID = t.ID + 1
		}
	}
	newTask := Task{ID: nextID, Title: title, Done: false}
	return append(tasks, newTask) // append() may grow the slice into a new array; always use its return value
}

// listTasks prints every task with a checkbox showing its done state.
func listTasks(tasks []Task) {
	if len(tasks) == 0 {
		fmt.Println("No tasks yet.")
		return
	}
	for _, t := range tasks { // Range over a slice by value; t is a copy, safe to read but never mutates tasks
		mark := " " // Space inside the checkbox means "not done"
		if t.Done {
			mark = "x"
		}
		fmt.Printf("[%s] %d. %s\n", mark, t.ID, t.Title)
	}
}

Step 4: Complete and Delete Tasks

`completeTask()` loops with the two-value form of `range`, using the index `i` to reach into the slice and flip `Done` on the actual element — ranging with just `t` would only modify a copy, since Go slice elements are copied into the loop variable by value. `deleteTask()` builds a fresh slice of everything except the matching id, which is the idiomatic Go way to "remove" an element without the pointer-juggling an in-place removal would require.

// completeTask marks the task with the given id as done. It returns false
// if no task with that id exists, so the caller can report "not found".
func completeTask(tasks []Task, id int) bool {
	for i := range tasks { // Index form of range: needed to mutate the real element, not a copy of it
		if tasks[i].ID == id {
			tasks[i].Done = true
			return true
		}
	}
	return false // No match; caller decides how to report this
}

// deleteTask removes the task with the given id and returns the updated
// slice. Building a new slice of "everything that doesn't match" is the
// idiomatic Go way to delete from a slice.
func deleteTask(tasks []Task, id int) ([]Task, bool) {
	result := make([]Task, 0, len(tasks)) // Pre-size capacity; at most len(tasks) items will ever be appended
	removed := false
	for _, t := range tasks {
		if t.ID == id {
			removed = true
			continue // Skip this one; everything else gets appended below
		}
		result = append(result, t)
	}
	return result, removed
}

Step 5: Build the Menu Loop

`main()` loads the saved task list once at startup, then loops on a numbered menu using `bufio.NewReader(os.Stdin)` to read whole lines — `fmt.Scanln` alone would stop at the first space, which breaks multi-word task titles. Every command that changes the list ends by calling `saveTasks()` immediately, so the JSON file on disk is never more than one action behind what is in memory.

import (
	"bufio"   // Reads whole lines of input, including spaces, unlike fmt.Scanln
	"fmt"
	"os"
	"strconv" // Atoi: parse a typed-in id string into an int
	"strings" // TrimSpace: strip the trailing newline bufio.Reader leaves on each line
)

const dataFile = "tasks.json"

func main() {
	tasks, err := loadTasks(dataFile) // One shared []Task, updated and saved after every change
	if err != nil {
		fmt.Println("Error loading tasks:", err)
		return
	}

	reader := bufio.NewReader(os.Stdin)

	for {
		fmt.Println("\n===== CLI TASK MANAGER =====")
		fmt.Println("1. Add Task")
		fmt.Println("2. List Tasks")
		fmt.Println("3. Complete Task")
		fmt.Println("4. Delete Task")
		fmt.Println("5. Exit")
		fmt.Print("Enter your choice: ")

		choiceStr, _ := reader.ReadString('\n') // ReadString keeps reading until it sees the delimiter byte
		choice := strings.TrimSpace(choiceStr)   // Strip the trailing "\n" (and any "\r" on Windows)

		switch choice {
		case "1":
			fmt.Print("Enter task title: ")
			titleStr, _ := reader.ReadString('\n')
			title := strings.TrimSpace(titleStr)
			tasks = addTask(tasks, title) // Reassign: addTask's returned slice is the source of truth from here on
			saveTasks(dataFile, tasks)
			fmt.Println("Task added.")
		case "2":
			listTasks(tasks)
		case "3":
			fmt.Print("Enter task ID to complete: ")
			idStr, _ := reader.ReadString('\n')
			id, err := strconv.Atoi(strings.TrimSpace(idStr)) // Atoi returns an error for non-numeric input
			if err != nil {
				fmt.Println("Please enter a valid number.")
				continue
			}
			if completeTask(tasks, id) {
				saveTasks(dataFile, tasks)
				fmt.Println("Task marked complete.")
			} else {
				fmt.Println("No task with that ID.")
			}
		case "4":
			fmt.Print("Enter task ID to delete: ")
			idStr, _ := reader.ReadString('\n')
			id, err := strconv.Atoi(strings.TrimSpace(idStr))
			if err != nil {
				fmt.Println("Please enter a valid number.")
				continue
			}
			updated, removed := deleteTask(tasks, id)
			if removed {
				tasks = updated // Only reassign on success; a no-op delete shouldn't touch the in-memory list
				saveTasks(dataFile, tasks)
				fmt.Println("Task deleted.")
			} else {
				fmt.Println("No task with that ID.")
			}
		case "5":
			fmt.Println("Goodbye!")
			return // Exits main(), which ends the program
		default:
			fmt.Println("Invalid choice, try again.")
		}
	}
}

Complete Code

Here is the full program assembled in one file, ready to save as `main.go` and run with `go run main.go`.

package main

import (
	"bufio"
	"encoding/json"
	"fmt"
	"os"
	"strconv"
	"strings"
)

const dataFile = "tasks.json"

type Task struct {
	ID    int    `json:"id"`
	Title string `json:"title"`
	Done  bool   `json:"done"`
}

func loadTasks(filename string) ([]Task, error) {
	data, err := os.ReadFile(filename)
	if err != nil {
		if os.IsNotExist(err) {
			return []Task{}, nil
		}
		return nil, err
	}

	var tasks []Task
	if err := json.Unmarshal(data, &tasks); err != nil {
		return nil, err
	}
	return tasks, nil
}

func saveTasks(filename string, tasks []Task) error {
	data, err := json.MarshalIndent(tasks, "", "  ")
	if err != nil {
		return err
	}
	return os.WriteFile(filename, data, 0644)
}

func addTask(tasks []Task, title string) []Task {
	nextID := 1
	for _, t := range tasks {
		if t.ID >= nextID {
			nextID = t.ID + 1
		}
	}
	newTask := Task{ID: nextID, Title: title, Done: false}
	return append(tasks, newTask)
}

func listTasks(tasks []Task) {
	if len(tasks) == 0 {
		fmt.Println("No tasks yet.")
		return
	}
	for _, t := range tasks {
		mark := " "
		if t.Done {
			mark = "x"
		}
		fmt.Printf("[%s] %d. %s\n", mark, t.ID, t.Title)
	}
}

func completeTask(tasks []Task, id int) bool {
	for i := range tasks {
		if tasks[i].ID == id {
			tasks[i].Done = true
			return true
		}
	}
	return false
}

func deleteTask(tasks []Task, id int) ([]Task, bool) {
	result := make([]Task, 0, len(tasks))
	removed := false
	for _, t := range tasks {
		if t.ID == id {
			removed = true
			continue
		}
		result = append(result, t)
	}
	return result, removed
}

func main() {
	tasks, err := loadTasks(dataFile)
	if err != nil {
		fmt.Println("Error loading tasks:", err)
		return
	}

	reader := bufio.NewReader(os.Stdin)

	for {
		fmt.Println("\n===== CLI TASK MANAGER =====")
		fmt.Println("1. Add Task")
		fmt.Println("2. List Tasks")
		fmt.Println("3. Complete Task")
		fmt.Println("4. Delete Task")
		fmt.Println("5. Exit")
		fmt.Print("Enter your choice: ")

		choiceStr, _ := reader.ReadString('\n')
		choice := strings.TrimSpace(choiceStr)

		switch choice {
		case "1":
			fmt.Print("Enter task title: ")
			titleStr, _ := reader.ReadString('\n')
			title := strings.TrimSpace(titleStr)
			tasks = addTask(tasks, title)
			saveTasks(dataFile, tasks)
			fmt.Println("Task added.")
		case "2":
			listTasks(tasks)
		case "3":
			fmt.Print("Enter task ID to complete: ")
			idStr, _ := reader.ReadString('\n')
			id, err := strconv.Atoi(strings.TrimSpace(idStr))
			if err != nil {
				fmt.Println("Please enter a valid number.")
				continue
			}
			if completeTask(tasks, id) {
				saveTasks(dataFile, tasks)
				fmt.Println("Task marked complete.")
			} else {
				fmt.Println("No task with that ID.")
			}
		case "4":
			fmt.Print("Enter task ID to delete: ")
			idStr, _ := reader.ReadString('\n')
			id, err := strconv.Atoi(strings.TrimSpace(idStr))
			if err != nil {
				fmt.Println("Please enter a valid number.")
				continue
			}
			updated, removed := deleteTask(tasks, id)
			if removed {
				tasks = updated
				saveTasks(dataFile, tasks)
				fmt.Println("Task deleted.")
			} else {
				fmt.Println("No task with that ID.")
			}
		case "5":
			fmt.Println("Goodbye!")
			return
		default:
			fmt.Println("Invalid choice, try again.")
		}
	}
}

Sample Run

Click Run to see what this code prints.

Extend This Project

Add a `Priority` field (`"low"`/`"medium"`/`"high"`) to `Task` and a command to sort tasks by it before listing.
Support command-line flags with the `flag` package so tasks can be added or listed non-interactively, e.g. `go run main.go -add "Buy milk"`.
Add a `DueDate` field using `time.Time` and highlight overdue tasks in the listing.
Add a `findByTitle(tasks []Task, query string) []Task` helper using `strings.Contains` for case-insensitive search.
Wrap file access in a `sync.Mutex` and expose the same operations over a small `net/http` server, reusing the JSON persistence layer from Step 2 as-is.

Summary

You built a working task manager where a plain `Task` struct is serialized to and from JSON with `encoding/json`, and every function that can fail — reading a file, parsing JSON, converting a string to an int — returns an explicit `error` that the caller is expected to check. That `(value, error)` return pattern, and the discipline of reassigning a slice after every `append()`, are two of the most fundamental habits in idiomatic Go, and you will reach for both in nearly every program you write from here on.