vaultconfig 0.2.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/PKG-INFO +276 -16
  2. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/README.md +275 -15
  3. vaultconfig-0.2.1/docs/cli.rst +1015 -0
  4. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/quickstart.rst +87 -12
  5. vaultconfig-0.2.1/tests/test_cli.py +1082 -0
  6. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/_version.py +3 -3
  7. vaultconfig-0.2.1/vaultconfig/cli.py +2435 -0
  8. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/config.py +146 -14
  9. vaultconfig-0.2.1/vaultconfig/py.typed +0 -0
  10. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/PKG-INFO +276 -16
  11. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/SOURCES.txt +1 -1
  12. vaultconfig-0.2.0/docs/cli.rst +0 -518
  13. vaultconfig-0.2.0/examples/_update_examples.sh +0 -11
  14. vaultconfig-0.2.0/tests/test_cli.py +0 -342
  15. vaultconfig-0.2.0/vaultconfig/cli.py +0 -400
  16. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.coveragerc +0 -0
  17. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.github/pytest.ini +0 -0
  18. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.github/workflows/codecov.yml +0 -0
  19. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.github/workflows/pre-commit.yml +0 -0
  20. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.github/workflows/python-publish.yml +0 -0
  21. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.github/workflows/tests.yml +0 -0
  22. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.gitignore +0 -0
  23. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.pre-commit-config.yaml +0 -0
  24. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.prettierrc.yml +0 -0
  25. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.readthedocs.yaml +0 -0
  26. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/.ruff.toml +0 -0
  27. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/LICENSE +0 -0
  28. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/Makefile +0 -0
  29. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/api.rst +0 -0
  30. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/conf.py +0 -0
  31. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/examples.rst +0 -0
  32. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/index.rst +0 -0
  33. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/installation.rst +0 -0
  34. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/make.bat +0 -0
  35. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/make.py +0 -0
  36. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/requirements.txt +0 -0
  37. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/docs/security.rst +0 -0
  38. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/README.md +0 -0
  39. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/custom_cipher_key_example.py +0 -0
  40. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/README.md +0 -0
  41. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/environments.ini +0 -0
  42. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/example.py +0 -0
  43. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/example_default_section.py +0 -0
  44. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/hosts_config.ini +0 -0
  45. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/invalid_database.ini +0 -0
  46. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/obscured_database.ini +0 -0
  47. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/ini_config/valid_database.ini +0 -0
  48. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/README.md +0 -0
  49. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/app_config.toml +0 -0
  50. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/environments.toml +0 -0
  51. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/example.py +0 -0
  52. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/example_advanced.py +0 -0
  53. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/invalid_database.toml +0 -0
  54. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/nested_config.toml +0 -0
  55. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/obscured_database.toml +0 -0
  56. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/types_demo.toml +0 -0
  57. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/toml_config/valid_database.toml +0 -0
  58. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/README.md +0 -0
  59. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/app_config.yaml +0 -0
  60. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/environments.yaml +0 -0
  61. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/example.py +0 -0
  62. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/example_advanced.py +0 -0
  63. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/invalid_database.yaml +0 -0
  64. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/nested_config.yaml +0 -0
  65. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/obscured_database.yaml +0 -0
  66. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/types_demo.yaml +0 -0
  67. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/examples/yaml_config/valid_database.yaml +0 -0
  68. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/pyproject.toml +0 -0
  69. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/requirements-test.txt +0 -0
  70. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/setup.cfg +0 -0
  71. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/setup.py +0 -0
  72. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/__init__.py +0 -0
  73. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/conftest.py +0 -0
  74. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_config.py +0 -0
  75. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_crypt.py +0 -0
  76. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_formats.py +0 -0
  77. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_obscure.py +0 -0
  78. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_obscure_custom_keys.py +0 -0
  79. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/tests/test_schema.py +0 -0
  80. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/__init__.py +0 -0
  81. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/crypt.py +0 -0
  82. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/exceptions.py +0 -0
  83. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/formats/__init__.py +0 -0
  84. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/formats/base.py +0 -0
  85. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/formats/ini_format.py +0 -0
  86. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/formats/toml_format.py +0 -0
  87. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/formats/yaml_format.py +0 -0
  88. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/obscure.py +0 -0
  89. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig/schema.py +0 -0
  90. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/dependency_links.txt +0 -0
  91. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/entry_points.txt +0 -0
  92. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/requires.txt +0 -0
  93. {vaultconfig-0.2.0 → vaultconfig-0.2.1}/vaultconfig.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: vaultconfig
