launchr

README

Launchr

Launchr is a versatile CLI action runner that executes tasks defined in local or embeded yaml files across multiple runtimes:

• Short-lived container (docker or kubernetes)
• Shell (host)
• Golang (as plugin)

It supports:

• Arguments and options
• Automatic action discovery
• Automatic path-based naming of local actions
• Seamless extensibility via a plugin system

Actions are defined in action.yaml files:

• either on local filesystem: Useful for project-specific actions
• or embeded as plugin: Useful for common and shared actions

You can find action examples here and in the documentation.

Launchr has a plugin system that allows to extend its functionality. See core plugins, official plugins and documentation.

Table of contents

• Usage
• Installation
  • Installation from source
• Development

Usage

Build launchr from source locally. Build dependencies:

1. go >=1.24, see installation guide
2. make

Build the launchr tool:

make
bin/launchr --help

The documentation for launchr usage can be found in docs.

If you face any issues with launchr:

1. Open an issue in the repo.
2. Share the app version with launchr --version

Installation

Installation from source

Build dependencies:

1. go >=1.24, see installation guide
2. make

Global installation

Install launchr globally:

make install
launchr --version

The tool will be installed in $GOPATH/bin which is usually ~/go/bin. If GOPATH env variable is not available, make sure you have it in ~/.bashrc or ~/.zhrc:

export GOPATH=`go env GOPATH`
export PATH=$PATH:$GOPATH/bin

Local installation

The tool can be built and run locally:

make
bin/launchr --version

Development

The launchr can be built with a make to bin directory:

make

It is also supported to make a build to use with dlv for debug:

make DEBUG=1

Useful make commands:

1. Fetch dependencies - make deps
2. Test the code - make test
3. Lint the code - make lint

Publishing a new release

• Create a new Github release from UI
• Github Action will compile new binaries using goreleaser and attach them to release

Documentation

Overview

Package launchr has application implementation.

Index

• Constants
• func EnsurePath(parts ...string) error
• func FsRealpath(fs fs.FS) string
• func Gen() int
• func GenAndExit()
• func MustAbs(path string) string
• func MustSubFS(fsys fs.FS, path string) fs.FS
• func NewExitError(code int, msg string) error
• func NewMaskingWriter(w io.Writer, mask *SensitiveMask) io.WriteCloser
• func RegisterCleanupFn(fn func() error)
• func RegisterPlugin(p Plugin)
• func Run() int
• func RunAndExit()
• func SetLogger(l *Logger)
• func StdInOutErr() (stdIn io.ReadCloser, stdOut, stdErr io.Writer)
• type ActionDiscoveryPlugin
• type App
• type AppVersion
  • func Version() *AppVersion
• type CobraPlugin
• type Command
• type Config
• type EnvVar
• type ExitError
• type GenerateConfig
• type GeneratePlugin
• type In
  • func NewIn(in io.ReadCloser) *In
• type LogLevel
• type LogOptions
• type Logger
  • func Log() *Logger
  • func NewConsoleLogger(w io.Writer) *Logger
  • func NewJSONHandlerLogger(w io.Writer) *Logger
  • func NewTextHandlerLogger(w io.Writer) *Logger
• type ManagedFS
• type MaskingWriter
• type OnAppInitPlugin
• type Out
  • func NewOut(out io.Writer) *Out
• type PersistentPreRunPlugin
• type Plugin
• type PluginInfo
• type PluginManager
• type SensitiveMask
• type Service
• type ServiceInfo
• type Slog
• type Streams
  • func MaskedStdStreams(mask *SensitiveMask) Streams
  • func NewBasicStreams(in io.ReadCloser, out io.Writer, err io.Writer, ...) Streams
  • func NoopStreams() Streams
• type Template
• type Terminal
  • func Term() *Terminal
• type TextPrinter

Constants

