Viper

https://github.com/spf13/viper
Admin
Viper is a complete configuration solution for Go applications, supporting defaults, multiple file...
Tokens:88,479
Snippets:712
Trust Score:9.9
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### Configuring file watching with OnConfigChange

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Example showing how to define configuration paths, register a change handler, and start the watcher.

```go
// All config paths must be defined prior to calling WatchConfig()
v.AddConfigPath("$HOME/.appname")

v.OnConfigChange(func(e fsnotify.Event) {
	fmt.Println("Config file changed:", e.Name)
})

v.WatchConfig()
```

--------------------------------

### Viper Get Method Usage

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

Example demonstrating how Get retrieves values, showing how explicit sets override default values.

```go
v.SetDefault("endpoint", "https://localhost")
v.Set("endpoint", "https://example.com")
v.Get("endpoint") // "https://example.com"
```

--------------------------------

### Install Viper with go get

Source: https://github.com/spf13/viper/blob/master/README.md

Install the Viper library using Go modules. Run this command in your Go project directory.

```shell
go get github.com/spf13/viper
```

--------------------------------

### Set usage examples

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Examples of setting configuration values, including nested keys.

```go
v.Set("verbose", true)
v.Set("host.port", 5899) // embedded key
```

--------------------------------

### Usage Example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Example of using multiple options with NewWithOptions.

```APIDOC
## Usage Example

### Description
Example of using multiple options with NewWithOptions.

### Code
```go
v := viper.NewWithOptions(
	viper.WithLogger(slog.New(slog.NewTextHandler(os.Stderr, nil))),
	viper.KeyDelimiter("::"),
	viper.WithCodecRegistry(codecRegistry),
)
```
```

--------------------------------

### SetDefault usage examples

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Examples of setting default values for simple and map types.

```go
v.SetDefault("ContentDir", "content")
v.SetDefault("Taxonomies", map[string]string{"tag": "tags", "category": "categories"})
```

--------------------------------

### WithDecodeHook usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-unmarshal.md

Example of initializing a Viper instance with a custom decode hook.

```go
v := viper.NewWithOptions(
	viper.WithDecodeHook(mapstructure.ComposeDecodeHookFunc(
		mapstructure.StringToTimeDurationHookFunc(),
	)),
)
```

--------------------------------

### Usage of NewWithOptions

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Example of initializing a Viper instance with specific configuration options.

```go
v := viper.NewWithOptions(
	viper.KeyDelimiter("::"),
	viper.EnvKeyReplacer(envKeyReplacer),
)
```

--------------------------------

### BindEnv usage examples

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Examples showing how to bind a key to an environment variable, either using the default prefix or by specifying explicit environment variable names.

```go
if err := viper.BindEnv("id"); err != nil { /* ... */ } // looks for SPF_ID with prefix "spf"
if err := viper.BindEnv("id", "ID", "APP_ID"); err != nil { /* ... */ }
```

--------------------------------

### Marshaling AllSettings to YAML

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

Example of retrieving all settings and marshaling them into YAML format.

```go
c := viper.AllSettings()
bs, err := yaml.Marshal(c)
if err != nil {
	log.Fatalf("unable to marshal config to YAML: %v", err)
}
fmt.Println(string(bs))
```

--------------------------------

### MustBindEnv usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

A simple example of using MustBindEnv to bind a key to an environment variable.

```go
viper.MustBindEnv("id")
```

--------------------------------

### JSON configuration with nested keys and array indexes

Source: https://github.com/spf13/viper/blob/master/README.md

Example configuration showing nested keys and array indexes used with Viper's Get* functions. Keys use '.' as delimiter and numbers for array indexes.

```jsonc
{
    "datastore": {
        "metric": {
            "host": "127.0.0.1",
            "ports": [
                5799,
                6029
            ]
        }
    }
}

```

--------------------------------

### Viper NewWithOptions usage

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Example of initializing a new Viper instance with multiple configuration options.

```go
v := viper.NewWithOptions(
	viper.WithLogger(slog.New(slog.NewTextHandler(os.Stderr, nil))),
	viper.KeyDelimiter("::"),
	viper.WithCodecRegistry(codecRegistry),
)
```

--------------------------------

### Configuration writing usage examples

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Common patterns for writing configurations to files or standard output.

```go
v.WriteConfig()                      // to resolved path (overwrites)
v.SafeWriteConfig()                  // errors if exists
v.WriteConfigAs("/path/to/my/.config")
v.SafeWriteConfigAs("/path/to/my/.other_config")
v.WriteConfigTo(os.Stdout)           // prints marshaled config
```

--------------------------------

### Package-level Get function delegation

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper.md

Example of how exported package-level functions delegate calls to the singleton instance.

```go
func Get(key string) any { return v.Get(key) }
```

--------------------------------

### AddRemoteProvider usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

Example of adding an etcd provider and reading the remote configuration. Note that SetConfigType is required when the remote source does not provide a file extension.

```go
if err := viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.json"); err != nil {
	// handle
}
viper.SetConfigType("json") // no extension in a byte stream
if err := viper.ReadRemoteConfig(); err != nil { /* ... */ }
```

--------------------------------

### AddSecureRemoteProvider usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

Example of adding a secure remote provider using a GPG keyring file for decryption.

```go
if err := viper.AddSecureRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.json", "/etc/secrets/mykeyring.gpg"); err != nil {
	// handle
}
```

