The Magic of the Tab Key: A Deep Dive into Shell Auto-Completion

(Read this article on my blog for best experience - https://mraviral.in/blog/tab-auto-complete)

Long before "AI" became a household term and Large Language Models began predicting our emails, Linux/terminal users possessed a different kind of magic: the Tab key.

You type git check, press <Tab>, and the shell instantaneously types checkout for you.

You type ls Doc, press <Tab>, and it becomes ls Documents/.

It feels intuitive, almost psychic. But unlike modern AI, this isn't probabilistic guesswork. It is a deterministic, highly structured conversation between your keyboard, the shell, and a hidden layer of scripts.

In this guide, we will dismantle this mechanism, starting from the basics of native file listing to understanding complex tools like Docker, and finally, writing our own auto-completion engine for a custom Go CLI.

---

1. The Basics: Native Shell Intelligence

At its core, a shell like Bash (Bourne Again SHell) uses a library called Readline to handle text input. When you press Tab, Readline intercepts that keystroke and checks the context.

Scenario A: Path and Command Completion

If you are typing the first word of a command, Bash assumes you are looking for an executable.

1. It scans the directories listed in your $PATH environment variable.

2. If you type pyth and hit tab, it looks for executables starting with "pyth" (like python3).

Scenario B: File Completion

If you are typing arguments after a command, and no specific rules are defined, Bash defaults to filename completion.

1. It looks at the current working directory.

2. It matches the string against files and folders.

Open your terminal and try this:

(Type the following (do not press enter, just Tab)

/usr/bin/zi[TAB]

Bash looks in /usr/bin/, finds files starting with zi, and completes zip or zipgrep.

This is the "fallback" behavior: if no specific rules exist, look for files.

---

2. Programmable Completion: How git and docker work

The default behavior works for files, but how does git checkout [TAB] work? checkout isn't a file in your directory.

This is where Programmable Completion enters the scene. Bash allows us to define specific rules for specific commands using the complete builtin.

The complete Command

The shell maintains a registry mapping command names to specific functions that generate suggestions.

Let's ask Bash how it handles git.

complete -p git

Translation:

• -F _git: When the user hits Tab on git, run the shell function named _git.

• git: The command this rule applies to.

When you install a tool like Docker, it places a massive Bash script into a specific directory (like /etc/bash_completion.d/ or /usr/share/bash-completion/completions/). When you start your shell, these scripts are "sourced" (loaded into memory).

For example here is what docker's script looks like -

Anatomy of a Completion Script

These scripts utilize a few special environment variables that Bash provides only during completion:

• COMP_WORDS: An array of all words currently typed in the command line.

• COMP_CWORD: The index of the word where the cursor currently is.

• COMPREPLY: An array variable where the script must store the possible suggestions.

If you type docker cont[TAB], the flow is:

1. Read: The script reads COMP_WORDS.

2. Analyze: It sees the previous word was docker and current fragment is cont.

3. Match: It matches the fragment against a list of docker subcommands (container, context, cp).

4. Reply: It populates COMPREPLY with container context cp.

5. Display: Bash displays these options to the user.

---

3. Building Your Own Auto-Completion

Let's demystify this by building a completion system from scratch. We will create a dummy Command Line Interface (CLI) in Go, and then write the shell script to make it smart.

Step 1: The Dummy CLI (Golang)

We will create a tool called solar-system. It will have two subcommands: earth and mars.

• earth accepts the flag --moon.

• mars accepts the flag --rover.

File: main.go

package main

import (
    "fmt"
    "os"
)

func main() {
    if len(os.Args) < 2 {
        fmt.Println("Usage: solar-system [earth|mars]")
        return
    }

    cmd := os.Args[1]
    switch cmd {
    case "earth":
        fmt.Println("Hello Earthling! Options: --moon")
    case "mars":
        fmt.Println("Hello Martian! Options: --rover")
    default:
        fmt.Println("Unknown planet")
    }
}

Build and Install -

go build -o solar-system main.go

Move it to your path so you can run it from anywhere -

sudo mv solar-system /usr/local/bin/

Note: If you type solar-system [TAB] now, nothing happens (or it just defaults to local files).

Step 2: Writing the Completion Script

We need to tell Bash: "When solar-system is typed, use my logic."

File: solar-completion.bash

#!/bin/bash

_solar_system_completions()
{
  local cur prev

  # 'cur' is the word currently being typed
  cur="${COMP_WORDS[COMP_CWORD]}"

  # 'prev' is the word before the current cursor
  prev="${COMP_WORDS[COMP_CWORD-1]}"

  # Define our lists of commands
  local planets="earth mars"
  local earth_opts="--moon"
  local mars_opts="--rover"

  # Logic
  # If we are at the first argument (subcommand level)
  if [ "$COMP_CWORD" -eq 1 ]; then
    # COMPGEN is a builtin to generate matches
    # -W holds the word list, -- $cur matches against current input
    COMPREPLY=( $(compgen -W "${planets}" -- ${cur}) )
    return 0
  fi

  # Context Aware Logic
  # If the previous word was 'earth', suggest earth options
  case "${prev}" in
    earth)
      COMPREPLY=( $(compgen -W "${earth_opts}" -- ${cur}) )
      return 0
      ;;
    mars)
      COMPREPLY=( $(compgen -W "${mars_opts}" -- ${cur}) )
      return 0
      ;;
    *)
      ;;
  esac
}

# register the function
complete -F _solar_system_completions solar-system

Step 3: Enabling and Testing

Load the script into your current shell session:

source ./solar-completion.bash

Now, witness the magic:

1. Type solar-system [TAB][TAB]

   • Result: It suggests earth and mars.

2. Type solar-system ea[TAB]

   • Result: It completes to solar-system earth.

3. Type solar-system earth [TAB][TAB]

   • Result: It suggests --moon.

---

4. Modern Approaches: Dynamic Completion

The method above (writing a separate Bash script) is the classic way. However, keeping a Bash script in sync with your Go code is tedious. If you add a "jupiter" command in our Go program, we have to manually update the Bash script.

Modern CLIs (like kubectl or tools built with the Go Cobra library) use Dynamic Completion.

Instead of hardcoding lists in Bash, the Bash script calls the binary itself to ask for suggestions.

1. The user hits Tab.

2. The Bash function runs solar-system __complete [current_text].

3. The Go binary runs a hidden logic to calculate suggestions and prints them to Standard Out.

4. Bash captures those prints and displays them.

This keeps the logic entirely inside your application code (Golang/Python/Rust), making the binary self-documenting and self-completing.

Summary

Hence we saw that shell auto-completion is not magic; it is a structured event loop:

1. You press Tab.

2. Readline pauses input and looks for a registered complete function.

3. The function analyzes COMP_WORDS (what you typed) and COMP_CWORD (where you are).

4. The function populates COMPREPLY using compgen.

5. The shell prints the matches.

Thanks for reading!

PS - Get the source code from here