3
- Version: 0.2.0
3
+ Version: 0.2.1
4
4
  Summary: Secure configuration management library with encryption support for Python
5
5
  Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
6
6
  License: MIT License
@@ -85,29 +85,288 @@ pip install vaultconfig[dev]
85
85
 
86
86
  ### Command Line Usage
87
87
 
88
+ The CLI provides complete configuration management without requiring Python programming.
89
+
90
+ #### Default Config Directory
91
+
92
+ VaultConfig uses a platform-specific default config directory so you don't need to
93
+ specify it every time:
94
+
95
+ - **Linux/macOS**: `~/.config/vaultconfig`
96
+ - **Windows**: `%APPDATA%\vaultconfig`
97
+
98
+ You can override this with:
99
+
100
+ - `--config-dir` (or `-d`) option on any command
101
+ - `VAULTCONFIG_DIR` environment variable
102
+
88
103
  ```bash
89
- # Initialize a new config directory
90
- vaultconfig init ./myapp-config --format toml
104
+ # Use default directory
105
+ vaultconfig init
106
+ vaultconfig set database host=localhost --create
107
+
108
+ # Use custom directory
109
+ vaultconfig init -d ./myapp-config
110
+ vaultconfig set -d ./myapp-config database host=localhost --create
111
+
112
+ # Or set environment variable
113
+ export VAULTCONFIG_DIR=./myapp-config
114
+ vaultconfig list
115
+ ```
116
+
117
+ #### Initialization
118
+
119
+ ```bash
120
+ # Initialize default config directory
121
+ vaultconfig init --format toml
91
122
 
92
123
  # Initialize with encryption
93
- vaultconfig init ./myapp-config --format toml --encrypt
124
+ vaultconfig init --encrypt
94
125
 
95
- # List all configurations
96
- vaultconfig list ./myapp-config
126
+ # Initialize custom directory
127
+ vaultconfig init -d ./myapp-config --format toml
128
+ ```
129
+
130
+ #### Creating & Updating Configs
131
+
132
+ ```bash
133
+ # Create a configuration interactively (uses default directory)
134
+ vaultconfig create database
135
+ # Prompts for key-value pairs
136
+
137
+ # Create from a file
138
+ vaultconfig create database --from-file config.json
139
+
140
+ # Set individual values
141
+ vaultconfig set database host=localhost port=5432
97
142
 
98
- # Show a configuration
99
- vaultconfig show ./myapp-config myconfig
143
+ # Set with automatic creation
144
+ vaultconfig set newconfig key=value --create
145
+
146
+ # Set obscured password
147
+ vaultconfig set database password=secret --obscure
148
+
149
+ # Remove keys
150
+ vaultconfig unset database old_key
151
+
152
+ # All commands work with custom directories too
153
+ vaultconfig set -d ./myapp-config database host=localhost
154
+ ```
155
+
156
+ #### Reading Configs
157
+
158
+ ```bash
159
+ # List all configurations (table format, uses default directory)
160
+ vaultconfig list
161
+
162
+ # List as JSON
163
+ vaultconfig list --output json
164
+
165
+ # List as plain names
166
+ vaultconfig list --output plain
167
+
168
+ # Show a configuration (pretty format)
169
+ vaultconfig show database
100
170
 
101
171
  # Show with revealed passwords
102
- vaultconfig show ./myapp-config myconfig --reveal
172
+ vaultconfig show database --reveal
173
+
174
+ # Show as JSON
175
+ vaultconfig show database --output json
176
+
177
+ # Get a specific value
178
+ vaultconfig get database host
179
+
180
+ # Get with reveal (for obscured values)
181
+ vaultconfig get database password --reveal
182
+ ```
183
+
184
+ #### Import/Export
185
+
186
+ ```bash
187
+ # Export to JSON
188
+ vaultconfig export database -e json -o database.json
189
+
190
+ # Export with revealed passwords
191
+ vaultconfig export database -e json --reveal
192
+
193
+ # Export to YAML
194
+ vaultconfig export database -e yaml
195
+
196
+ # Export to stdout
197
+ vaultconfig export database -e json
198
+
199
+ # Import from file
200
+ vaultconfig import database --from-file database.json
201
+
202
+ # Import with overwrite
203
+ vaultconfig import database --from-file config.yaml --overwrite
204
+ ```
205
+
206
+ #### Environment Variables
207
+
208
+ ```bash
209
+ # Preview what will be exported (dry-run mode)
210
+ vaultconfig export-env database --dry-run
211
+
212
+ # Export as environment variables (auto-detects shell)
213
+ vaultconfig export-env database --prefix DB_
214
+
215
+ # Use in bash/zsh
216
+ eval $(vaultconfig export-env database --prefix DB_ --reveal)
217
+ echo $DB_HOST # localhost
218
+
219
+ # Use in fish
220
+ vaultconfig export-env database --shell fish | source
221
+
222
+ # Use in nushell
223
+ vaultconfig export-env database --shell nushell | save -f env.nu
224
+ source env.nu
225
+
226
+ # Use in PowerShell
227
+ vaultconfig export-env database --shell powershell | Invoke-Expression
228
+
229
+ # Specify shell explicitly
230
+ vaultconfig export-env database --shell bash
231
+ vaultconfig export-env database --shell zsh
232
+ vaultconfig export-env database --shell fish
233
+ vaultconfig export-env database --shell nushell
234
+ vaultconfig export-env database --shell powershell
235
+
236
+ # Preview with prefix before exporting
237
+ vaultconfig export-env database --prefix DB_ --dry-run
238
+ ```
239
+
240
+ **Supported Shells:**
241
+
242
+ - **bash** - Bash shell (default)
243
+ - **zsh** - Zsh shell
244
+ - **fish** - Fish shell
245
+ - **nushell** - Nushell
246
+ - **powershell** - PowerShell
247
+
248
+ The shell type is auto-detected from your environment if not specified.
249
+
250
+ **Dry-Run Mode:** Use `--dry-run` to preview the environment variables in a readable
251
+ table format. The output includes:
252
+
253
+ - A formatted table showing all variables and their values
254
+ - Shell-specific copyable commands that you can paste directly into your terminal
255
+ - Helpful tips and notes
256
+
257
+ This is useful for verifying what will be exported before actually using it, and
258
+ provides ready-to-copy commands for manual setup.
259
+
260
+ #### Run Command with Config
261
+
262
+ The `run` command loads a configuration and executes a command with config values as
263
+ environment variables. This is similar to `dotenv run` but works with VaultConfig
264
+ configurations.
265
+
266
+ ```bash
267
+ # Run a command with config values as environment variables
268
+ vaultconfig run database python app.py
269
+
270
+ # Use custom prefix for env vars (default is config name + underscore)
271
+ vaultconfig run database --prefix DB_ python app.py
272
+
273
+ # Reveal obscured passwords
274
+ vaultconfig run database --reveal python app.py
275
+
276
+ # Keep lowercase keys (default converts to uppercase)
277
+ vaultconfig run database --no-uppercase python app.py
278
+
279
+ # Don't override existing environment variables
280
+ vaultconfig run database --no-override python app.py
281
+
282
+ # Combine options
283
+ vaultconfig run database --prefix MYAPP_ --reveal -- python app.py --arg value
284
+ ```
285
+
286
+ **How it works:**
287
+
288
+ - Loads the specified configuration
289
+ - Flattens nested configs (e.g., `database.host` → `DATABASE_HOST`)
290
+ - Converts keys to uppercase by default (disable with `--no-uppercase`)
291
+ - Adds optional prefix to all variable names
292
+ - Executes the command with the config as environment variables
293
+ - Exits with the same exit code as the command
294
+
295
+ **Examples:**
296
+
297
+ ```bash
298
+ # Run a Python script with database config
299
+ vaultconfig run database python manage.py migrate
300
+
301
+ # Run tests with test config
302
+ vaultconfig run test-env pytest tests/
303
+
304
+ # Run Docker with config
305
+ vaultconfig run docker-config docker-compose up
306
+
307
+ # Use with custom directory
308
+ vaultconfig run -d ./myapp-config prod-db python deploy.py
309
+ ```
310
+
311
+ #### Copy & Rename
312
+
313
+ ```bash
314
+ # Copy a configuration
315
+ vaultconfig copy database database-backup
316
+
317
+ # Rename a configuration
318
+ vaultconfig rename database database-prod
319
+ ```
320
+
321
+ #### Schema Validation
322
+
323
+ ```bash
324
+ # Create a schema file (schema.yaml)
325
+ cat > schema.yaml <<EOF
326
+ fields:
327
+ host:
328
+ type: str
329
+ default: localhost
330
+ port:
331
+ type: int
332
+ default: 5432
333
+ password:
334
+ type: str
335
+ sensitive: true
336
+ required: true
337
+ EOF
338
+
339
+ # Validate configuration
340
+ vaultconfig validate database --schema schema.yaml
341
+ ```
342
+
343
+ #### Encryption Management
344
+
345
+ ```bash
346
+ # Set/change password (uses default directory or specify with -d)
347
+ vaultconfig encrypt set
348
+ vaultconfig encrypt set -d ./myapp-config
349
+
350
+ # Remove encryption
351
+ vaultconfig encrypt remove
352
+ vaultconfig encrypt remove -d ./myapp-config
353
+
354
+ # Check encryption status
355
+ vaultconfig encrypt check
356
+ vaultconfig encrypt check -d ./myapp-config
357
+ ```
358
+
359
+ #### Deletion
360
+
361
+ ```bash
362
+ # Delete a configuration (prompts for confirmation)
363
+ vaultconfig delete myconfig
103
364
 
104
- # Delete a configuration
105
- vaultconfig delete ./myapp-config myconfig
365
+ # Delete without confirmation
366
+ vaultconfig delete myconfig --yes
106
367
 
107
- # Manage encryption
108
- vaultconfig encrypt set ./myapp-config # Set/change password
109
- vaultconfig encrypt remove ./myapp-config # Remove encryption
110
- vaultconfig encrypt check ./myapp-config # Check encryption status
368
+ # Delete from custom directory
369
+ vaultconfig delete -d ./myapp-config myconfig
111
370
  ```