--------------------------------

### Unmarshal usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-unmarshal.md

Example of unmarshaling configuration into a struct with mapstructure tags.

```go
type config struct {
	Port    int
	Name    string
	PathMap string `mapstructure:"path_map"`
}

var C config
if err := viper.Unmarshal(&C); err != nil {
	t.Fatalf("unable to decode into struct, %v", err)
}
```

--------------------------------

### BindPFlags usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Example of binding the command-line flag set to Viper.

```go
pflag.Int("flagname", 1234, "help message for flagname")
pflag.Parse()
if err := viper.BindPFlags(pflag.CommandLine); err != nil { /* ... */ }
i := viper.GetInt("flagname")
```

--------------------------------

### Remote configuration polling example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

Example of setting up a runtime Viper instance to poll for remote configuration updates using WatchRemoteConfig.

```go
runtimeViper := viper.New()
runtimeViper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.yml")
runtimeViper.SetConfigType("yaml")

if err := runtimeViper.ReadRemoteConfig(); err != nil { /* ... */ }
runtimeViper.Unmarshal(&runtimeConf)

go func() {
	for {
		time.Sleep(time.Second * 5)
		if err := runtimeViper.WatchRemoteConfig(); err != nil {
			log.Printf("unable to read remote config: %v", err)
			continue
		}
		runtimeViper.Unmarshal(&runtimeConf)
	}
}()
```

--------------------------------

### RegisterAlias usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Demonstrates creating an alias for a key and verifying that both the alias and the original key return the same value.

```go
v.RegisterAlias("loud", "Verbose")
v.Set("verbose", true)
v.GetBool("loud")    // true
v.GetBool("verbose") // true
```

--------------------------------

### UnmarshalKey usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-unmarshal.md

Example of unmarshaling a specific configuration key into an integer variable.

```go
var port int
if err := viper.UnmarshalKey("server.port", &port); err != nil {
	// handle error
}
```

--------------------------------

### UnmarshalExact usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-unmarshal.md

Example of using UnmarshalExact to ensure no unknown keys exist in the configuration.

```go
var C config
if err := viper.UnmarshalExact(&C); err != nil {
	// errors on unknown keys in the config
}
```

--------------------------------

### BindPFlag usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-binding.md

Example of binding a specific flag from a command to a Viper key.

```go
serverCmd.Flags().Int("port", 1138, "Port to run Application server on")
if err := viper.BindPFlag("port", serverCmd.Flags().Lookup("port")); err != nil {
	// handle
}
```

--------------------------------

### Reading configuration from io.Reader

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Example of reading a YAML configuration from a buffer using ReadConfig.

```go
v.SetConfigType("yaml")
var yamlExample = []byte("hacker: true\nname: steve\n")
if err := v.ReadConfig(bytes.NewBuffer(yamlExample)); err != nil { /* ... */ }
v.Get("name") // "steve"
```

--------------------------------

### Bridge Standard Library Flags to Viper

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-flags.md

Example of using the standard library flag package by bridging it through pflag.

```go
package main

import (
	"flag"

	"github.com/spf13/pflag"
	"github.com/spf13/viper"
)

func main() {
	// Using standard library "flag" package
	flag.Int("flagname", 1234, "help message for flagname")

	// Pass standard library flags to pflag
	pflag.CommandLine.AddGoFlagSet(flag.CommandLine)
	pflag.Parse()

	// Viper takes over
	if err := viper.BindPFlags(pflag.CommandLine); err != nil {
		panic(err)
	}

	i := viper.GetInt("flagname") // retrieve from viper instead of pflag
	_ = i
}
```

--------------------------------

### Usage with Standard Library flag Package

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-flags.md

Example showing how to use the standard library flag package with Viper by bridging through pflag.

```APIDOC
## Usage with Standard Library flag Package

### Description
This example demonstrates how to use the standard library flag package with Viper by adding the standard flags to pflag and then binding them.

### Code Example
```go
package main

import (
	"flag"

	"github.com/spf13/pflag"
	"github.com/spf13/viper"
)

func main() {
	// Using standard library "flag" package
	flag.Int("flagname", 1234, "help message for flagname")

	// Pass standard library flags to pflag
	pflag.CommandLine.AddGoFlagSet(flag.CommandLine)
	pflag.Parse()

	// Viper takes over
	if err := viper.BindPFlags(pflag.CommandLine); err != nil {
		panic(err)
	}

	i := viper.GetInt("flagname") // retrieve from viper instead of pflag
	_ = i
}
```
```

--------------------------------

### Enable Go Modules with GO111MODULE=on

Source: https://github.com/spf13/viper/blob/master/TROUBLESHOOTING.md

Command to switch to Go Modules mode, which resolves the 'cannot find package' error. This is the recommended solution for Viper installation issues.

```bash
export GO111MODULE=on
```

--------------------------------

### Usage: Register a custom format

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-encoding.md

Example of registering a custom codec and using it with Viper.

```APIDOC
## Usage: Register a custom format

### Description
Register a custom format and read/write with it.

### Code Example
```go
package main

import (
	"fmt"

	"github.com/spf13/viper"
)

// MyCodec implements viper.Codec for a custom format.
type MyCodec struct{}