const (
	LogLevelDisabled = launchr.LogLevelDisabled // LogLevelDisabled does never print.
	LogLevelDebug    = launchr.LogLevelDebug    // LogLevelDebug is the log level for debug.
	LogLevelInfo     = launchr.LogLevelInfo     // LogLevelInfo is the log level for info.
	LogLevelWarn     = launchr.LogLevelWarn     // LogLevelWarn is the log level for warnings.
	LogLevelError    = launchr.LogLevelError    // LogLevelError is the log level for errors.
)

Log levels.

const (
	// EnvVarRootParentPID defines parent process id. May be used by forked processes.
	EnvVarRootParentPID = launchr.EnvVarRootParentPID
	// EnvVarActionsPath defines path where to search for actions.
	EnvVarActionsPath = launchr.EnvVarActionsPath
	// EnvVarLogLevel defines currently set log level.
	EnvVarLogLevel = launchr.EnvVarLogLevel
	// EnvVarLogFormat defines currently set log format, see --log-format flag.
	EnvVarLogFormat = launchr.EnvVarLogFormat
	// EnvVarQuietMode defines if the application should output anything, see --quiet flag.
	EnvVarQuietMode = launchr.EnvVarQuietMode
)

Application environment variables.

const PkgPath = launchr.PkgPath

PkgPath is a main module path.

Functions

func EnsurePath

func EnsurePath(parts ...string) error

EnsurePath creates all directories in the path.

func FsRealpath

func FsRealpath(fs fs.FS) string

FsRealpath returns absolute path for a fs.FS interface.

func Gen

func Gen() int

Gen generates application specific build files and returns os exit code.

func GenAndExit

func GenAndExit()

GenAndExit runs the generation and exits with a result code.

func MustAbs

func MustAbs(path string) string

MustAbs returns absolute filepath and panics on error.

func MustSubFS

func MustSubFS(fsys fs.FS, path string) fs.FS

MustSubFS returns an fs.FS corresponding to the subtree rooted at fsys's dir.

func NewExitError

func NewExitError(code int, msg string) error

NewExitError creates a new ExitError.

func NewMaskingWriter

func NewMaskingWriter(w io.Writer, mask *SensitiveMask) io.WriteCloser

NewMaskingWriter initializes a new MaskingWriter.

func RegisterCleanupFn

func RegisterCleanupFn(fn func() error)

RegisterCleanupFn saves a function to be executed on Cleanup. It is run on the termination of the application.

func RegisterPlugin

func RegisterPlugin(p Plugin)

RegisterPlugin add a plugin to global pull.

func Run

func Run() int

Run executes the application.

func RunAndExit

func RunAndExit()

RunAndExit runs the application and exits with a result code.

func SetLogger

func SetLogger(l *Logger)

SetLogger sets the default logger.

func StdInOutErr

func StdInOutErr() (stdIn io.ReadCloser, stdOut, stdErr io.Writer)

StdInOutErr returns the standard streams (stdin, stdout, stderr).

On Windows, it attempts to turn on VT handling on all std handles if supported, or falls back to terminal emulation. On Unix, this returns the standard os.Stdin, os.Stdout and os.Stderr.

Types

type ActionDiscoveryPlugin

type ActionDiscoveryPlugin = action.DiscoveryPlugin

ActionDiscoveryPlugin is an interface to implement a plugin to discover actions.

type App

type App = launchr.App

App stores global application state.

type AppVersion

type AppVersion = launchr.AppVersion

AppVersion stores application version.

func Version

func Version() *AppVersion

Version provides app version info.

type CobraPlugin

type CobraPlugin = launchr.CobraPlugin

CobraPlugin is an interface to implement a plugin for cobra.

type Command

type Command = launchr.Command

Command is an application command to execute.

type Config

type Config = launchr.Config

Config handles application configuration.

type EnvVar

type EnvVar = launchr.EnvVar

EnvVar defines an environment variable and provides an interface to interact with it by prefixing the current app name. For example, if "my_var" is given as the variable name and the app name is "launchr", the accessed environment variable will be "LAUNCHR_MY_VAR".

type ExitError

type ExitError = launchr.ExitError

ExitError is an error holding an error code of executed command.