112
371
 
113
372
  ### Python API Usage
@@ -298,7 +557,7 @@ vaultconfig list ./myapp-config
298
557
 
299
558
  # Or point to key file
300
559
  export VAULTCONFIG_CIPHER_KEY_FILE=~/.myapp_cipher_key
301
- vaultconfig show ./myapp-config database --reveal
560
+ vaultconfig show database --reveal
302
561
  ```
303
562
 
304
563
  #### Key Management Best Practices
@@ -386,6 +645,7 @@ nested:
386
645
 
387
646
  ## Environment Variables
388
647
 
648
+ - `VAULTCONFIG_DIR`: Default config directory (overrides platform default)
389
649
  - `VAULTCONFIG_PASSWORD`: Password for encrypted configs
390
650
  - `VAULTCONFIG_PASSWORD_COMMAND`: Command to retrieve password (e.g., from password
391
651
  manager)
@@ -40,29 +40,288 @@ pip install vaultconfig[dev]
40
40
 
41
41
  ### Command Line Usage
42
42
 
43
+ The CLI provides complete configuration management without requiring Python programming.
44
+
45
+ #### Default Config Directory
46
+
47
+ VaultConfig uses a platform-specific default config directory so you don't need to
48
+ specify it every time:
49
+
50
+ - **Linux/macOS**: `~/.config/vaultconfig`
51
+ - **Windows**: `%APPDATA%\vaultconfig`
52
+
53
+ You can override this with:
54
+
55
+ - `--config-dir` (or `-d`) option on any command
56
+ - `VAULTCONFIG_DIR` environment variable
57
+
43
58
  ```bash