func (MyCodec) Encode(v map[string]any) ([]byte, error) {
	// custom serialization
	return []byte(fmt.Sprintf("%v", v)), nil
}

func (MyCodec) Decode(b []byte, v map[string]any) error {
	// custom parsing
	v["name"] = "from-custom-format"
	return nil
}

func main() {
	codecRegistry := viper.NewCodecRegistry()
	_ = codecRegistry.RegisterCodec("myformat", &MyCodec{})

	v := viper.NewWithOptions(
		viper.WithCodecRegistry(codecRegistry),
	)

	v.SetConfigType("myformat")
	// ... read/write using the custom codec
}
```
```

--------------------------------

### Handling ReadInConfig errors

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Example demonstrating how to check for FileLookupError when calling ReadInConfig.

```go
var fileLookupError viper.FileLookupError
if err := viper.ReadInConfig(); err != nil {
	if errors.As(err, &fileLookupError) {
		// explicitly set file missing, or nothing found in search paths
	} else {
		// file found but another error occurred
	}
}
```

--------------------------------

### YAML configuration for cache subsets

Source: https://github.com/spf13/viper/blob/master/README.md

Example YAML configuration with cache sections used to demonstrate viper.Sub for extracting configuration subsets.

```yaml
cache:
  cache1:
    item-size: 64
    max-items: 100
  cache2:
    item-size: 80
    max-items: 200

```

--------------------------------

### Custom Flag Implementation

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-flags.md

Example of implementing FlagValue and FlagValueSet to avoid pflag dependency.

```go
type myFlag struct{}

func (f myFlag) HasChanged() bool    { return true }
func (f myFlag) Name() string        { return "my-flag-name" }
func (f myFlag) ValueString() string { return "my-flag-value" }
func (f myFlag) ValueType() string   { return "string" }

// in your app:
if err := viper.BindFlagValue("my-flag-name", myFlag{}); err != nil {
	panic(err)
}

type myFlagSet struct {
	flags []myFlag
}

func (f myFlagSet) VisitAll(fn func(viper.FlagValue)) {
	for _, flag := range f.flags {
		fn(flag)
	}
}

fSet := myFlagSet{flags: []myFlag{{}, {}}}
if err := viper.BindFlagValues(fSet); err != nil {
	panic(err)
}
```

--------------------------------

### Go package installation error output

Source: https://github.com/spf13/viper/blob/master/TROUBLESHOOTING.md

Error message shown when Viper installation fails due to GOPATH mode. The error indicates Go cannot find the package 'github.com/hashicorp/hcl/tree/hcl1' in GOROOT or GOPATH. This occurs when dependencies are not managed with Go Modules.

```plaintext
cannot find package "github.com/hashicorp/hcl/tree/hcl1" in any of:
/usr/local/Cellar/go/1.15.7_1/libexec/src/github.com/hashicorp/hcl/tree/hcl1 (from $GOROOT)
/Users/user/go/src/github.com/hashicorp/hcl/tree/hcl1 (from $GOPATH)
```

--------------------------------

### Run the test suite with make test

Source: https://github.com/spf13/viper/blob/master/README.md

Executes the project's test suite. Requires Go installed or the development environment set up via Nix/direnv or make deps.

```shell
make test
```

--------------------------------

### Implement FlagValue and FlagValueSet interfaces

Source: https://github.com/spf13/viper/blob/master/README.md

Avoid pflag entirely by implementing the FlagValue and FlagValueSet interfaces. The example shows minimal implementations and how to bind them with viper.BindFlagValue and viper.BindFlagValues.

```go
// Implementing FlagValue

type myFlag struct {}
func (f myFlag) HasChanged() bool { return false }
func (f myFlag) Name() string { return "my-flag-name" }
func (f myFlag) ValueString() string { return "my-flag-value" }
func (f myFlag) ValueType() string { return "string" }

viper.BindFlagValue("my-flag-name", myFlag{})

// Implementing FlagValueSet

type myFlagSet struct {
	flags []myFlag
}
func (f myFlagSet) VisitAll(fn func(FlagValue)) {
	for _, flag := range flags {
		fn(flag)
	}
}

fSet := myFlagSet{
	flags: []myFlag{myFlag{}, myFlag{}},
}
viper.BindFlagValues("my-flags", fSet)
```

--------------------------------

### Usage: Restore HCL/INI/Java-properties support

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-encoding.md

Example of restoring support for HCL, INI, and Java properties formats using the codec registry.

```APIDOC
## Usage: Restore HCL/INI/Java-properties support

### Description
Restore HCL/INI/Java-properties support (from UPGRADE.md).

### Code Example
```go
import (
	"github.com/go-viper/encoding/hcl"
	"github.com/go-viper/encoding/javaproperties"
	"github.com/go-viper/encoding/ini"
)

codecRegistry := viper.NewCodecRegistry()

codecRegistry.RegisterCodec("hcl", hcl.Codec{})
codecRegistry.RegisterCodec("tfvars", hcl.Codec{})
codecRegistry.RegisterCodec("properties", &javaproperties.Codec{})
codecRegistry.RegisterCodec("props", &javaproperties.Codec{})
codecRegistry.RegisterCodec("prop", &javaproperties.Codec{})
codecRegistry.RegisterCodec("ini", ini.Codec{})

v := viper.NewWithOptions(
	viper.WithCodecRegistry(codecRegistry),
)
```
```

--------------------------------

