sxcli.dev█Simple Extensible CLI█
You are viewing an archived snapshot (v0.1.0). Switch to the current version →

Getting started

Install#

Add the framework to your module:

sh
sh
go get sxcli.dev/fw

A minimal binary#

The framework owns main. Import the providers you want linked into the binary and hand over control:

go
go
package main

import (
    fw "sxcli.dev/fw"
    _ "sxcli.dev/fw/sink/console"
    _ "sxcli.dev/fw/configfmt/yaml"
)

func main() { fw.Main() }

Your first applet#

An applet is a service implementing Configured() error and Run() int. Register it from an init() function, with a config struct whose field values are the defaults:

go
go
package hello

import (
    "fmt"

    fw "sxcli.dev/fw"
)

type Config struct {
    Name string `json:"name" arg:"name,n" usage:"who to greet"`
}

type Hello struct{ cfg Config }

func (h *Hello) Configured() error { return nil }

func (h *Hello) Run() int {
    fmt.Println("hello,", h.cfg.Name)
    return 0
}

func init() {
    h := &Hello{cfg: Config{Name: "world"}} // field values are the defaults
    fw.Register("hello", h, fw.WithConfig(&h.cfg))
}

Blank-import the package from main and the applet is part of the binary:

go
go
package main

import (
    fw "sxcli.dev/fw"
    _ "sxcli.dev/fw/sink/console"
    _ "sxcli.dev/fw/configfmt/yaml"

    _ "example.com/myapp/hello" // your applet registers itself in init()
)

func main() { fw.Main() }

Run it#

With a single applet registered, the whole argument vector belongs to it:

sh
sh
$ hello                # hello, world
$ hello --name gopher  # hello, gopher
$ HELLO_NAME=go hello  # hello, go — env name derived from the arg name
$ hello --help         # full argument schema, current effective values

The same field is settable from a config file ({"hello": {"name": "…"}} in JSON, or the YAML equivalent), the environment, or the command line — precedence is defaults < config files < environment < arguments.

JSON is the native config format — always enabled, nothing to import. The configfmt/yaml import in main.go is purely additive: it teaches the binary .yaml/.yml on top of the built-in JSON. Drop the import and JSON configs keep working.

Next: Your config struct — every supported type and tag, and how each value is set from arguments, environment and files.