44
- # Initialize a new config directory
45
- vaultconfig init ./myapp-config --format toml
59
+ # Use default directory
60
+ vaultconfig init
61
+ vaultconfig set database host=localhost --create
62
+
63
+ # Use custom directory
64
+ vaultconfig init -d ./myapp-config
65
+ vaultconfig set -d ./myapp-config database host=localhost --create
66
+
67
+ # Or set environment variable
68
+ export VAULTCONFIG_DIR=./myapp-config
69
+ vaultconfig list
70
+ ```
71
+
72
+ #### Initialization
73
+
74
+ ```bash
75
+ # Initialize default config directory
76
+ vaultconfig init --format toml
46
77
 
47
78
  # Initialize with encryption
48
- vaultconfig init ./myapp-config --format toml --encrypt
79
+ vaultconfig init --encrypt
49
80
 
50
- # List all configurations
51
- vaultconfig list ./myapp-config
81
+ # Initialize custom directory
82
+ vaultconfig init -d ./myapp-config --format toml
83
+ ```
84
+
85
+ #### Creating & Updating Configs
86
+
87
+ ```bash
88
+ # Create a configuration interactively (uses default directory)
89
+ vaultconfig create database
90
+ # Prompts for key-value pairs
91
+
92
+ # Create from a file
93
+ vaultconfig create database --from-file config.json
94
+
95
+ # Set individual values
96
+ vaultconfig set database host=localhost port=5432
52
97
 
