cli

CLI Package

A lightweight framework for building command-line applications with consistent behavior.

Overview

The CLI package provides a standardized way to create command-line applications with common features:

• Consistent flag parsing
• Structured logging
• Version information handling
• Error handling
• Builder pattern for configuration

Usage

Here's a simple example of how to use the CLI package:

package main

import (
	"context"
	"flag"
	"fmt"
	"os"

	"git.sr.ht/~jcmuller/tools/pkg/cli"
)

func main() {
	var name string

	app := cli.New(
		"hello-world",
		"A simple hello world application\n\nUsage:\n  %s [options]\n\nOptions:\n",
		cli.WithRunFunc(func(ctx context.Context) error {
			fmt.Printf("Hello, %s!\n", name)
			return nil
		}),
		cli.WithFlags(func(fs *flag.FlagSet) {
			fs.StringVar(&name, "name", "World", "Name to greet")
		}),
	)

	if err := app.Run(context.Background(), os.Args); err != nil {
		os.Exit(1)
	}
}

Features

Builder Pattern

The CLI package uses the builder pattern for configuration:

app := cli.New(
    "app-name",
    "app description",
    cli.WithRunFunc(run),
    cli.WithFlags(addFlags),
    cli.WithVersion("1.0.0"),  // Optional, defaults to version from tools package
    cli.WithLogConfig(logConfig),  // Optional, defaults to text output to stderr
)

Common Flags

All applications automatically get these flags:

• --debug: Enable debug logging
• --help: Show help and exit
• --version: Show version and exit
• --completion: Generate shell completion script for the specified shell (bash, zsh, fish)

Structured Logging

The CLI package uses log/slog for structured logging:

// Configure logging with options
config := cli.NewLogConfig(
    cli.WithLogLevel(slog.LevelDebug),
    cli.WithLogFormat("json"),
)

// Use in your application
app := cli.New(
    "app-name",
    "description",
    cli.WithLogConfig(config),
)

Shell Completion

The CLI package provides automatic shell completion generation for Bash, Zsh, and Fish shells. Users can generate completion scripts using the --completion flag.

Persistent Installation

For persistent installation, save the completion script to the appropriate directory for your shell. The generated scripts are self-updating, meaning they will automatically query the binary for the latest flags whenever completions are requested:

# Bash completion
$ your-app --completion=bash >~/.bash_completion.d/your-app

# Zsh completion
$ your-app --completion=zsh >~/.zsh/completions/_your-app

# Fish completion
$ your-app --completion=fish >~/.config/fish/completions/your-app.fish

With this approach, you won't need to regenerate completion scripts when your application's flags change.

Dynamic Loading

For temporary use or testing, you can dynamically load the completion in your current shell session:

# Zsh dynamic loading
$ eval "$(your-app --completion=zsh)"

# Bash dynamic loading
$ eval "$(your-app --completion=bash)"

# Fish dynamic loading (in fish shell)
$ your-app --completion=fish| source

The completion scripts will provide tab completion for all flags defined in your application.

Version Information

Version information is handled consistently:

// Use the default version from the tools package
app := cli.New("app-name", "description")

// Or specify a custom version
app := cli.New(
    "app-name",
    "description",
    cli.WithVersion("1.2.3"),
)

API Reference

App Creation

• New(name, description string, opts ...AppOption) *App: Create a new CLI application

App Options

• WithRunFunc(fn func(ctx context.Context) error) AppOption: Set the main function
• WithFlags(flagFunc func(*flag.FlagSet)) AppOption: Add custom flags
• WithVersion(version string) AppOption: Set a custom version
• WithLogConfig(config LogConfig) AppOption: Set a custom logging configuration

Logging Configuration

• NewLogConfig(opts ...LogOption) LogConfig: Create a new logging configuration
• WithLogLevel(level slog.Level) LogOption: Set the minimum log level
• WithLogOutput(output io.Writer) LogOption: Set where logs will be written
• WithLogFormat(format string) LogOption: Set the log format (text or json)

Best Practices

1. Keep the run function focused: The run function should only contain the core logic of your application.
2. Use structured logging: Use slog.InfoContext, slog.DebugContext, etc. with key-value pairs for better log analysis.
3. Handle errors properly: Return errors from your run function rather than calling os.Exit.
4. Use the builder pattern: Use the builder pattern for configuration to make your code more readable.