Lab: Click tool

Build ds-tool — a multi-subcommand CLI with scan, report, and clean subcommands, config file support, and rich output.

This lab builds ds-tool (dataset tool) from scratch — a multi-subcommand CLI with three commands: scan to discover files, report to display a Rich table of results, and clean to delete matched files with a confirmation prompt.

The full tool is assembled in four steps. Run each demo independently to verify it works before moving on.

Step 1 — The group and scan subcommand

scan takes a directory and an extension, walks the directory, and collects file metadata. The group holds shared state (the scan results) in the context:

Python — editable, runs in your browser

import click
from click.testing import CliRunner
import os, tempfile, pathlib

@click.group()
@click.pass_context
def ds(ctx):
  """Dataset management tool."""
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv", help="File extension to scan for.")
@click.pass_obj
def scan(obj, directory, ext):
  """Scan DIRECTORY for files with the given extension."""
  found = []
  for entry in os.scandir(directory):
      if entry.is_file() and entry.name.endswith(ext):
          stat = entry.stat()
          found.append({"name": entry.name, "size": stat.st_size, "path": entry.path})
  obj["results"] = found
  click.echo(f"Found {len(found)} {ext} file(s) in {directory}.")

# -- Test it
tmpdir = tempfile.mkdtemp()
for name, content in [("sales.csv", "a,b
1,2"), ("notes.txt", "hi"), ("data.csv", "x
1
2
3")]:
  pathlib.Path(tmpdir, name).write_text(content)

shared = {"results": []}
runner = CliRunner()
r = runner.invoke(ds, ["scan", tmpdir, "--ext", ".csv"], obj=shared)
print(r.output.strip())
print("Results stored:", [x["name"] for x in shared["results"]])

Step 2 — The report subcommand

report reads from the shared context and displays a Rich table:

Python — editable, runs in your browser

import click
from click.testing import CliRunner
from rich.table import Table
from rich.console import Console
import os, tempfile, pathlib

console = Console()

@click.group()
@click.pass_context
def ds(ctx):
  """Dataset management tool."""
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv")
@click.pass_obj
def scan(obj, directory, ext):
  """Scan DIRECTORY for files with the given extension."""
  found = []
  for entry in os.scandir(directory):
      if entry.is_file() and entry.name.endswith(ext):
          stat = entry.stat()
          found.append({"name": entry.name, "size": stat.st_size, "path": entry.path})
  obj["results"] = found
  click.echo(f"Found {len(found)} {ext} file(s).")

@ds.command()
@click.pass_obj
def report(obj):
  """Display a table of scan results."""
  results = obj.get("results", [])
  if not results:
      click.echo("No scan results. Run 'ds scan <directory>' first.")
      return
  table = Table(title="Scan Results", header_style="bold blue")
  table.add_column("File", style="green")
  table.add_column("Size (bytes)", justify="right")
  for r in results:
      table.add_row(r["name"], str(r["size"]))
  console.print(table)

# -- Test it
tmpdir = tempfile.mkdtemp()
for name, content in [("sales.csv", "a,b
1,2"), ("data.csv", "x
1
2
3")]:
  pathlib.Path(tmpdir, name).write_text(content)

shared = {"results": []}
runner = CliRunner()
runner.invoke(ds, ["scan", tmpdir], obj=shared)
r = runner.invoke(ds, ["report"], obj=shared)
print(r.output)

Step 3 — The clean subcommand with confirmation

clean deletes the scanned files. It always asks for confirmation before deleting. The --yes flag skips the prompt for scripting:

Python — editable, runs in your browser

import click
from click.testing import CliRunner
import os, tempfile, pathlib

@click.group()
@click.pass_context
def ds(ctx):
  ctx.ensure_object(dict)
  ctx.obj.setdefault("results", [])

@ds.command()
@click.argument("directory")
@click.option("--ext", default=".csv")
@click.pass_obj
def scan(obj, directory, ext):
  found = []
  for entry in os.scandir(directory):
      if entry.is_file() and entry.name.endswith(ext):
          found.append({"name": entry.name, "path": entry.path})
  obj["results"] = found
  click.echo(f"Found {len(found)} file(s).")

@ds.command()
@click.option("--yes", is_flag=True, help="Skip confirmation prompt.")
@click.pass_obj
def clean(obj, yes):
  """Delete files found by the last scan."""
  results = obj.get("results", [])
  if not results:
      click.echo("Nothing to clean.")
      return
  if not yes:
      confirmed = click.confirm(f"Delete {len(results)} file(s)?")
      if not confirmed:
          click.echo("Aborted.")
          return
  for r in results:
      os.remove(r["path"])
      click.echo(f"Deleted {r['name']}")
  obj["results"] = []

# -- Test: confirm yes
tmpdir = tempfile.mkdtemp()
for name in ["a.csv", "b.csv"]:
  pathlib.Path(tmpdir, name).write_text("data")

shared = {"results": []}
runner = CliRunner()
runner.invoke(ds, ["scan", tmpdir], obj=shared)

# Pass input="y
" to simulate the user typing yes
r = runner.invoke(ds, ["clean"], input="y
", obj=shared)
print("With confirmation:")
print(r.output.strip())
print("Files remaining:", os.listdir(tmpdir))

# Test: --yes skips the prompt
tmpdir2 = tempfile.mkdtemp()
pathlib.Path(tmpdir2, "c.csv").write_text("data")
shared2 = {"results": []}
runner.invoke(ds, ["scan", tmpdir2], obj=shared2)
r2 = runner.invoke(ds, ["clean", "--yes"], obj=shared2)
print("
With --yes:")
print(r2.output.strip())

Destructive operations must always have a confirmation step. The --yes flag exists to allow automation and scripting, not to encourage skipping the confirmation in interactive use. Document the --yes flag clearly so users know it is for scripts.

Step 4 — Config file support

Add a default directory from ~/.config/ds-tool/config.toml so users do not have to type the path every time:

import tomllib
import pathlib

def load_config() -> dict:
    p = pathlib.Path.home() / ".config" / "ds-tool" / "config.toml"
    if p.exists():
        with open(p, "rb") as f:
            return tomllib.load(f).get("defaults", {})
    return {}

@ds.command()
@click.argument("directory", required=False)
@click.option("--ext", default=None)
@click.pass_obj
def scan(obj, directory, ext):
    config = load_config()
    directory = directory or config.get("directory", ".")
    ext = ext or config.get("ext", ".csv")
    ...

With a config file at ~/.config/ds-tool/config.toml containing:

[defaults]
directory = "/data/datasets"
ext = ".parquet"

Running ds-tool scan with no arguments scans /data/datasets for .parquet files. The CLI arguments still override the config values when provided.

What you built

ds-tool now has:

A top-level group with three subcommands (scan, report, clean)
Shared state through Click's context object
Rich table output in the report command
A confirmation prompt before destructive deletion
Config file support with CLI flags taking precedence

This is the shape of most real-world CLI tools — the Click skills you used here transfer directly.

Where to go next

Next module: Testing CLIs — using Click's CliRunner to write reliable automated tests for every command path.

Finished reading? Mark it complete to track your progress.

Step 1 — The group and scan subcommand

Step 2 — The report subcommand

Step 3 — The clean subcommand with confirmation

Step 4 — Config file support

What you built

Where to go next

On this page