53
- # Show a configuration
54
- vaultconfig show ./myapp-config myconfig
98
+ # Set with automatic creation
99
+ vaultconfig set newconfig key=value --create
100
+
101
+ # Set obscured password
102
+ vaultconfig set database password=secret --obscure
103
+
104
+ # Remove keys
105
+ vaultconfig unset database old_key
106
+
107
+ # All commands work with custom directories too
108
+ vaultconfig set -d ./myapp-config database host=localhost
109
+ ```
110
+
111
+ #### Reading Configs
112
+
113
+ ```bash
114
+ # List all configurations (table format, uses default directory)
115
+ vaultconfig list
116
+
117
+ # List as JSON
118
+ vaultconfig list --output json
119
+
120
+ # List as plain names
121
+ vaultconfig list --output plain
122
+
123
+ # Show a configuration (pretty format)
124
+ vaultconfig show database
55
125
 
56
126
  # Show with revealed passwords
57
- vaultconfig show ./myapp-config myconfig --reveal
127
+ vaultconfig show database --reveal
128
+
129
+ # Show as JSON
130
+ vaultconfig show database --output json
131
+
132
+ # Get a specific value
133
+ vaultconfig get database host
134
+
135
+ # Get with reveal (for obscured values)
136
+ vaultconfig get database password --reveal
137
+ ```
138
+
139
+ #### Import/Export
140
+
141
+ ```bash
142
+ # Export to JSON
143
+ vaultconfig export database -e json -o database.json
144
+
145
+ # Export with revealed passwords
146
+ vaultconfig export database -e json --reveal
147
+
148
+ # Export to YAML
149
+ vaultconfig export database -e yaml
150
+
151
+ # Export to stdout
152
+ vaultconfig export database -e json
153
+
154
+ # Import from file
155
+ vaultconfig import database --from-file database.json
156
+
157
+ # Import with overwrite
158
+ vaultconfig import database --from-file config.yaml --overwrite
159
+ ```
160
+
161
+ #### Environment Variables
162
+
163
+ ```bash
164
+ # Preview what will be exported (dry-run mode)
165
+ vaultconfig export-env database --dry-run
166
+
167
+ # Export as environment variables (auto-detects shell)
168
+ vaultconfig export-env database --prefix DB_
169
+
170
+ # Use in bash/zsh
171
+ eval $(vaultconfig export-env database --prefix DB_ --reveal)
172
+ echo $DB_HOST # localhost
173
+
174
+ # Use in fish
175
+ vaultconfig export-env database --shell fish | source
176
+
177
+ # Use in nushell
178
+ vaultconfig export-env database --shell nushell | save -f env.nu
179
+ source env.nu
180
+
181
+ # Use in PowerShell
182
+ vaultconfig export-env database --shell powershell | Invoke-Expression
183
+
184
+ # Specify shell explicitly
185
+ vaultconfig export-env database --shell bash
186
+ vaultconfig export-env database --shell zsh
187
+ vaultconfig export-env database --shell fish
188
+ vaultconfig export-env database --shell nushell
189
+ vaultconfig export-env database --shell powershell
190
+
191
+ # Preview with prefix before exporting
192
+ vaultconfig export-env database --prefix DB_ --dry-run
193
+ ```
194
+
195
+ **Supported Shells:**
196
+
197
+ - **bash** - Bash shell (default)
198
+ - **zsh** - Zsh shell
199
+ - **fish** - Fish shell
200
+ - **nushell** - Nushell
201
+ - **powershell** - PowerShell
202
+
203
+ The shell type is auto-detected from your environment if not specified.
204
+
205
+ **Dry-Run Mode:** Use `--dry-run` to preview the environment variables in a readable
206
+ table format. The output includes:
207
+
208
+ - A formatted table showing all variables and their values
209
+ - Shell-specific copyable commands that you can paste directly into your terminal
210
+ - Helpful tips and notes
211
+
212
+ This is useful for verifying what will be exported before actually using it, and
213
+ provides ready-to-copy commands for manual setup.
214
+
215
+ #### Run Command with Config
216
+
217
+ The `run` command loads a configuration and executes a command with config values as
218
+ environment variables. This is similar to `dotenv run` but works with VaultConfig
219
+ configurations.
220
+
221
+ ```bash
222
+ # Run a command with config values as environment variables
223
+ vaultconfig run database python app.py
224
+
225
+ # Use custom prefix for env vars (default is config name + underscore)
226
+ vaultconfig run database --prefix DB_ python app.py
227
+
228
+ # Reveal obscured passwords
229
+ vaultconfig run database --reveal python app.py
230
+
231
+ # Keep lowercase keys (default converts to uppercase)
232
+ vaultconfig run database --no-uppercase python app.py
233
+
234
+ # Don't override existing environment variables
235
+ vaultconfig run database --no-override python app.py
236
+
237
+ # Combine options
238
+ vaultconfig run database --prefix MYAPP_ --reveal -- python app.py --arg value
239
+ ```
240
+
241
+ **How it works:**
242
+
243
+ - Loads the specified configuration
244
+ - Flattens nested configs (e.g., `database.host` → `DATABASE_HOST`)
245
+ - Converts keys to uppercase by default (disable with `--no-uppercase`)
246
+ - Adds optional prefix to all variable names
247
+ - Executes the command with the config as environment variables
248
+ - Exits with the same exit code as the command
249
+
250
+ **Examples:**
251
+
252
+ ```bash
253
+ # Run a Python script with database config
254
+ vaultconfig run database python manage.py migrate
255
+
256
+ # Run tests with test config
257
+ vaultconfig run test-env pytest tests/
258
+
259
+ # Run Docker with config
260
+ vaultconfig run docker-config docker-compose up
261
+
262
+ # Use with custom directory
263
+ vaultconfig run -d ./myapp-config prod-db python deploy.py
264
+ ```
265
+
266
+ #### Copy & Rename
267
+
268
+ ```bash
269
+ # Copy a configuration
270
+ vaultconfig copy database database-backup
271
+
272
+ # Rename a configuration
273
+ vaultconfig rename database database-prod
274
+ ```
275
+
276
+ #### Schema Validation
277
+
278
+ ```bash
279
+ # Create a schema file (schema.yaml)
280
+ cat > schema.yaml <<EOF
281
+ fields:
282
+ host:
283
+ type: str
284
+ default: localhost
285
+ port:
286
+ type: int
287
+ default: 5432
288
+ password:
289
+ type: str
290
+ sensitive: true
291
+ required: true
292
+ EOF
293
+
294
+ # Validate configuration
295
+ vaultconfig validate database --schema schema.yaml
296
+ ```
297
+
298
+ #### Encryption Management
299
+
300
+ ```bash
301
+ # Set/change password (uses default directory or specify with -d)
302
+ vaultconfig encrypt set
303
+ vaultconfig encrypt set -d ./myapp-config
304
+
305
+ # Remove encryption
306
+ vaultconfig encrypt remove
307
+ vaultconfig encrypt remove -d ./myapp-config
308
+
309
+ # Check encryption status
310
+ vaultconfig encrypt check
311
+ vaultconfig encrypt check -d ./myapp-config
312
+ ```
313
+
314
+ #### Deletion
315
+
316
+ ```bash
317
+ # Delete a configuration (prompts for confirmation)
318
+ vaultconfig delete myconfig
58
319
 
