# 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](https://hub.aux4.io/r/public/packages/aux4/config) package:

```bash
aux4 aux4 pkger install aux4/config
```

## Config File Format

Configuration files use a `config` wrapper key. Both YAML and JSON formats are supported:

### YAML

```yaml
config:
  environment: production
  region: us-east-1
  instances: 3
```

### JSON

```json
{
  "config": {
    "environment": "production",
    "region": "us-east-1",
    "instances": 3
  }
}
```

### Auto-Detection

When no `--file` is specified, aux4 searches the current directory for config files in this order:
1. `config.yaml`
2. `config.yml`
3. `config.json`

## Using Config Files in Commands

To load variables from a configuration file, use the `--configFile` and `--config` parameters in your command:

```bash
> aux4 deploy --configFile deploy-config.yaml --config
```

The config values become available as aux4 variables inside the execute array.

### Example

Create a configuration file:

```yaml
# deploy-config.yaml
config:
  environment: production
  region: us-east-1
  instances: 3
```

Create your `.aux4` command:

```json
{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "deploy",
          "execute": [
            "log:Deploying to ${environment} in ${region} with ${instances} instances"
          ],
          "help": {
            "text": "deploy the application",
            "variables": [
              {
                "name": "environment",
                "text": "deployment environment"
              },
              {
                "name": "region",
                "text": "AWS region"
              },
              {
                "name": "instances",
                "text": "number of instances"
              }
            ]
          }
        }
      ]
    }
  ]
}
```

Run with config file:

```bash
> aux4 deploy --configFile deploy-config.yaml --config
```

```text
Deploying to production in us-east-1 with 3 instances
```

### Named Configurations

You can organize multiple configurations in a single file and select one by name:

```yaml
config:
  dev:
    host: localhost
    port: 3000
  prod:
    host: api.example.com
    port: 443
```

```bash
> aux4 connect --configFile config.yaml --config dev
```

This loads only the values under `dev`, making `${host}` and `${port}` available.

## Nested Configuration

Configuration files support nested objects. Access nested values using dot notation:

```yaml
config:
  database:
    host: localhost
    port: 5432
    name: myapp
  cache:
    enabled: true
    ttl: 3600
```

```json
...
  {
    "execute": [
      "log:Database: ${database.host}:${database.port}/${database.name}",
      "log:Cache enabled: ${cache.enabled}, TTL: ${cache.ttl}"
    ],
    ...
  }
...
```

## 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:

```bash
> aux4 config get --file config.yaml dev/host
```

```text
localhost
```

Scalar values are returned as raw text. Objects and arrays are returned as JSON:

```bash
> aux4 config get --file config.yaml dev
```

```json
{
  "host": "localhost",
  "port": 3000
}
```

Use forward slash `/` notation for nested paths:

```bash
> aux4 config get --file config.yaml dev/database/port
```

```text
5432
```

### config set

Set a value in a configuration file:

```bash
> aux4 config set --file config.yaml --name dev/host --value api.example.com
```

If 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:

```bash
> aux4 config get --file dev.yaml | aux4 config merge --file prod.yaml --save true
```

Without `--save`, the merged result is printed to stdout as JSON:

```bash
> echo '{"host": "new-host", "port": 8080}' | aux4 config merge --file config.yaml --name dev
```

Merge into a specific path with `--name`:

```bash
> cat db-config.json | aux4 config merge --file config.yaml --name prod/database --save true
```

## Order 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.

---

## See Also

- [Variables](/variables)
- [Executors](/executors)
- [Functions](/functions)
- [Commands](/commands)
- [Testing](/testing)
- [Package Manager](/package-manager)
- [Packaging](/packaging)
- [Docker](/docker)