Charm Fang

charm-fang

Fang is NOT a Cobra replacement - it wraps Cobra. You still write *cobra.Command structs exactly as you would with plain Cobra. Fang intercepts execution to add:

• styled help/usage output (lipgloss-rendered)
• styled error output with an ERROR header block
• auto --version from build info or a string you provide
• hidden man subcommand (manpage via mango/roff)
• completion subcommand for shell completions
• SilenceUsage = true by default (no help dump on error)
• signal handling via WithNotifySignal

Install

go get charm.land/fang/v2

Import path (v2, note the vanity domain):

import "charm.land/fang/v2"

Minimal App

package main

import (
    "context"
    "os"

    "charm.land/fang/v2"
    "github.com/spf13/cobra"
)

func main() {
    root := &cobra.Command{
        Use:   "myapp",
        Short: "Does something useful",
    }
    if err := fang.Execute(context.Background(), root); err != nil {
        os.Exit(1)
    }
}

That's the full swap from root.Execute() to fang.Execute().

Complete CLI Skeleton

package main

import (
    "context"
    "os"

    "charm.land/fang/v2"
    "github.com/spf13/cobra"
)

func main() {
    var name string
    var verbose bool

    root := &cobra.Command{
        Use:     "myapp [flags]",
        Short:   "One-line description",
        Long:    "Longer description shown in full help.",
        Version: "1.0.0", // overridden by fang if you use WithVersion
        Example: `
  # basic usage
  myapp --name alice

  # with subcommand
  myapp greet --name alice`,
        RunE: func(cmd *cobra.Command, args []string) error {
            cmd.Printf("Hello, %s\n", name)
            return nil
        },
    }

    // persistent flags available to all subcommands
    root.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "verbose output")
    // local flags for root only
    root.Flags().StringVar(&name, "name", "world", "name to greet")

    // subcommand
    greet := &cobra.Command{
        Use:   "greet",
        Short: "Greet someone",
        RunE: func(cmd *cobra.Command, args []string) error {
            cmd.Println("greet subcommand")
            return nil
        },
    }
    root.AddCommand(greet)

    if err := fang.Execute(
        context.Background(),
        root,
        fang.WithVersion("1.2.3"),
        fang.WithCommit("abc1234"),
        fang.WithNotifySignal(os.Interrupt),
    ); err != nil {
        os.Exit(1)
    }
}

Options Reference

| Option | Effect | |--------|--------| | WithVersion(v string) | Sets version string shown by --version | | WithCommit(sha string) | Appends short commit SHA to version | | WithoutVersion() | Disables -v/--version entirely | | WithoutCompletions() | Removes the completion subcommand | | WithoutManpage() | Removes the hidden man subcommand | | WithNotifySignal(signals...) | Cancels context on given OS signals | | WithColorSchemeFunc(fn) | Custom theme, light/dark-adaptive | | WithErrorHandler(fn) | Custom error rendering |

If no WithVersion is passed, fang reads debug.ReadBuildInfo() automatically (works when installed via go install).

Custom Theme

import "charm.land/lipgloss/v2"

fang.Execute(ctx, root, fang.WithColorSchemeFunc(func(ld lipgloss.LightDarkFunc) fang.ColorScheme {
    return fang.ColorScheme{
        Title:   ld(lipgloss.Color("#FF6B6B"), lipgloss.Color("#4ECDC4")),
        Flag:    lipgloss.Color("#0CB37F"),
        Command: lipgloss.Color("#A550DF"),
        // ... other fields
    }
}))

LightDarkFunc lets you return different colors based on terminal background. Use fang.DefaultColorScheme or fang.AnsiColorScheme as a reference.

Differences from Plain Cobra

| Cobra | Fang | |-------|------| | root.Execute() | fang.Execute(ctx, root, opts...) | | plain text help | lipgloss-styled help | | errors printed raw | styled error block | | manual signal handling | WithNotifySignal | | manual manpage setup | built-in hidden man cmd | | SilenceUsage off by default | on by default | | no version auto-detect | reads build info automatically |

Flag Patterns (Cobra, unchanged)

// string flag with short form
cmd.Flags().StringVarP(&val, "name", "n", "default", "description")

// persistent (inherited by subcommands)
cmd.PersistentFlags().BoolVar(&debug, "debug", false, "enable debug")

// hidden flag
cmd.Flags().String("internal", "", "internal use")
_ = cmd.Flags().MarkHidden("internal")

// required flag
cmd.Flags().String("config", "", "config file")
_ = cmd.MarkFlagRequired("config")

Command Groups

root.AddGroup(&cobra.Group{
    ID:    "core",
    Title: "Core Commands",
})
sub.GroupID = "core"

Groups show as sections in fang's styled help output.

Context Usage

Subcommands get the context fang passes (with signal cancellation if configured):

RunE: func(cmd *cobra.Command, args []string) error {
    select {
    case <-time.After(5 * time.Second):
        return nil
    case <-cmd.Context().Done():
        return cmd.Context().Err()
    }
},

go.mod

require (
    charm.land/fang/v2 v2.x.x
    github.com/spf13/cobra v1.x.x
)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alxxpersonal
• Source: alxxpersonal/forge
• License: MIT

Install and usage instructions live in the source repository linked above.