clix

README

clix

clix gives a Go command-line program built on cobra, the Go command-line library, one consistent way to talk to the user. Data goes to stdout. Narration (progress, outcomes, warnings, errors and hints) goes to stderr, as a live block on a terminal, plain lines in a log, or one JSON object per line for a script. clix adds the global flags, builds the console, turns errors and signals into exit codes, and ships a test package. The console package uses only the standard library and works without cobra.

$ go get github.com/vi-dev/clix

A few lines of main

This is the main of hello, the program that getting started builds.

func main() {
    clix.Run(newRoot(), clix.Options{
        App:       "hello",
        Version:   "0.1.0",
        EnvPrefix: "HELLO",
        Hint:      hint,
        Setup: func(ctx context.Context, c *console.Console) (context.Context, error) {
            con = c
            return ctx, nil
        },
    })
}

clix.Run runs the command, prints a final error if there is one, and exits with the right code.

What the user sees

hello greet world --color never prints:

INFO Hello, world
OK Greeted world

The same run with --narration json prints one JSON object per line:

{"seq":1,"time":"2026-10-20T02:55:15.572500Z","event":"begin","app":"hello","version":"0.1.0","schema":1}
{"seq":2,"time":"2026-10-20T02:55:15.572730Z","event":"line","level":"info","text":"Hello, world"}
{"seq":3,"time":"2026-10-20T02:55:15.572741Z","event":"task","task":1,"state":"started","label":"Greeting world"}
{"seq":4,"time":"2026-10-20T02:55:15.572754Z","event":"task","task":1,"state":"phase","phase":"thinking"}
{"seq":5,"time":"2026-10-20T02:55:15.873788Z","event":"task","task":1,"state":"done","outcome":"Greeted world","elapsed_ms":301}
{"seq":6,"time":"2026-10-20T02:55:15.874018Z","event":"exit","code":0}

Flags

Every command gets four global flags, and a command that prints data can add a fifth:

• --color auto|always|never turns colour on or off.
• --narration auto|plain|json picks the narration format.
• -q, --quiet keeps only warnings and errors.
• --verbose adds debug lines.
• --output text|json picks the data format, for a command that adds it.

Where to go next

• Getting started: build a small CLI step by step.
• The guide: narration, tasks, data, commands, testing, signals and exit.
• The reference: flags, environment, JSON events, terminal, exit codes.
• Conventions: the house style for what a command prints.

License

MIT, see LICENSE.

Documentation

Overview

Package clix wires the global flags --quiet, --verbose, --color and --narration, the console, exit codes and signal handling around a cobra command tree. A main needs only a few lines: build the root command and call clix.Run(root, clix.Options{...}). The house style for what a command prints is in docs/conventions.md and the contract in docs/reference.

Example

package main

import (
	"context"

	"github.com/spf13/cobra"

	"github.com/vi-dev/clix"
	"github.com/vi-dev/clix/console"
)

func main() {
	root := &cobra.Command{
		Use: "demo",
		RunE: func(cmd *cobra.Command, args []string) error {
			clix.ConsoleOf(cmd).Infof("hello")
			return nil
		},
	}
	clix.Run(root, clix.Options{
		App:       "demo",
		Version:   "0.1.0",
		EnvPrefix: "DEMO",
		Setup: func(ctx context.Context, c *console.Console) (context.Context, error) {
			return ctx, nil
		},
	})
}

Index

• func AddOutputFlag(cmd *cobra.Command, output *string)
• func ConsoleOf(cmd *cobra.Command) *console.Console
• func Execute(ctx context.Context, root *cobra.Command, opts Options) (int, error)
• func OutputFlag(cmd *cobra.Command) *string
• func Run(root *cobra.Command, opts Options)
• func ValidateOutput(output string) error
• type ExitError
  • func (e *ExitError) Error() string
• type Options
• type SignalError
  • func (e SignalError) Error() string

Examples

• Package

Functions

func AddOutputFlag

func AddOutputFlag(cmd *cobra.Command, output *string)

AddOutputFlag adds the --output flag to cmd and stores its value in output. The default is text.

func ConsoleOf

func ConsoleOf(cmd *cobra.Command) *console.Console

ConsoleOf returns the console of a command run through Run or Execute, and panics for any other command.

func Execute

func Execute(ctx context.Context, root *cobra.Command, opts Options) (int, error)

Execute runs root like Run but returns the exit code and the command's error instead of exiting, and does not handle signals.

func OutputFlag

func OutputFlag(cmd *cobra.Command) *string

OutputFlag adds the --output flag to cmd, rejects any value other than text or json before the command runs, and returns the value.

func Run

func Run(root *cobra.Command, opts Options)

Run executes root with the global flags, the console and signal handling, then exits the process with the run's exit code.

func ValidateOutput

func ValidateOutput(output string) error

ValidateOutput returns an error unless output is text or json.

Types

type ExitError

type ExitError struct{ Code int }

ExitError ends the run with exit code Code and no error line.

func (*ExitError) Error

func (e *ExitError) Error() string

Error reports the exit code.

type Options

type Options struct {
	// App names the program in JSON narration; empty means the root command's name.
	App string
	// Version is the program version in JSON narration; empty means the root command's Version.
	Version string
	// EnvPrefix makes <EnvPrefix>_NARRATION choose the narration format; empty means no variable is read.
	EnvPrefix string
	// Hint returns the hint shown under the final error, or an empty string for none; nil means no hints.
	Hint func(error) string
	// Setup runs once the console is ready and returns the context the command runs with; an error from it ends the run like an error from the command.
	Setup func(ctx context.Context, c *console.Console) (context.Context, error)
}

Options configures Execute and Run.

type SignalError

type SignalError struct{ Sig os.Signal }

SignalError is the cause of the context's cancellation when Run receives a signal, with Sig naming that signal.

func (SignalError) Error

func (e SignalError) Error() string

Error names the signal received.