How to gate flags and subcommands behind features
A feature is a named setting, on or off or a numbered level, that the person running your CLI changes at run time. While its feature is on, a gated flag or subcommand appears in --help and shell completion and accepts input, and a gated flag gets a row in --why.
This guide builds the HTTP server from the feature toggles example. It declares four features, gates two flags and one subcommand behind them, and turns them on from each source.
Declare the features
Section titled “Declare the features”Declare the features in a field of the root command struct whose type is the container conga.Features[...]. The type in the brackets is a struct, and each of its exported fields is one feature, named after the field in kebab-case (AdminAPI becomes admin-api). A bool field is off unless its default tag says otherwise:
type experiments struct { HTTP3 bool `stage:"alpha" help:"Experimental HTTP/3 (QUIC) listener"` AdminAPI bool `stage:"alpha" help:"Experimental admin API"` StrictTLS bool `stage:"beta" default:"true" help:"Require TLS and reject weak ciphers"` Metrics bool `stage:"beta" default:"true" help:"Expose the metrics endpoint"`}
type CLI struct { Features conga.Features[experiments] `flag:"feature-gates" env:"API_FEATURES" config:"features"`}The three container tags name the places a user can set features from: the --feature-gates flag, the API_FEATURES variable, and the features: section of a config file. Each tag is optional, so declare only the sources your users need. For the environment, each feature can have its own variable instead, as Give each feature its own environment variable shows.
Enable features
Section titled “Enable features”Turn on feature support by calling EnableFeatures() on the application builder:
app := conga.New[CLI](). Name("feature-toggles"). EnableFeatures(). EnableWhy()The root help screen now lists every feature, its stage, and its default:
Features: http3 Experimental HTTP/3 (QUIC) listener [alpha] admin-api Experimental admin API [alpha] strict-tls Require TLS and reject weak ciphers [beta] [default: true] metrics Expose the metrics endpoint [beta] [default: true]Gate a flag
Section titled “Gate a flag”Add a feature tag naming the feature the flag depends on. Here the feature is http3 and the flag it gates is --quic:
type CLI struct { Features conga.Features[experiments] `flag:"feature-gates" env:"API_FEATURES" config:"features"`
Listen conga.OptionalFlag[string] `default:":8080" help:"Listen address"` QUIC conga.OptionalFlag[bool] `feature:"http3" help:"Enable the QUIC/HTTP3 listener (experimental)"`}--quic appears in --help once http3 is on. Before that, typing it gives a usage error (exit code 2):
$ feature-toggles --quicError:feature-toggles: error: flag '--quic' requires feature "http3"Error
Usage: feature-toggles [flags]
Run 'feature-toggles --help' for more information.Turn the feature on and the flag appears in --help and works:
feature-toggles --feature-gates http3=true --quicThe feature tag works on OptionalFlag, Counter, ConfigFile, and Command[T] fields. A required flag can’t be gated, because it would be required while it doesn’t exist. Here QUIC was made a RequiredFlag:
Error:feature-toggles: error: struct CLI field QUIC: schema error: invalid struct tag: tag "feature" cannot be used on required flags (feature-gated flags must be optional)ErrorGate a subcommand
Section titled “Gate a subcommand”Put the same tag on a Command[T] field. The subcommand and everything beneath it disappear together:
Admin conga.Command[AdminCmd] `feature:"admin-api" summary:"Experimental admin API"`$ feature-toggles adminError:feature-toggles: error: command "admin" requires feature "admin-api"Error
Usage: feature-toggles admin [flags]
Run 'feature-toggles admin --help' for more information.Show a flag only while a feature is off
Section titled “Show a flag only while a feature is off”Prefix the feature name with !. The example keeps a plaintext escape hatch that exists only while strict TLS is off:
AllowInsecure conga.OptionalFlag[bool] `feature:"!strict-tls" help:"Serve plaintext (development only)"`strict-tls defaults to on, so --allow-insecure appears once a user runs with --feature-gates strict-tls=false. Before that, the error says which state the feature must be in:
$ feature-toggles --allow-insecureError:feature-toggles: error: flag '--allow-insecure' requires feature "strict-tls" to be offError
Usage: feature-toggles [flags]
Run 'feature-toggles --help' for more information.To require several conditions, separate them with commas. All of them must hold. feature:"http3,!strict-tls" gates a member on http3 being on and strict-tls being off. The expression table lists the forms.
Turn features on
Section titled “Turn features on”Each source changes only the features it names, and the rest keep their values from lower sources.
From the command line:
feature-toggles --feature-gates http3=true,admin-api=trueFrom the environment, using the variable named by the container’s env tag:
API_FEATURES=strict-tls=false feature-toggles --allow-insecureWith envprefix, each feature has its own variable instead (see Give each feature its own environment variable).
From a config file, under the section named by the container’s config tag. The application must register a decoder for the file format (see How to manage config files):
features: http3: true admin-api: truefeature-toggles -c features.yaml adminWhen two sources set the same feature, the command line beats the environment, which beats the config file, which beats the default tag. Here the environment turns http3 off and the command line turns it back on:
$ API_FEATURES=http3=false feature-toggles --feature-gates http3=truefeatures: http3=true admin-api=false strict-tls=true metrics=trueOn the command line and in the environment, users may spell a name in kebab-case, snake_case, or camelCase, so admin-api, admin_api, and adminApi are the same feature. A config file takes the feature name spelled in the app’s config key casing (admin-api by default), like every other config key:
features: admin_api: true$ feature-toggles -c features.yamlError:feature-toggles: error: config file "features.yaml": unknown field "admin_api" in section "features" (did you mean "admin-api"?)ErrorCheck which source set each feature
Section titled “Check which source set each feature”Run with --why to see each feature’s value and the source that set it:
$ API_FEATURES=admin-api=true feature-toggles -c features.yaml --whyValue provenance for "feature-toggles":Features:
FEATURE VALUE SOURCE http3 true config (features.yaml) admin-api true env strict-tls true default metrics true defaultunset marks a flag or feature that keeps its zero value, because it has no default and no source sets it. See How to inspect value provenance for the rest of the report.
Know what users see when input is wrong
Section titled “Know what users see when input is wrong”Gated members and feature names are checked against every source. Each source reports problems in its own way:
| What the user does | Command line | Environment | Config file |
|---|---|---|---|
| Uses a gated flag or command while its feature is off | Usage error, exit 2 | Ignored | Config error, exit 1 |
Sets a gated flag in a file whose feature --feature-gates or the environment turned off |
— | — | Ignored, the run continues |
Names an unknown feature (htt3=true) |
Usage error, exit 2, with a “did you mean” hint | Config error, exit 1, with a hint (list variable only) | Config error, exit 1, with a hint |
Gives a bad value (http3=maybe) |
Usage error, exit 2 | Config error, exit 1, naming the variable | Config error, exit 1, naming the config key |
When a gated flag has its own variable, such as API_QUIC from EnvPrefix("API"), the environment skips it while the flag is inactive, so leftover variables from a parent shell or CI runner leave unrelated runs alone. Feature variables, whether the API_FEATURES list or per-feature variables such as API_FEATURE_METRICS, exist only to set features, so the program always validates them. They come from the environment, so their failures are ErrConfig with exit 1.
An unknown name or a bad value in API_FEATURES produces:
$ API_FEATURES=htt3=true feature-togglesError:feature-toggles: error: unknown feature "htt3" (from environment variable API_FEATURES) (did you mean "http3"?)Error$ API_FEATURES=http3=maybe feature-togglesError:feature-toggles: error: invalid value "maybe" for feature "http3" (from environment variable API_FEATURES): must be true or false (or 1 or 0)ErrorThe config-file errors name the file:
Error:feature-toggles: error: config file "features.yaml": unknown feature "htt3" in section "features" (did you mean "http3"?)ErrorError:feature-toggles: error: config file "features.yaml": flag '--quic' requires feature "http3"A file that sets --quic is still valid when the feature is off only because the command line or the environment turned it off. With http3: true and quic: true in features.yaml, --feature-gates http3=false runs without --quic:
$ feature-toggles -c features.yaml --feature-gates http3=falsefeatures: http3=false admin-api=false strict-tls=true metrics=trueA bad value in the file names the key it came from and exits 1:
Error:feature-toggles: error: invalid value "maybe" for feature "http3" (from config key "features.http3"): must be true or false (or 1 or 0)ErrorRead a feature’s value
Section titled “Read a feature’s value”Features.Get() returns the resolved struct:
func (c *CLI) Run(ctx context.Context, session *conga.Session) error { if c.Features.Get().Metrics { // start the metrics collector }
return nil}A feature can also stand alone. metrics gates no member and is read only in code.
Use a feature with levels
Section titled “Use a feature with levels”Declare an integer field and list its levels in enum. 0 means off, so list only the levels above it:
Syntax int `stage:"beta" enum:"1,2" help:"Config syntax version (0 = off)"`Users pick a level with --feature-gates syntax=2. The help screen lists the levels, and a value outside them gives a usage error:
syntax Config syntax version (0 = off) [beta] [levels: 1, 2]Error:feature-toggles: error: invalid value "3" for feature "syntax": must be one of: 0, 1, 2ErrorA gate such as feature:"syntax" holds at every level from 1 up. To vary behavior by level, read it in code with c.Features.Get().Syntax.
Give each feature its own environment variable
Section titled “Give each feature its own environment variable”The env tag on the container gives users one variable holding a list of pairs. To give each feature its own variable instead, replace env with envprefix:
| Container tag | What the user sets |
|---|---|
env:"API_FEATURES" |
API_FEATURES=http3=true,metrics=false |
envprefix:"API_FEATURE" |
API_FEATURE_HTTP3=true API_FEATURE_METRICS=false |
Each feature’s variable is the prefix plus its name in upper snake case. A field’s own env tag renames its variable, and env:"-" leaves the feature to the command line and config file:
type experiments struct { HTTP3 bool `env:"ENABLE_HTTP3" stage:"alpha" help:"Experimental HTTP/3 (QUIC) listener"` AdminAPI bool `stage:"alpha" help:"Experimental admin API"` StrictTLS bool `env:"-" stage:"beta" default:"true" help:"Require TLS and reject weak ciphers"` Metrics bool `stage:"beta" default:"true" help:"Expose the metrics endpoint"`}
type CLI struct { Features conga.Features[experiments] `flag:"feature-gates" envprefix:"API_FEATURE" config:"features"`}Users find the variables in the help screen, next to each feature:
Features: http3 Experimental HTTP/3 (QUIC) listener [alpha] [env: ENABLE_HTTP3] admin-api Experimental admin API [alpha] [env: API_FEATURE_ADMIN_API] strict-tls Require TLS and reject weak ciphers [beta] [default: true] metrics Expose the metrics endpoint [beta] [default: true] [env: API_FEATURE_METRICS]Switching changes which variables the program reads, so tell your users before you switch:
envprefixreplaces the list variable. A container uses one form at a time, so the program readsAPI_FEATURE_HTTP3in place ofAPI_FEATURES.- A field’s
envtag renames its variable. Withenv:"ENABLE_HTTP3", the program readsENABLE_HTTP3in place ofAPI_FEATURE_HTTP3. - Users set
env:"-"features through the container’s other sources, here--feature-gatesand thefeatures:config section, for example--feature-gates strict-tls=false. - Features take their variables from the container’s
envorenvprefixtag alone.EnvPrefix("API")gives--listenthe variableAPI_LISTENand leaves features as they are.
The command line still beats these variables, one feature at a time. ENABLE_HTTP3=false feature-toggles --feature-gates http3=true runs with http3 on.
The application checks at startup that each variable belongs to one feature. Here AdminAPI was also given env:"ENABLE_HTTP3":
Error:feature-toggles: error: struct CLI field Features: schema error: environment variable "ENABLE_HTTP3" is bound by both feature "http3" and feature "admin-api"ErrorA feature’s variable can’t also belong to a flag. With env:"API_LISTEN" on AdminAPI instead, the variable of --listen:
Error:feature-toggles: error: struct CLI field Features: schema error: environment variable "API_LISTEN" is bound by both feature "admin-api" and flag --listenErrorMark how mature each feature is
Section titled “Mark how mature each feature is”The stage tag labels a feature alpha, beta, ga, or deprecated, and the label appears in the help screen’s Features: list. Once you set stage on one feature you must set it on all of them.
Features staged ga or deprecated drop out of the help list but keep working, and users can still set them and see them in --why. About feature toggles explains why.
Where to go next
Section titled “Where to go next”- About feature toggles: why features are typed struct fields and why sources merge feature by feature.
- Struct tags: every container tag, feature-field tag, and expression form.
- About value precedence: how command line, environment, config, and defaults combine.
- Feature toggles example: the program used on this page.