### Usage with Custom Flag Implementation

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-flags.md

Example showing how to implement FlagValue and FlagValueSet interfaces to use a custom flag library with Viper.

```APIDOC
## Usage with Custom Flag Implementation

### Description
This example demonstrates how to implement the FlagValue and FlagValueSet interfaces to use a custom flag library with Viper.

### Code Example
```go
type myFlag struct{}

func (f myFlag) HasChanged() bool    { return true }
func (f myFlag) Name() string        { return "my-flag-name" }
func (f myFlag) ValueString() string { return "my-flag-value" }
func (f myFlag) ValueType() string   { return "string" }

// in your app:
if err := viper.BindFlagValue("my-flag-name", myFlag{}); err != nil {
	panic(err)
}

type myFlagSet struct {
	flags []myFlag
}

func (f myFlagSet) VisitAll(fn func(viper.FlagValue)) {
	for _, flag := range f.flags {
		fn(flag)
	}
}

fSet := myFlagSet{flags: []myFlag{{}, {}}}
if err := viper.BindFlagValues(fSet); err != nil {
	panic(err)
}
```
```

--------------------------------

### GetString and GetInt with nested keys

Source: https://github.com/spf13/viper/blob/master/README.md

Shows how to retrieve values using GetString and GetInt with dot-delimited keys. Get* functions return zero values if the key is not found.

```go
GetString("datastore.metric.host") // "127.0.0.1"
GetInt("host.ports.1") // 6029

```

--------------------------------

### etcd Remote Provider Example

Source: https://github.com/spf13/viper/blob/master/README.md

Configures Viper to read from an etcd remote provider at http://127.0.0.1:4001 with the key /config/hugo.json. The config type is set to json because the stream has no file extension.

```go
viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001","/config/hugo.json")
viper.SetConfigType("json") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
err := viper.ReadRemoteConfig()
```

--------------------------------

### Basic singleton usage

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper.md

Demonstrates how to set the configuration file name, type, and search path, then read the configuration and access values with defaults.

```go
package main

import (
	"fmt"

	"github.com/spf13/viper"
)

func main() {
	viper.SetConfigName("config")
	viper.SetConfigType("yaml")
	viper.AddConfigPath(".")

	if err := viper.ReadInConfig(); err != nil {
		panic(fmt.Errorf("fatal error config file: %w", err))
	}

	viper.SetDefault("port", 8080)

	fmt.Println(viper.GetString("name"))
	fmt.Println(viper.GetInt("port"))
}
```

--------------------------------

### WatchRemoteConfigOnChannel function signature

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

Starts a goroutine per provider to consume remote configuration updates from a channel.

```go
func (v *Viper) WatchRemoteConfigOnChannel() error
```

--------------------------------

### Usage of New and basic configuration

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Demonstrates creating a new instance and setting default or override values.

```go
v := viper.New()
v.SetDefault("ContentDir", "content")
v.Set("verbose", true)
fmt.Println(v.Get("ContentDir")) // "content"
```

--------------------------------

### WatchConfig

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Starts watching the config file for changes in a background goroutine using fsnotify. It resolves the config file, watches the entire directory, and re-reads the config on write, create, or symlink changes.

```APIDOC
## WatchConfig

### Description
Starts watching the config file for changes in a background goroutine using fsnotify. It resolves the config file, watches the entire directory, and re-reads the config on write, create, or symlink changes.

### Method
WatchConfig

### Signature
func (v *Viper) WatchConfig()

### Behavior
- Resolves the config file via getConfigFile; on error logs and returns.
- Watches the entire directory to catch renames/atomic saves.
- On a Write or Create event for the config file, or when the real path (via EvalSymlinks, e.g. k8s ConfigMap replacement) changes, it re-runs v.ReadInConfig() and invokes v.onConfigChange(event).
- On Remove of the config file, the watcher goroutine ends.
- If fsnotify.NewWatcher() fails, logs and calls os.Exit(1).
- Returns after the init goroutine has started the watch (initWG.Wait()).

### Source
viper.go:282
```

--------------------------------

### Viper Typed Getters Usage

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

Examples of using typed getters to access nested keys and parsing human-readable size strings into byte counts.

```go
v.Set("host.ports", []int{5799, 6029})
v.GetInt("host.ports.1")        // 6029
v.GetString("datastore.metric.host")

v.Set("cache.limit", "256MB")
v.GetSizeInBytes("cache.limit") // 268435456
```

--------------------------------

### SetEnvPrefix method

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Defines a prefix that environment variables will use. When a prefix is set, Viper looks for variables starting with the prefix followed by an underscore and the key name.

```go
func (v *Viper) SetEnvPrefix(in string)
```

```go
v.SetEnvPrefix("spf")   // v.BindEnv("id") -> looks for SPF_ID
```

--------------------------------

### Crypt command-line helper for encrypted config

Source: https://github.com/spf13/viper/blob/master/README.md

Use the crypt command-line helper to set and get configurations in a key/value store. Encryption is optional and requires a GPG keyring.

```bash
$ go get github.com/sagikazarmark/crypt/bin/crypt
$ crypt set -plaintext /config/hugo.json /Users/hugo/settings/config.json
$ crypt get -plaintext /config/hugo.json
```

--------------------------------

### etcd3 Remote Provider Example

Source: https://github.com/spf13/viper/blob/master/README.md

