cli-usage.md

Command-line Interface Usage

Use this guide to choose the right command-line tools in this repository and find where each one is configured.

Table of contents

• Command-line Interface Usage
  • Table of contents
  • Scope
  • How to use this guide
  • Task-first quick start
  • Tool purpose and use-case reference
    • Core shell and navigation
    • Search, data and output processing
    • Git and repository workflow
    • Cloud, platform and infrastructure
    • Languages, runtimes and package tooling
    • AI CLI tooling
  • Installed CLI tooling
    • macOS base CLI
    • macOS developer CLI
    • macOS AI CLI
    • macOS user CLI
    • Ubuntu prerequisites and base CLI
    • asdf-managed CLI
  • Configuration map
  • Shell integration points

Scope

This guide inventories CLI tooling installed by this repository automation and shows where each tool is configured.

It is written for learning and day-to-day usage:

• New users can start with common tasks and tool selection.
• Existing users can use it as a reference for configuration locations.
• Contributors can validate what is installed on macOS vs Ubuntu.

The inventory is based on these scripts:

• assets/00-prerequisites.macos.sh
• assets/00-prerequisites.ubuntu.sh
• assets/01-update-all-packages.macos.sh
• assets/20-install-base-packages.macos.sh
• assets/20-install-base-packages.ubuntu.sh
• assets/30-install-developer-tools.macos.sh
• assets/32-install-ai-tools.macos.sh
• assets/91-install-user-apps.macos.sh
• .tool-versions (asdf-managed tools)

How to use this guide

1. Start with Task-first quick start to pick tools by outcome.
2. Use Tool purpose and use-case reference to understand when each tool is the right choice.
3. Use Configuration map when you need to customise defaults.
4. Use Installed CLI tooling as the authoritative inventory.

Task-first quick start

If you want to...	Start with...	Why this pair works
Find files and search text quickly	fd + ripgrep (rg)	fd narrows candidate files; rg searches content fast.
Inspect command output safely	bat + less	bat improves readability, less handles long output.
Explore Git changes interactively	git + delta + lazygit	CLI-first workflow with both detailed and TUI review modes.
Query JSON or YAML from APIs	jq + yq	Structured filtering is faster and less error-prone than manual parsing.
Jump between directories and sessions	zoxide + tmux	Fast directory recall plus persistent terminal workspaces.
Run project checks before commit	pre-commit + gitleaks + shellcheck	Catches quality and secret-scanning issues early.
Work with cloud and cluster resources	awscli/aws-vault + azure-cli + kubectl	Consistent CLI flow across cloud and Kubernetes operations.

Tool purpose and use-case reference

These tables focus on high-value day-to-day tools. The full installed inventory remains in Installed CLI tooling.

Core shell and navigation

Tool	What it is for	Good use case
zsh / bash	Interactive shell environments	Running setup scripts and daily terminal workflows.
eza	Modern ls replacement	Listing directories with clearer metadata and tree view.
zoxide	Smart directory jumping	Moving quickly between frequently used repo paths.
tmux	Terminal multiplexer	Keeping long-running sessions alive across reconnects.
screen	Alternative terminal multiplexer	Lightweight multi-session work on remote hosts.
watch	Periodic command execution	Monitoring changing command output while debugging.
btop	Interactive system monitor	Inspecting CPU, memory, and process usage in terminal.

Search, data and output processing

Tool	What it is for	Good use case
fd	Fast file discovery	Finding candidate files before grep or edits.
ripgrep (rg)	Fast text search in files	Locating symbols, TODOs or config values in large repos.
fzf	Fuzzy finder	Interactive selection of files, branches, or command history.
bat	Syntax-highlighted file viewer	Previewing files and logs with readable output.
jq	JSON processor	Filtering API responses in scripts and pipelines.
yq	YAML processor	Extracting and editing values from YAML config files.
xq	XML to jq-like querying	Querying XML output with jq-style expressions.
jc	CLI output to JSON	Converting classic command output for automation pipelines.

Git and repository workflow

Tool	What it is for	Good use case
git	Version control	Branching, committing and repository history management.
delta	Enhanced Git diff viewer	Reviewing code changes with improved readability.
diff-so-fancy	Human-friendly diff formatting	Cleaner patch reviews in terminal-only sessions.
lazygit	Terminal Git UI	Staging and rebasing interactively without leaving the shell.
gh	GitHub CLI	Creating PRs, viewing checks, and managing issues from terminal.
git-secrets	Secret detection in Git content	Blocking obvious credential leaks before commit.
gitleaks	Deep secret scanning	Running repository-wide secret scans in CI/local checks.
pre-commit	Multi-tool hook runner	Enforcing lint/format/security checks consistently.

Cloud, platform and infrastructure

