settings.toml

# Fnox Settings Registry
#
# This file defines all configurable settings for fnox, including:
# - Type information
# - Default values
# - Configuration sources (CLI flags, environment variables, config files)
# - Documentation
#
# The build script (build/generate_settings.rs) reads this file and generates:
# - src/generated/settings.rs - Settings struct with type-safe fields
# - src/generated/settings_merge.rs - Merge logic and types
# - src/generated/settings_meta.rs - Metadata for introspection

[age_key_file]
type = "option<path>"
default = "None"
sources.cli = ["--age-key-file"]
sources.env = ["FNOX_AGE_KEY_FILE"]
docs = """
Path to a file containing the age encryption key.

This can be set via:
- CLI flag: --age-key-file <path>
- Environment variable: FNOX_AGE_KEY_FILE

Priority (highest to lowest): CLI > Environment > Default
"""
examples = [
  "fnox get MY_SECRET --age-key-file ~/.age/key.txt",
  "FNOX_AGE_KEY_FILE=~/.age/key.txt fnox get MY_SECRET",
]
since = "0.1.0"

[profile]
type = "string"
default = "\"default\""
sources.cli = ["--profile", "-p"]
sources.env = ["FNOX_PROFILE"]
docs = """
Configuration profile to use for secrets retrieval.

Profiles allow you to maintain multiple configurations (e.g., dev, staging, prod)
in a single fnox.toml file.

Priority (highest to lowest): CLI > Environment > Default
"""
examples = [
  "fnox get MY_SECRET --profile production",
  "FNOX_PROFILE=staging fnox get MY_SECRET",
]
since = "0.1.0"

[no_defaults]
type = "bool"
default = "false"
sources.cli = ["--no-defaults"]
sources.env = ["FNOX_NO_DEFAULTS"]
docs = """
When a non-default profile is selected, do not merge top-level [secrets] into
the profile. Only [profiles.<name>.secrets] will be used.

Priority (highest to lowest): CLI > Environment > Default
"""
examples = [
  "fnox exec --profile dev --no-defaults -- ./my-app",
  "FNOX_NO_DEFAULTS=true fnox exec --profile dev -- ./my-app",
]
since = "1.12.0"

[shell_integration_output]
type = "string"
default = "\"normal\""
sources.env = ["FNOX_SHELL_OUTPUT"]
docs = """
Control output level for shell integration.

Available modes:
- "none" - No output from shell integration
- "normal" - Show summary when secrets are loaded/unloaded (default)
- "debug" - Show detailed information including early-exit reasons

When set to "normal", fnox will output a summary to stderr showing which
secrets were loaded or unloaded, with truncated values (first 8 characters).

When set to "debug", fnox will additionally show:
- When hook-env runs
- Whether it exits early (optimization)
- Why it exits early (no changes detected)
- Config file paths being loaded

This is useful for understanding what the shell integration is doing and
troubleshooting issues.

Priority: Environment > Default
"""
examples = [
  "FNOX_SHELL_OUTPUT=none fnox activate bash",
  "FNOX_SHELL_OUTPUT=debug fnox activate zsh",
]
since = "0.1.0"

[if_missing]
type = "option<string>"
default = "None"
sources.cli = ["--if-missing"]
sources.env = ["FNOX_IF_MISSING"]
docs = """
Runtime override for if_missing behavior when a secret cannot be resolved.

Available modes:
- "error" - Fail the command if a secret cannot be resolved
- "warn" - Print a warning and continue
- "ignore" - Silently skip missing secrets

This overrides all config file settings. Use FNOX_IF_MISSING_DEFAULT to set the base default.

Priority (highest to lowest): CLI flag > Environment > Secret level > Top-level config > FNOX_IF_MISSING_DEFAULT > Default (warn)
"""
examples = [
  "fnox exec --if-missing error -- ./my-app",
  "FNOX_IF_MISSING=ignore fnox exec -- ./my-app",
]
since = "1.1.0"

[http_timeout]
type = "string"
default = "\"30s\""
sources.env = ["FNOX_HTTP_TIMEOUT"]
docs = """
HTTP request timeout in seconds for lease backend API calls (Vault, GCP IAM, etc.).

Prevents fnox exec from hanging indefinitely on slow or unreachable servers.
Set to "0" to disable the timeout (not recommended).

Priority: Environment > Default
"""
examples = [
  "FNOX_HTTP_TIMEOUT=60s fnox exec -- ./my-app",
  "FNOX_HTTP_TIMEOUT=10s fnox lease create my-lease --duration 1h",
]
since = "1.16.0"

[if_missing_default]
type = "option<string>"
default = "None"
sources.env = ["FNOX_IF_MISSING_DEFAULT"]
docs = """
Base default behavior when a secret cannot be resolved and not specified in config.

Available modes:
- "error" - Fail the command if a secret cannot be resolved
- "warn" - Print a warning and continue (default)
- "ignore" - Silently skip missing secrets

This sets the fallback behavior when nothing is configured in fnox.toml.
Config file settings (top-level or secret-level) override this.

Priority (highest to lowest): CLI flag > FNOX_IF_MISSING > Secret level > Top-level config > FNOX_IF_MISSING_DEFAULT > Default (warn)
"""
examples = [
  "export FNOX_IF_MISSING_DEFAULT=error  # Strict by default",
  "export FNOX_IF_MISSING_DEFAULT=ignore  # Lenient by default",
]
since = "1.1.0"