Configures Viper to read from an etcd3 remote provider at http://127.0.0.1:4001 with the key /config/hugo.json. The config type is set to json because the stream has no file extension.

```go
viper.AddRemoteProvider("etcd3", "http://127.0.0.1:4001","/config/hugo.json")
viper.SetConfigType("json") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
err := viper.ReadRemoteConfig()
```

--------------------------------

### Use standard library flag with pflag and Viper

Source: https://github.com/spf13/viper/blob/master/README.md

The standard library flag package is not directly supported, but can be parsed through pflag. This example shows passing standard library flags to pflag and then binding to Viper.

```go
package main

import (
	"flag"

	"github.com/spf13/pflag"
)

func main() {
	// Using standard library "flag" package
	flag.Int("flagname", 1234, "help message for flagname")

    // Pass standard library flags to pflag
	pflag.CommandLine.AddGoFlagSet(flag.CommandLine)
	pflag.Parse()

    // Viper takes over
	viper.BindPFlags(pflag.CommandLine)
}
```

--------------------------------

### AddConfigPath

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Adds a path for Viper to search for the config file in. May be called multiple times; duplicate absolute paths are not re-added. The path is absolutized via absPathify ($HOME and os.ExpandEnv are expanded). No-op when in == "". If a custom Finder is installed, logs a warning that the call is ineffective.

```APIDOC
## AddConfigPath

### Description
Adds a path for Viper to search for the config file in. May be called multiple times; duplicate absolute paths are not re-added. The path is absolutized via absPathify ($HOME and os.ExpandEnv are expanded). No-op when in == "". If a custom Finder is installed, logs a warning that the call is ineffective.

### Method
AddConfigPath

### Signature
func (v *Viper) AddConfigPath(in string)

### Parameters
- **in** (string) - Required - The path to add.

### Usage Example
```go
v.AddConfigPath("/etc/appname/")
v.AddConfigPath("$HOME/.appname")
v.AddConfigPath(".")
```
```

--------------------------------

### Watching Remote Config Changes

Source: https://github.com/spf13/viper/blob/master/README.md

Creates a new Viper instance, reads remote config from etcd, and starts a goroutine that watches for changes every 5 seconds. It unmarshals the config into a runtime struct and logs errors if reading fails. Currently only tested with etcd support.

```go
// Alternatively, you can create a new viper instance
var runtime_viper = viper.New()

runtime_viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.yml")
runtime_viper.SetConfigType("yaml") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"

// Read from remote config the first time
err := runtime_viper.ReadRemoteConfig()

// Unmarshal config
runtime_viper.Unmarshal(&runtime_conf)

// Open a goroutine to watch remote changes forever
go func(){
	for {
		time.Sleep(time.Second * 5) // delay after each request

		// Currently, only tested with Etcd support
		err := runtime_viper.WatchRemoteConfig()
		if err != nil {
			log.Errorf("unable to read remote config: %v", err)
			continue
		}

		// Unmarshal new config into our runtime config struct
		runtime_viper.Unmarshal(&runtime_conf)
	}
}()
```

--------------------------------

### Initialize a new Viper instance with NewWithOptions

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Creates a new Viper instance and applies the provided options in order.

```go
func NewWithOptions(opts ...Option) *Viper
```

--------------------------------

### Viper Get Method Signature

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

The base Get method signature used to retrieve raw values.

```go
func (v *Viper) Get(key string) any
```

--------------------------------

### SetTypeByDefaultValue usage example

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Example showing how to enable type inference so that a default value of []string{} correctly casts an environment variable string into a slice.

```go
v.SetDefault("tags", []string{})
v.SetTypeByDefaultValue(true)
os.Setenv("TAGS", "a b c") // after v.BindEnv("tags")
v.Get("tags")              // []string{"a","b","c"}
```

--------------------------------

### Inspect Viper state and configuration file

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Demonstrates using DebugTo to print registry contents to stdout and ConfigFileUsed to check if a configuration file is loaded.

```go
v := viper.New()
v.Set("foo", "bar")
v.DebugTo(os.Stdout)

if v.ConfigFileUsed() == "" {
	fmt.Println("no config file loaded")
}
```

--------------------------------

### Initialize a new Viper instance with New

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

The New function returns an initialized Viper instance with default settings.

```go
func New() *Viper
```

--------------------------------

### Execute Go text templates with viper-template

Source: https://github.com/spf13/viper/wiki/Tips-and-tricks

Demonstrates using the viper-template library to store and execute Go templates within Viper configuration values.

```go
package main

import (
	"fmt"
	"text/template"

	"github.com/spf13/viper"
	vipertemplate "github.com/sv-tools/viper-template"
)

func main() {
	v := viper.New()
	v.Set("foo", `{{ Get "bar" }}`)
	v.Set("bar", `{{ Mul . 2 }}`)

	type Data struct {
		Bar int
	}
	data := Data{
		Bar: 42,
	}

	funcs := template.FuncMap{
		"Mul": func(d *Data, v int) int {
			return d.Bar * v
		},
	}

	val, err := vipertemplate.Get(
		"foo",
		vipertemplate.WithViper(v),
		vipertemplate.WithData(&data),
		vipertemplate.WithFuncs(funcs),
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(val)
	// Output: 84
}
```

--------------------------------

### Create and configure multiple Viper instances