type GenerateConfig

type GenerateConfig = launchr.GenerateConfig

GenerateConfig defines generation config.

type GeneratePlugin

type GeneratePlugin = launchr.GeneratePlugin

GeneratePlugin is an interface to generate supporting files before build.

type In

type In = launchr.In

In is an input stream used by the app to read user input.

func NewIn

func NewIn(in io.ReadCloser) *In

NewIn returns a new In object from a io.ReadCloser.

type LogLevel

type LogLevel = launchr.LogLevel

A LogLevel is the importance or severity of a log event.

type LogOptions

type LogOptions = launchr.LogOptions

LogOptions is a common interface to allow adjusting the logger.

type Logger

type Logger = launchr.Logger

Logger is a logger and its config holder struct.

func Log

func Log() *Logger

Log returns the default logger.

func NewConsoleLogger

func NewConsoleLogger(w io.Writer) *Logger

NewConsoleLogger creates a default console logger.

func NewJSONHandlerLogger

func NewJSONHandlerLogger(w io.Writer) *Logger

NewJSONHandlerLogger creates a logger with a io.Writer and JSON output.

func NewTextHandlerLogger

func NewTextHandlerLogger(w io.Writer) *Logger

NewTextHandlerLogger creates a logger with a io.Writer and plain output.

type ManagedFS

type ManagedFS = launchr.ManagedFS

ManagedFS is a File System managed by launchr.

type MaskingWriter

type MaskingWriter = launchr.MaskingWriter

MaskingWriter is a writer that masks sensitive data in the input stream. It buffers data to handle cases where sensitive data spans across writes.

type OnAppInitPlugin

type OnAppInitPlugin = launchr.OnAppInitPlugin

OnAppInitPlugin is an interface to implement a plugin for app initialisation.

type Out

type Out = launchr.Out

Out is an output stream used by the app to write normal program output.

func NewOut

func NewOut(out io.Writer) *Out

NewOut returns a new Out object from a io.Writer.

type PersistentPreRunPlugin

type PersistentPreRunPlugin = launchr.PersistentPreRunPlugin

PersistentPreRunPlugin is an interface to implement a plugin to run before any command is run and all arguments are parsed.

type Plugin

type Plugin = launchr.Plugin

Plugin is a common interface for launchr plugins.

type PluginInfo

type PluginInfo = launchr.PluginInfo

PluginInfo provides information about the plugin and is used as a unique data to indentify a plugin.

type PluginManager

type PluginManager = launchr.PluginManager

PluginManager handles plugins.

type SensitiveMask

type SensitiveMask = launchr.SensitiveMask

SensitiveMask replaces sensitive strings with a mask.

type Service

type Service = launchr.Service

Service is a common interface for a service to register.

type ServiceInfo

type ServiceInfo = launchr.ServiceInfo

ServiceInfo provides service info for its initialization.

type Slog

type Slog = launchr.Slog

Slog is an alias for a go structured logger [slog.Logger] to reduce visible dependencies.

type Streams

type Streams = launchr.Streams

Streams is an interface which exposes the standard input and output streams.

func MaskedStdStreams

func MaskedStdStreams(mask *SensitiveMask) Streams

MaskedStdStreams sets a cli in, out and err streams with the standard streams and with masking of sensitive data.

func NewBasicStreams

func NewBasicStreams(in io.ReadCloser, out io.Writer, err io.Writer, fns ...launchr.StreamsModifierFn) Streams

NewBasicStreams creates streams with given in, out and err streams. Give decorate functions to extend functionality.

func NoopStreams

func NoopStreams() Streams

NoopStreams provides streams like /dev/null.

type Template

type Template = launchr.Template

Template provides templating functionality to generate files.

type Terminal

type Terminal = launchr.Terminal

Terminal prints formatted text to the console.

func Term

func Term() *Terminal

Term returns default Terminal to print application messages to the console.

type TextPrinter

type TextPrinter = launchr.TextPrinter

TextPrinter contains methods to print formatted text to the console or return it as a string.