Tool	What it is for	Good use case
awscli	AWS service operations	Scripting S3, IAM or EC2 workflows from terminal.
aws-vault	Secure AWS credential sessions	Running temporary-role commands without long-lived keys.
azure-cli	Azure resource operations	Provisioning and querying Azure resources via scripts.
kubectl	Kubernetes control plane CLI	Inspecting pods, logs and rollout status in clusters.
terraform	Infrastructure as code workflows	Planning and applying reproducible infrastructure changes.
act	Run GitHub Actions locally	Validating CI workflows before pushing commits.

Languages, runtimes and package tooling

Tool	What it is for	Good use case
asdf	Runtime version manager	Pinning tool versions per project with .tool-versions.
python + uv	Python runtime and package workflow	Fast virtualenv and dependency operations.
node + yarn	JavaScript runtime and package workflow	Installing and running JS/TS tooling and scripts.
go	Go toolchain	Building and testing Go-based CLI tools.
rust	Rust toolchain	Compiling high-performance command-line utilities.
ruby	Ruby runtime	Running Ruby-based automation and scripts.
openjdk	Java runtime and compiler	Running Java tooling that requires JDK support.

AI CLI tooling

Tool	What it is for	Good use case
codex	AI-assisted coding in terminal	Generating or editing code with repository context.
copilot-cli	Copilot chat/commands in CLI	Drafting commands and code explanations from terminal.
claude-code	AI coding assistant CLI	Pair-programming and refactoring through prompt-driven edits.
chatgpt / chatgpt-atlas	General-purpose AI assistants	Brainstorming, summarisation and command drafting.
ollama	Local model runtime	Running local LLM inference workflows offline.
lm-studio	Local model management and inference	Testing local models and prompts on-device.
llmfit	Local model fit analyser	Finding which LLM models fit available local hardware.
macwhisper	Local speech-to-text tooling	Transcribing recordings without cloud dependency.
specify	Specification-driven planning tool	Turning feature ideas into structured implementation specs.
opencode	AI-assisted coding CLI workflow	Running agentic coding flows from terminal.

Installed CLI tooling

This section is the complete inventory of tools installed by automation scripts.

macOS base CLI

ack, autoconf, bash, bat, binutils, btop, coreutils, ctop, curl, delta, diff-so-fancy, diffutils, dive, dockutil, duti, eza, fd, findutils, fzf, gawk, git, git-crypt, git-secrets, gnu-getopt, gnu-sed, gnu-tar, gnu-which, gnutls, gpg, grep, gzip, grc, jc, jq, lazygit, less, make, neovim, openssl, pinentry-mac, readline, ripgrep, screen, tmux, topgrade, tree, watch, wdiff, wget, xq, xz, yq, zip, zlib, zoxide, zsh.

macOS developer CLI

act, asdf, aws-vault, awscli, azure-cli, bitwarden-cli, chezmoi, gh, hadolint, kubernetes-cli, scc, shellcheck, python, ruff, uv, node, yarn, go, rust, openjdk, ruby, terraform.

macOS AI CLI

anomalyco/tap/opencode, chatgpt, chatgpt-atlas, claude-code, codex, copilot-cli, lm-studio, llmfit, macwhisper, ollama, specify.

macOS user CLI

mole.

Ubuntu prerequisites and base CLI

apt-transport-https, build-essential, ca-certificates, curl, git, gnupg, lsb-release, software-properties-common, unzip, wget, zsh, bat, fd-find, fzf, jq, less, neovim, ripgrep, screen, tmux, tree, watch, zip, plus explicit installs for eza, zoxide, delta and gpg.

asdf-managed CLI

gitleaks, pre-commit.

Configuration map

Tool	Configuration location	Notes
bat	~/.config/bat/config	Default style, paging, and syntax mapping
fd	~/.config/fd/ignore	Global ignore list for noisy paths
ripgrep	~/.config/ripgrep/config + RIPGREP_CONFIG_PATH	Central default flags
fzf	~/.config/fzf/fzfrc + FZF_DEFAULT_OPTS_FILE	Shared interactive defaults
gh	~/.config/gh/config.yml	Protocol/editor/pager and aliases
lazygit	~/.config/lazygit/config.yml via LG_CONFIG_FILE	UI and git workflow defaults
topgrade	~/.config/topgrade.toml	Upgrade strategy and safety defaults
git + delta	~/.gitconfig (templated from dot_gitconfig.tmpl)	Diff, pager, and merge behavior
awscli	AWS_PAGER env var in ~/.exports	Disables default pager for scripts

Tools without dedicated config files still get behaviour through shell aliases, PATH and environment wiring.

Shell integration points

• dot_path.tmpl manages PATH precedence and GNU tool overrides.
• dot_exports stores tool environment variables and config-path wiring.
• dot_aliases provides command ergonomics and Ubuntu compatibility aliases (batcat/fdfind).
• dot_functions provides helper functions for git, containers and shell tasks.