Source: https://github.com/spf13/viper/blob/master/README.md

Shows how to create two independent Viper instances using viper.New() and set different defaults for each. Each instance has its own unique configuration and can read from a different configuration source.

```go
x := viper.New()
y := viper.New()

x.SetDefault("ContentDir", "content")
y.SetDefault("ContentDir", "foobar")
```

--------------------------------

### Initialize Viper with a custom Finder

Source: https://github.com/spf13/viper/blob/master/UPGRADE.md

Use the WithFinder option to supply a custom implementation of the Finder interface to a new Viper instance.

```go
v := viper.NewWithOptions(
    viper.WithFinder(&MyFinder{}),
)
```

--------------------------------

### SetTypeByDefaultValue

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Enables inference of a key's value type from its default value when using Get. When enabled, Get casts the fetched value to the type of the default (bool, string, ints, uints, floats, time, duration, slices) via the cast package.

```APIDOC
## SetTypeByDefaultValue

### Description
Enables inference of a key's value type from its default value when using Get. When enabled, Get casts the fetched value to the type of the default (bool, string, ints, uints, floats, time, duration, slices) via the cast package.

### Method
SetTypeByDefaultValue

### Signature
func (v *Viper) SetTypeByDefaultValue(enable bool)

### Parameters
- **enable** (bool) - Required - Whether to enable type inference from default values.

### Example
```go
v.SetDefault("tags", []string{})
v.SetTypeByDefaultValue(true)
os.Setenv("TAGS", "a b c") // after v.BindEnv("tags")
v.Get("tags")              // []string{"a","b","c"}
```

### Source
viper.go:690
```

--------------------------------

### Registering a custom format

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-encoding.md

Demonstrates implementing the viper.Codec interface and registering it with a new CodecRegistry to read and write custom formats.

```go
package main

import (
	"fmt"

	"github.com/spf13/viper"
)

// MyCodec implements viper.Codec for a custom format.
type MyCodec struct{}

func (MyCodec) Encode(v map[string]any) ([]byte, error) {
	// custom serialization
	return []byte(fmt.Sprintf("%v", v)), nil
}

func (MyCodec) Decode(b []byte, v map[string]any) error {
	// custom parsing
	v["name"] = "from-custom-format"
	return nil
}

func main() {
	codecRegistry := viper.NewCodecRegistry()
	_ = codecRegistry.RegisterCodec("myformat", &MyCodec{})

	v := viper.NewWithOptions(
		viper.WithCodecRegistry(codecRegistry),
	)

	v.SetConfigType("myformat")
	// ... read/write using the custom codec
}
```

--------------------------------

### Remote package init function

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

The initialization logic that assigns the remote configuration provider to Viper.

```go
func init() {
	viper.RemoteConfig = &remoteConfigProvider{}
}
```

--------------------------------

### AllSettings method signature

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

The function signature for retrieving all configuration settings as a map.

```go
func (v *Viper) AllSettings() map[string]any
```

--------------------------------

### Debug

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Prints all registries (aliases, override, pflags, env, kvstore, config, defaults) to os.Stdout.

```APIDOC
## Debug

### Description
Prints all registries (aliases, override, pflags, env, kvstore, config, defaults) to os.Stdout.

### Method
Debug

### Signature
func (v *Viper) Debug()

### Parameters
None

### Return Value
None

### Example
```go
v := viper.New()
v.Set("foo", "bar")
v.Debug()
```
```

--------------------------------

### Unmarshal with custom decode hook

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-unmarshal.md

Example of providing a custom decode hook to the Unmarshal method.

```go
err := viper.Unmarshal(&appConfig, viper.DecodeHook(mapstructure.ComposeDecodeHookFunc(
	mapstructure.StringToTimeDurationHookFunc(),
	mapstructure.StringToSliceHookFunc(","),
)))
```

--------------------------------

### WriteConfigTo method

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-io.md

Marshals the current configuration and writes it to the provided io.Writer.

```go
func (v *Viper) WriteConfigTo(w io.Writer) error
```

--------------------------------

### Blank import viper/remote for remote support

Source: https://github.com/spf13/viper/blob/master/README.md

Enable remote key/value store support by blank importing the viper/remote package.

```go
import _ "github.com/spf13/viper/remote"
```

--------------------------------

### Get

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-getters.md

Retrieves the value associated with the key, returning the first source that has it. Returns nil if unset.

```APIDOC
## Get

### Description
Retrieves the value associated with the key, returning the first source that has it. Returns nil if unset. If typeByDefValue is enabled, the value is cast to the type of the default value.

### Method
Get

### Signature
func (v *Viper) Get(key string) any

### Parameters
- **key** (string) - Required - The key to retrieve.

### Returns
- **any** - The raw stored value, or nil if unset.

### Example
```go
v.SetDefault("endpoint", "https://localhost")
v.Set("endpoint", "https://example.com")
v.Get("endpoint") // "https://example.com"
```

### Notes
Shadowing behavior: the find algorithm returns nil when a shorter path holds a non-map value and would shadow a longer path in a lower-priority source.
```

--------------------------------

### AllowEmptyEnv method

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Configures whether set-but-empty environment variables are considered valid. When true, empty values are accepted instead of falling back to other sources.

```go
func (v *Viper) AllowEmptyEnv(allowEmptyEnv bool)
```

