demo-cli

README

demo-cli 🎓

A tiny, cheerful command-line tool whose only job in life is to teach you the fundamental concepts of CLIs — commands, flags, arguments, environment variables, and shell completion — while making you smile.

It's built with urfave/cli (a declarative, simple, fast, and fun package for building command-line tools in Go) and it's a companion to comp: because demo-cli speaks the demo-cli completion <shell> convention, you can install its tab-completion with a single comp demo-cli.

Install

go install github.com/piechutowski/demo-cli@latest

If ~/go/bin isn't on your PATH, add it (fish: fish_add_path ~/go/bin).

The 90-second tour

demo-cli                      # a friendly menu
demo-cli learn                # the guided syllabus

Each command demonstrates exactly one fundamental idea:

Command	Teaches	Try it
greet	arguments & flags (+ env vars)	demo-cli greet Ada Grace --loud --times 2
joke	flag values & completion	demo-cli joke --category shell
learn	nested subcommands	demo-cli learn flags
pack	repeatable "slice" flags	demo-cli pack -i socks -i towel Mars

The lessons, one at a time

1. Arguments vs. flags — greet

demo-cli greet Ada Grace --loud --times 2
         ^^^^^ ^^^^^^^^^^ ^^^^^^ ^^^^^^^^^
         cmd   arguments  bool   int flag with a value

• Arguments are the plain words; their meaning comes from their position.

• Flags are named knobs. Bool flags are switches (--loud); value flags carry data (--times 2).

• Flags can read from the environment. --greeting falls back to DEMO_GREETING:

  DEMO_GREETING=Howdy demo-cli greet Sam   # => Howdy, Sam!
  

2. Global flags & compound shorthands

--verbose/-v and --sparkles/-s are global flags — they work on every command. Single-letter bool flags can be mashed together:

demo-cli -vs greet Ada        # same as: demo-cli -v -s greet Ada

-v narrates what's happening behind the curtain; -s adds ✨.

3. Flag values & completion — joke

Many flags take a value from a known set. joke --category is one, and it wires up shell completion so <TAB> lists the choices for you:

demo-cli joke --category shell
demo-cli joke -c <TAB>          # => shell  cli  go  completion

4. Nested subcommands — learn

learn is just a container for smaller lessons — commands within commands:

demo-cli learn args
demo-cli learn flags
demo-cli learn subcommands
demo-cli learn env
demo-cli learn completion

5. Repeatable slice flags — pack

A slice flag can be given many times and collects every value into a list:

demo-cli pack --item socks --item towel --item snacks Mars

Shell completion (the whole point)

demo-cli ships completion scripts for every major shell:

demo-cli completion bash
demo-cli completion zsh
demo-cli completion fish
demo-cli completion pwsh

The fastest way to install them is comp, which detects your shell and drops the script in the right place:

comp demo-cli

...or do it manually, e.g. for the current bash session:

source <(demo-cli completion bash)

Then press <TAB> anywhere — after demo-cli , after learn , or after joke -c — and watch demo-cli finish your thought.

Building from source

go build -o demo-cli .
./demo-cli learn

License

Apache-2.0. See LICENSE.

Documentation

Overview

demo-cli is a tiny, cheerful command-line tool whose only job in life is to teach you the fundamental concepts of CLIs — commands, flags, arguments, environment variables and shell completion — using the delightful github.com/urfave/cli library.

It is a companion to `comp` (github.com/piechutowski/comp): because demo-cli speaks the `demo-cli completion <shell>` convention, you can install its completions with a single `comp demo-cli`.