conductor

README

conductor

🎼 One-shot initialization for Go CLIs.

conductor glues together clib (themed help, shell completions), clog (structured logging) and clive (versioning, self-update): fill in one App struct at program start and your CLI inherits the whole stack - house logging style, unified env-var prefixes, themed help, completion management, version plumbing and passive update notifications - while remaining free to call any of the underlying libraries directly.

Packages

Package	Description
conductor	App/Runtime core: logging defaults, flags, notify, version
cli/cobra	Cobra integration
cli/kong	Kong integration
cli/urfave	urfave/cli integration

Installation

go get github.com/gechr/conductor

Usage

app := conductor.New(conductor.App{
    Name:        "demo",
    Description: "Demo application.",
    Module:      "github.com/you/demo",
    Updater: brew.New(
        clive.Info{Module: "github.com/you/demo"},
        brew.WithFormula("demo"),
        brew.WithTap("you/tap"),
    ),
})

var cli CLI // your kong grammar, embedding ckong.Flags
prog, err := ckong.New(app, &cli)
if err != nil {
    clog.Fatal().Err(err).Msg("Failed to build CLI")
}
os.Exit(prog.Run(os.Args[1:]))

That one New + Program.Run pair replaces the bootstrap every tool otherwise hand-rolls: clog output/format setup, clog.SetEnvPrefix + theme.SetEnvPrefix, theme.Auto() → help.NewRenderer → help-printer wiring, the Reflect → completion-generator → preflight block, post-parse --color/--verbose/--quiet application, version flag/subcommand, and the passive update check with its deferred hint flush and skip-on-update logic.

See examples/ for runnable kong, cobra and urfave demo apps.

Lifecycle

1. conductor.New(App) - pre-parse phase. Sets the env prefix on clog and clib, applies LogDefaults (stderr output with auto color, space-separated slices, human-friendly duration gradients), runs your ConfigureLog hook, resolves the theme (before any output, so background detection is clean) and builds the help renderer.
2. Adapter New(app, ...) - builds/wires the parser or command tree: themed help, standard flags, -V/version, completion flags and the update notification hook.
3. Program.Run(...) - completion preflight, parse, post-parse flag application (--verbose/--quiet/--color → clog), passive update check (skipped for update, version, help and completion verbs), dispatch, deferred update-hint flush, and error → exit-code mapping. Pass the result to os.Exit.

Standard flags

Every adapter provides the same trio plus completion management:

Flag	Effect
-v, --verbose	clog.SetVerbose(true)
-q, --quiet	clog.SetLevel(clog.LevelError)
--color <mode>	clog.SetColorMode (auto default)
-V, --version	Print the version

Kong CLIs embed ckong.Flags; cobra and urfave register them as persistent/root flags automatically.

Version stamping

conductor standardises on clive's linker variables - no per-app version var needed:

go build -ldflags "-X github.com/gechr/clive.version=$(VERSION) -X github.com/gechr/clive.buildTime=$(BUILD_TIME)"

Without stamping, clive falls back to Go module build info, then the VCS revision.

Update notifications

Set App.Updater to any updater.Tool (brew.New, goinstall.New, github.New) to enable the passive "update available" hint, cached and rate-limited by clive. The standard update subcommand (UpdateCmd for kong; UpdateCommand for cobra/urfave) self-updates via whichever install method App.Updater uses - Homebrew, go install, or GitHub release download - with --check, --stable, --dev and --no-uninstall (the latter two are Homebrew-specific: other methods treat stable as the default channel and manage no conflicting copies). The <APP>_NO_UPDATE_CHECK env var disables the hint entirely.

Escape hatches

conductor is a thin layer over the same public APIs you would call yourself, and never blocks direct use of them:

• App.ConfigureLog runs after LogDefaults - the place for direct clog customisation (symbols, styles, parts, custom levels).
• App.SkipLogDefaults opts out of the house style; the standalone conductor.LogDefaults() opts into it without the rest.
• Runtime.Theme/Runtime.Renderer and every Program field are exported and replaceable before Run.
• Adapter options (WithKongOptions, WithSections, WithGenerator, WithExitCode, ...) append after conductor's defaults, so they can override anything.
• Tools with bespoke needs skip the relevant piece (don't embed the flags, provide your own update command) and keep the rest.

Documentation

Overview

Package conductor wires up the gechr CLI libraries (clib, clog, clive) in one shot. A consumer fills in an App at program start, calls New, and inherits the house logging style, a themed help renderer, unified env-var prefixes, version plumbing, and passive update notifications - while remaining free to call any of the underlying libraries directly.

Index

• Constants
• func ExitCode(err error, custom func(error) int) int
• func LogDefaults()
• type App
  • func (a App) HelpLongDesc() string
  • func (a App) HelpShortDesc() string
• type FlagSource
• type Flags
• type Runtime
  • func New(app App) *Runtime
  • func (r *Runtime) ApplyFlags(f Flags)
  • func (r *Runtime) Notify(command string) func()
  • func (r *Runtime) PrintVersion(detailed bool)
  • func (r *Runtime) Version() string

Constants

const EnvPrefixNone = "-"

EnvPrefixNone disables env-prefix unification, leaving clog and clib on their own defaults (CLOG and CLIB).

Functions

func ExitCode

func ExitCode(err error, custom func(error) int) int

ExitCode maps a command error to a process exit code, shared by all framework adapters: nil is 0; updater.ErrReported is 1 without further output (the failure is already on screen); otherwise the optional custom mapper decides, falling back to logging the error and returning 1.

func LogDefaults

func LogDefaults()

LogDefaults applies the house clog style shared by every tool: stderr output with automatic color detection, space-separated slices, and human-friendly duration fields with a 20s gradient. It is exported so a tool that skips conductor entirely can still opt into the house style.

Types

type App

type App struct {
	// Name is the binary name, e.g. "demo". Required.
	Name string
	// Description is the one-line description used in help output.
	Description string

	// EnvPrefix unifies clog.SetEnvPrefix and clib theme.SetEnvPrefix under a
	// single application prefix. It defaults to Name upper-cased with dashes
	// mapped to underscores. Set [EnvPrefixNone] to leave both libraries on
	// their own defaults.
	EnvPrefix string

	// Module is the Go module path, e.g. "github.com/gechr/demo". It enables
	// clive release links and latest-version lookups.
	Module string
	// Repo is the GitHub "owner/name"; derived from Module when empty.
	Repo string
	// Private resolves latest-version lookups via GOPRIVATE-scoped version
	// control instead of the public module proxy.
	Private bool

	// Updater enables the passive update notification; nil disables it. Any
	// [updater.Tool] works, e.g. brew.New(...), goinstall.New(...) or
	// github.New(...).
	Updater updater.Tool
	// NotifyOptions are appended after conductor's own notify options.
	NotifyOptions []notify.Option
	// NotifySkip lists extra command verbs that suppress the update check, in
	// addition to the built-in "update", "version", "help" and completion
	// verbs.
	NotifySkip []string
	// NotifyOnly, when non-empty, restricts the update check to exactly these
	// command verbs.
	NotifyOnly []string

	// Theme overrides the help theme; nil means [theme.Auto].
	Theme *theme.Theme
	// HelpOptions are passed to [help.NewRenderer].
	HelpOptions []help.RendererOption
	// HelpShort is the terse description of -h (default "Print short help").
	HelpShort string
	// HelpLong is the terse description of --help (default "Print long
	// help, including examples").
	HelpLong string

	// SkipLogDefaults skips [LogDefaults] for tools with a fully bespoke
	// logging setup.
	SkipLogDefaults bool
	// ConfigureLog runs after [LogDefaults] and before anything logs; the
	// place for direct clog customisation (symbols, styles, custom levels).
	ConfigureLog func()
}

App declares everything conductor needs to initialize a CLI tool. Name is required; every other field has a sensible zero value.

func (App) HelpLongDesc

func (a App) HelpLongDesc() string

HelpLongDesc returns the terse --help description, defaulted.

func (App) HelpShortDesc

func (a App) HelpShortDesc() string

HelpShortDesc returns the terse -h description, defaulted.

type FlagSource

type FlagSource interface {
	ConductorFlags() Flags
}

FlagSource is implemented by CLI values that expose the standard flags, usually by embedding a framework adapter's flag struct. Adapters apply the flags automatically after parsing when the CLI value implements it.

type Flags

type Flags struct {
	Verbose bool
	Quiet   bool
	Color   clog.ColorMode
}

Flags are the framework-neutral post-parse flag values shared by every tool: verbosity and color mode.

type Runtime

type Runtime struct {
	App      App
	Info     clive.Info
	Theme    *theme.Theme
	Renderer *help.Renderer
}

Runtime is everything New builds. All fields are exported and may be replaced before handing the Runtime to a framework adapter.

func New

func New(app App) *Runtime

New initializes the libraries in dependency order and returns the shared Runtime. It must run before anything logs so that env prefixes, output and theme detection settle first. It panics when app.Name is empty - a programmer error on par with an invalid CLI grammar.

func (*Runtime) ApplyFlags

func (r *Runtime) ApplyFlags(f Flags)

ApplyFlags is the post-parse phase: it maps the standard flags onto clog. Tools with bespoke verbosity semantics skip FlagSource and call clog directly instead.

func (*Runtime) Notify

func (r *Runtime) Notify(command string) func()

Notify starts the passive update check for the resolved command and returns a flush function - never nil - that the caller runs after the command completes, so the hint trails normal output. The check is skipped when App.Updater is nil, when the command's verb is one of the built-in skip verbs or App.NotifySkip, or when App.NotifyOnly is set and does not contain the verb. clive's <APP>_NO_UPDATE_CHECK kill switch still applies underneath.

func (*Runtime) PrintVersion

func (r *Runtime) PrintVersion(detailed bool)

PrintVersion writes the version to stdout: the bare string, or a labelled table of build details (with release hyperlinks when Module/Repo is set) when detailed is true.

func (*Runtime) Version

func (r *Runtime) Version() string

Version returns the running binary's version via clive.Current: ldflag-injected, module build info, or VCS revision - whichever resolves first - with a friendly placeholder when nothing resolves.