```go
func (v *Viper) getEnv(key string) (string, bool) {
	if v.envKeyReplacer != nil {
		key = v.envKeyReplacer.Replace(key)
	}

	val, ok := os.LookupEnv(key)

	return val, ok && (v.allowEmptyEnv || val != "")
}
```

```go
v.AllowEmptyEnv(true)
```

--------------------------------

### Unmarshal with custom decoder config

Source: https://github.com/spf13/viper/blob/master/UPGRADE.md

Example of using the updated mapstructure dependency when providing a custom decoder configuration.

```go
err := viper.Unmarshal(&appConfig, func(config *mapstructure.DecoderConfig) {
	config.TagName = "yaml"
})
```

--------------------------------

### Marshal all settings to YAML string

Source: https://github.com/spf13/viper/blob/master/README.md

Shows how to marshal all Viper settings to a YAML string using AllSettings and yaml.Marshal. The function logs a fatal error if marshalling fails.

```go
import (
	yaml "go.yaml.in/yaml/v3"
)

func yamlStringSettings() string {
	c := viper.AllSettings()
	bs, err := yaml.Marshal(c)
	if err != nil {
		log.Fatalf("unable to marshal config to YAML: %v", err)
	}
	return string(bs)
}

```

--------------------------------

### Using viper.Sub to extract configuration subset

Source: https://github.com/spf13/viper/blob/master/README.md

Shows how to use viper.Sub to extract a subset of configuration for a reusable module. Sub returns nil if the key cannot be found, so check for nil before using.

```go
func NewCache(v *Viper) *Cache {
	return &Cache{
		ItemSize: v.GetInt("item-size"),
		MaxItems: v.GetInt("max-items"),
	}
}

cache1Config := viper.Sub("cache.cache1")

if cache1Config == nil {
    // Sub returns nil if the key cannot be found
	panic("cache configuration not found")
}

cache1 := NewCache(cache1Config)

```

--------------------------------

### Apply options to the global singleton with SetOptions

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-type.md

Applies options to the global singleton. Note that subsequent calls may override previous settings; using a local instance is preferred.

```go
func SetOptions(opts ...Option)
```

--------------------------------

### Register a custom codec

Source: https://github.com/spf13/viper/blob/master/UPGRADE.md

Create a new codec registry and register custom formats using the WithCodecRegistry option.

```go
codecRegistry := viper.NewCodecRegistry()

codecRegistry.RegisterCodec("myformat", &MyCodec{})

v := viper.NewWithOptions(
    viper.WithCodecRegistry(codecRegistry),
)
```

--------------------------------

### func WithLogger(l *slog.Logger) Option

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper.md

Returns an Option that sets a custom logger for Viper. Use this to integrate Viper with your logging setup.

```APIDOC
## func WithLogger(l *slog.Logger) Option

### Description
Returns an Option that sets a custom logger for Viper. Use this to integrate Viper with your logging setup.

### Signature
`func WithLogger(l *slog.Logger) Option`

### Parameters
- **l** (*slog.Logger) - Required - The logger to use.

### Returns
- **Option** - An option to pass to Viper constructor.
```

--------------------------------

### Watch and re-read config files

Source: https://github.com/spf13/viper/blob/master/README.md

Watch a config file for changes and run a callback on each change. All config paths must be defined prior to calling WatchConfig().

```go
// All config paths must be defined prior to calling `WatchConfig()`
viper.AddConfigPath("$HOME/.appname")

viper.OnConfigChange(func(e fsnotify.Event) {
	fmt.Println("Config file changed:", e.Name)
})

viper.WatchConfig()
```

--------------------------------

### Unmarshal into embedded structs

Source: https://github.com/spf13/viper/blob/master/README.md

Shows how to unmarshal into embedded structs using mapstructure squash tag. The example includes a comment showing the expected configuration format.

```go
/*
Example config:

module:
    enabled: true
    token: 89h3f98hbwf987h3f98wenf89ehf
*/
type config struct {
	Module struct {
		Enabled bool

		moduleConfig `mapstructure:",squash"`
	}
}

type moduleConfig struct {
	Token string
}

var C config

err := viper.Unmarshal(&C)
if err != nil {
	t.Fatalf("unable to decode into struct, %v", err)
}

```

--------------------------------

### GetEnvPrefix method

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Returns the currently configured environment variable prefix.

```go
func (v *Viper) GetEnvPrefix() string
```

--------------------------------

### NATS Remote Provider Example

Source: https://github.com/spf13/viper/blob/master/README.md

Configures Viper to read from a NATS remote provider at nats://127.0.0.1:4222 with the subject myapp.config. The config type is set to json.

```go
viper.AddRemoteProvider("nats", "nats://127.0.0.1:4222", "myapp.config")
viper.SetConfigType("json")
err := viper.ReadRemoteConfig()
```

--------------------------------

### FlagValue Interface

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-flags.md

The FlagValue interface represents a single bound flag. It provides methods to check if the flag has changed, get its name, value as string, and type.

```APIDOC
## FlagValue Interface

### Description
The FlagValue interface defines a single bound flag. It is used by Viper to retrieve flag information during value resolution.

### Interface Definition
```go
type FlagValue interface {
	HasChanged() bool
	Name() string
	ValueString() string
	ValueType() string
}
```

### Methods
- **HasChanged()** (bool) - Returns whether the flag's value was explicitly changed. Only changed flags are used when resolving values.
- **Name()** (string) - Returns the flag name, used as the config key by BindFlagValues.
- **ValueString()** (string) - Returns the flag value as a string.
- **ValueType()** (string) - Returns the flag's type name, used to select the conversion in find (e.g., "int", "bool", "stringSlice").
```

