Building a CLI tool: Rust Programming (Expert)

Why Rust for CLI tools?

A CLI (command-line interface) tool is a program you run in a terminal, like git or cargo. Rust is excellent for them: the result is a single fast binary file that starts instantly, has no runtime (like Python or Java) to install, and works on Windows, macOS and Linux. Popular tools like ripgrep (a fast search tool) and many developer tools are written in Rust.

The project: an expense summariser

We will build expsum, a tool that reads a CSV file of expenses and prints the total per category. CSV (comma-separated values) is a simple text format for tables, the kind you can export from Excel or a bank app.

output

date,category,amount
2026-10-01,food,250
2026-10-01,travel,120
2026-10-02,food,180
2026-10-03,bills,1499

expenses.csv: the input file.

bash

expsum expenses.csv
expsum expenses.csv --category food
expsum --help

How a user will run the tool.

The plan has three parts: read the arguments the user typed, do the real work (parse the CSV and add up amounts), and print results or a clear error. We keep the real work in a library function so it can be tested without a terminal, and keep main.rs as a thin layer that talks to the user.

Reading arguments with clap

std::env::args() gives the raw words typed after the program name, but parsing flags, help text and errors by hand is tedious. The clap crate does it from a struct: each field becomes an argument, and doc comments become help text.

bash

cargo new expsum
cd expsum
cargo add clap --features derive

clap 4 with the derive feature.

rust

use clap::Parser;

/// Summarise an expenses CSV file by category.
#[derive(Parser)]
#[command(version, about)]
struct Args {
    /// Path to the CSV file
    file: String,

    /// Only show this category
    #[arg(short, long)]
    category: Option<String>,
}

fn main() {
    let args = Args::parse();       // exits with a helpful message on bad input
    println!("file: {}, category: {:?}", args.file, args.category);
}

file is a required positional argument; --category (or -c) is optional because it is an Option.

The logic, kept testable

rust

// src/lib.rs
use std::collections::BTreeMap;

pub fn summarise(csv: &str) -> Result<BTreeMap<String, u64>, String> {
    let mut totals = BTreeMap::new();
    for (n, line) in csv.lines().enumerate().skip(1) {   // skip the header
        if line.trim().is_empty() {
            continue;
        }
        let parts: Vec<&str> = line.split(',').collect();
        if parts.len() != 3 {
            return Err(format!("line {}: expected 3 columns", n + 1));
        }
        let amount: u64 = parts[2].trim().parse()
            .map_err(|_| format!("line {}: bad amount '{}'", n + 1, parts[2]))?;
        *totals.entry(parts[1].trim().to_string()).or_insert(0) += amount;
    }
    Ok(totals)
}

BTreeMap keeps categories sorted. Errors carry the line number, which users love.

rust

// src/main.rs
use clap::Parser;
use std::process;

#[derive(Parser)]
#[command(version, about)]
struct Args {
    file: String,
    #[arg(short, long)]
    category: Option<String>,
}

fn main() {
    let args = Args::parse();
    let text = std::fs::read_to_string(&args.file).unwrap_or_else(|e| {
        eprintln!("expsum: cannot read {}: {e}", args.file);
        process::exit(1);
    });
    match expsum::summarise(&text) {
        Ok(totals) => {
            for (cat, amt) in &totals {
                if args.category.as_deref().map_or(true, |c| c == cat) {
                    println!("{cat:<10} Rs {amt}");
                }
            }
        }
        Err(e) => {
            eprintln!("expsum: {e}");
            process::exit(2);
        }
    }
}

eprintln! writes to stderr, so error messages do not mix with real output when the user redirects it to a file.

CLI good manners

Exit code 0 means success; any other number means failure. Scripts and CI rely on this.
Print results to stdout (println!) and errors to stderr (eprintln!).
Give helpful errors with the file name and line number.
Support --help and --version (clap does this for you).
Install your own tool locally with cargo install --path . and run it from anywhere.

Common mistakes

Putting all logic in main, so nothing can be tested. Keep main thin.
Calling unwrap() on file reads: users see an ugly panic. Print a clear error and exit with a code.
Reading a huge file fully into memory when you only need one line at a time. Use std::io::BufReader and lines() for big files.
Splitting CSV by commas when fields can contain commas in quotes. For real CSV files, use the csv crate.

Building a CLI tool

Explanation

Why Rust for CLI tools?

The project: an expense summariser

Reading arguments with clap

The logic, kept testable

CLI good manners

Common mistakes

Need help?

Watch the lesson

In real life: A tool for an accounts team

Practice (0/3 done)

Quick quiz

Read more (free)

Before this, learn

Related topics

Next steps

Building a CLI tool

Explanation

Why Rust for CLI tools?

The project: an expense summariser

Reading arguments with clap

The logic, kept testable

CLI good manners

Common mistakes

Need help?

Watch the lesson

In real life: A tool for an accounts team

Practice (0/3 done)

Quick quiz

Read more (free)

Related help

Before this, learn

Related topics

Questions people ask about this

Next steps