fnox 1.21.0

A flexible secret management tool supporting multiple providers and encryption methods
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# Shell Integration

fnox can automatically load secrets when you `cd` into directories with a `fnox.toml` file.

## Enable Shell Integration

Add this to your shell profile:

::: code-group

```bash [Bash]
# Add to ~/.bashrc or ~/.bash_profile
eval "$(fnox activate bash)"
```

```zsh [Zsh]
# Add to ~/.zshrc
eval "$(fnox activate zsh)"
```

```fish [Fish]
# Add to ~/.config/fish/config.fish
fnox activate fish | source
```

```nu [Nushell]
# Requires Nushell 0.96+
# Add to the end of your Nushell configuration
# (find it by running `$nu.config-path` in Nushell):
mkdir ($nu.data-dir | path join "vendor/autoload")
fnox activate nu | save -f ($nu.data-dir | path join "vendor/autoload/fnox.nu")
```

```powershell [Powershell]
# Add this to your Powershell profile.
# To find your profile, see https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles
(&fnox activate pwsh) | Out-String | Invoke-Expression
```

:::

## How It Works

Once enabled, fnox hooks into your shell's `cd` command. When you enter a directory with `fnox.toml`:

```bash
~/projects $ cd my-app
fnox: +3 DATABASE_URL, API_KEY, JWT_SECRET
~/projects/my-app $
```

When you leave:

```bash
~/projects/my-app $ cd ..
fnox: -3 DATABASE_URL, API_KEY, JWT_SECRET
~/projects $
```

## Output Control

Control what gets printed with `FNOX_SHELL_OUTPUT`:

```bash
# Silent mode (no output)
export FNOX_SHELL_OUTPUT=none

# Normal mode (show count and keys) - default
export FNOX_SHELL_OUTPUT=normal

# Debug mode (verbose logging)
export FNOX_SHELL_OUTPUT=debug
```

## Using Profiles

Switch environments with `FNOX_PROFILE`:

```bash
# Use production secrets
export FNOX_PROFILE=production
cd my-app
# fnox: +3 DATABASE_URL, API_KEY, JWT_SECRET (from production profile)

# Switch to staging
export FNOX_PROFILE=staging
# fnox detects the change on the next prompt automatically
# fnox: -3 +3 DATABASE_URL, API_KEY, JWT_SECRET (from staging profile)
```

## Hierarchical Loading

fnox searches parent directories for `fnox.toml` files and merges them:

```
project/
├── fnox.toml              # Common secrets (age provider, shared keys)
└── services/
    ├── api/
    │   └── fnox.toml      # API-specific secrets
    └── worker/
        └── fnox.toml      # Worker-specific secrets
```

When you `cd services/api/`, fnox loads:

1. Secrets from `project/fnox.toml`
2. Secrets from `project/services/api/fnox.toml` (overrides parent)

## Manual Reload

fnox's shell hook runs on every prompt and automatically detects changes to config files and environment variables like `FNOX_PROFILE`. In most cases, no manual reload is needed.

To force a full reload, temporarily disable and re-enable:

```bash
# Disable
fnox deactivate

# Re-enable
eval "$(fnox activate bash)"
```

## Next Steps

- [Profiles](/guide/profiles) - Manage multiple environments
- [Hierarchical Config](/guide/hierarchical-config) - Organize secrets across directories
- [Real-World Example](/guide/real-world-example) - See a complete setup