--------------------------------

### Global singleton initialization

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper.md

The package-level singleton instance v is initialized during the package init phase.

```go
var v *Viper

func init() {
	v = New()
}
```

--------------------------------

### Restoring HCL, INI, and Java properties support

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-encoding.md

Shows how to manually register codecs for HCL, INI, and Java properties formats using a custom CodecRegistry.

```go
import (
	"github.com/go-viper/encoding/hcl"
	"github.com/go-viper/encoding/javaproperties"
	"github.com/go-viper/encoding/ini"
)

codecRegistry := viper.NewCodecRegistry()

codecRegistry.RegisterCodec("hcl", hcl.Codec{})
codecRegistry.RegisterCodec("tfvars", hcl.Codec{})
codecRegistry.RegisterCodec("properties", &javaproperties.Codec{})
codecRegistry.RegisterCodec("props", &javaproperties.Codec{})
codecRegistry.RegisterCodec("prop", &javaproperties.Codec{})
codecRegistry.RegisterCodec("ini", ini.Codec{})

v := viper.NewWithOptions(
	viper.WithCodecRegistry(codecRegistry),
)
```

--------------------------------

### WatchRemoteConfigOnChannel

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-remote.md

Starts a goroutine per provider that consumes RemoteResponse from the provider's watch channel and unmarshals each payload into the internal store. Returns an error if no providers are configured.

```APIDOC
## WatchRemoteConfigOnChannel

### Description
Starts a goroutine per provider that consumes RemoteResponse from the provider's watch channel and unmarshals each payload into the internal store. Returns RemoteConfigError if no providers are configured.

### Method
WatchRemoteConfigOnChannel

### Signature
func (v *Viper) WatchRemoteConfigOnChannel() error

### Parameters
None.

### Request Example
```go
runtimeViper := viper.New()
runtimeViper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.yml")
runtimeViper.SetConfigType("yaml")

if err := runtimeViper.ReadRemoteConfig(); err != nil { /* ... */ }
runtimeViper.Unmarshal(&runtimeConf)

go func() {
    for {
        time.Sleep(time.Second * 5)
        if err := runtimeViper.WatchRemoteConfig(); err != nil {
            log.Printf("unable to read remote config: %v", err)
            continue
        }
        runtimeViper.Unmarshal(&runtimeConf)
    }
}()
```

### Response
Returns nil on success. Returns RemoteConfigError if no providers are configured.
```

--------------------------------

### Define a custom Finder interface

Source: https://github.com/spf13/viper/blob/master/UPGRADE.md

The Finder interface allows customization of how Viper searches for configuration files within an afero.Fs filesystem.

```go
// Finder looks for files and directories in an [afero.Fs] filesystem.
type Finder interface {
	Find(fsys afero.Fs) ([]string, error)
}
```

--------------------------------

### NewCodecRegistry function

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-encoding.md

Returns a new, ready-to-use registry with the codec map initialized via sync.Once.

```go
func NewCodecRegistry() *DefaultCodecRegistry
```

--------------------------------

### Read config file with Viper

Source: https://github.com/spf13/viper/blob/master/README.md

Configure Viper to search for and read a config file. Set the config name and add search paths, then call ReadInConfig and handle errors. At least one path should be provided.

```go
// Name of the config file without an extension (Viper will intuit the type
// from an extension on the actual file)
viper.SetConfigName("config")

// Add search paths to find the file
viper.AddConfigPath("/etc/appname/")
viper.AddConfigPath("$HOME/.appname")
viper.AddConfigPath(".")

// Find and read the config file
err := viper.ReadInConfig()

// Handle errors
if err != nil {
	panic(fmt.Errorf("fatal error config file: %w", err))
}
```

--------------------------------

### WithFinder constructor option

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-finder.md

Sets a custom Finder on the Viper instance. Note that this takes precedence over AddConfigPath, SetConfigName, and SetConfigType, which will log warnings if called.

```go
func WithFinder(f Finder) Option
```

--------------------------------

### SetConfigName

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Sets the name for the config file (without extension). Clears configFile (v.configFile = ""). No-op when in == "". If a custom Finder is installed, logs a warning that the call is ineffective.

```APIDOC
## SetConfigName

### Description
Sets the name for the config file (without extension). Clears configFile (v.configFile = ""). No-op when in == "". If a custom Finder is installed, logs a warning that the call is ineffective.

### Method
SetConfigName

### Signature
func (v *Viper) SetConfigName(in string)

### Parameters
- **in** (string) - Required - The config file name without extension.

### Usage Example
```go
v.SetConfigName("appconfig") // looks for appconfig.json, appconfig.yaml, ...
```
```

--------------------------------

### SetConfigFile usage

Source: https://github.com/spf13/viper/blob/master/_autodocs/api-reference/viper-config-setters.md

Explicitly defines the path, name, and extension of the config file. Viper will use this exact file and ignore configured search paths.

```go
v.SetConfigFile("/etc/app/config.yaml")
err := v.ReadInConfig()
```
Tokens:
Raw