Configuration Files
aux4 supports loading variables from YAML and JSON configuration files. This is useful for managing complex configurations and keeping sensitive data separate from your command definitions.
Requirements
To use configuration files, you need to install the aux4/config package:
1aux4 aux4 pkger install aux4/configConfig File Format
Configuration files use a config wrapper key. Both YAML and JSON formats are supported:
YAML
1config:
2 environment: production
3 region: us-east-1
4 instances: 3JSON
1{
2 "config": {
3 "environment": "production",
4 "region": "us-east-1",
5 "instances": 3
6 }
7}Auto-Detection
When no --file is specified, aux4 searches the current directory for config files in this order:
- config.yaml
- config.yml
- config.json
Using Config Files in Commands
To load variables from a configuration file, use the --configFile and --config parameters in your command:
1> aux4 deploy --configFile deploy-config.yaml --configThe config values become available as aux4 variables inside the execute array.
Example
Create a configuration file:
1# deploy-config.yaml
2config:
3 environment: production
4 region: us-east-1
5 instances: 3Create your .aux4 command:
1{
2 "profiles": [
3 {
4 "name": "main",
5 "commands": [
6 {
7 "name": "deploy",
8 "execute": [
9 "log:Deploying to ${environment} in ${region} with ${instances} instances"
10 ],
11 "help": {
12 "text": "deploy the application",
13 "variables": [
14 {
15 "name": "environment",
16 "text": "deployment environment"
17 },
18 {
19 "name": "region",
20 "text": "AWS region"
21 },
22 {
23 "name": "instances",
24 "text": "number of instances"
25 }
26 ]
27 }
28 }
29 ]
30 }
31 ]
32}Run with config file:
1> aux4 deploy --configFile deploy-config.yaml --config1Deploying to production in us-east-1 with 3 instancesNamed Configurations
You can organize multiple configurations in a single file and select one by name:
1config:
2 dev:
3 host: localhost
4 port: 3000
5 prod:
6 host: api.example.com
7 port: 4431> aux4 connect --configFile config.yaml --config devThis loads only the values under dev, making ${host} and ${port} available.
Nested Configuration
Configuration files support nested objects. Access nested values using dot notation:
1config:
2 database:
3 host: localhost
4 port: 5432
5 name: myapp
6 cache:
7 enabled: true
8 ttl: 36001...
2 {
3 "execute": [
4 "log:Database: ${database.host}:${database.port}/${database.name}",
5 "log:Cache enabled: ${cache.enabled}, TTL: ${cache.ttl}"
6 ],
7 ...
8 }
9...Config CLI Commands
The aux4/config package also provides standalone CLI commands for reading, writing, and merging configuration files.
config get
Retrieve a value from a configuration file:
1> aux4 config get --file config.yaml dev/host1localhostScalar values are returned as raw text. Objects and arrays are returned as JSON:
1> aux4 config get --file config.yaml dev1{
2 "host": "localhost",
3 "port": 3000
4}Use forward slash / notation for nested paths:
1> aux4 config get --file config.yaml dev/database/port15432config set
Set a value in a configuration file:
1> aux4 config set --file config.yaml --name dev/host --value api.example.comIf the path doesn't exist, intermediate properties are created automatically. The file format is preserved — YAML files stay YAML, JSON files stay JSON.
config merge
Merge configuration from stdin into a file. This performs a deep merge — nested objects are merged recursively rather than overwritten:
1> aux4 config get --file dev.yaml | aux4 config merge --file prod.yaml --save trueWithout --save, the merged result is printed to stdout as JSON:
1> echo '{"host": "new-host", "port": 8080}' | aux4 config merge --file config.yaml --name devMerge into a specific path with --name:
1> cat db-config.json | aux4 config merge --file config.yaml --name prod/database --save trueOrder Preservation
aux4 preserves the order of fields in configuration objects during read, write, and merge operations. Fields are returned in the same order they appear in the source file.