59
- # Delete a configuration
60
- vaultconfig delete ./myapp-config myconfig
320
+ # Delete without confirmation
321
+ vaultconfig delete myconfig --yes
61
322
 
62
- # Manage encryption
63
- vaultconfig encrypt set ./myapp-config # Set/change password
64
- vaultconfig encrypt remove ./myapp-config # Remove encryption
65
- vaultconfig encrypt check ./myapp-config # Check encryption status
323
+ # Delete from custom directory
324
+ vaultconfig delete -d ./myapp-config myconfig
66
325
  ```
67
326
 
68
327
  ### Python API Usage
@@ -253,7 +512,7 @@ vaultconfig list ./myapp-config
253
512
 
254
513
  # Or point to key file
255
514
  export VAULTCONFIG_CIPHER_KEY_FILE=~/.myapp_cipher_key
256
- vaultconfig show ./myapp-config database --reveal
515
+ vaultconfig show database --reveal
257
516
  ```
258
517
 
259
518
  #### Key Management Best Practices
@@ -341,6 +600,7 @@ nested:
341
600
 
342
601
  ## Environment Variables
343
602
 
603
+ - `VAULTCONFIG_DIR`: Default config directory (overrides platform default)
344
604
  - `VAULTCONFIG_PASSWORD`: Password for encrypted configs
345
605
  - `VAULTCONFIG_PASSWORD_COMMAND`: Command to retrieve password (e.g., from password
346
606
  manager)