docs/development/tools/ffx/commands/config.md

# FFX Config

FFX's configuration management allows you to configure your FFX code without
recompiling. From a high level, configurations can be thought of as a
 multi-layered, key-value map.

## Value resolution process
The configuration management code searches in several locations for the value
associated with a key. The search is performed in the following order
and returns the first value found:

1. [Runtime configuration (set by the command line)](#runtime-configuration)
2. [User level configuration (set by `ffx config set`)](#user-configuration)
3. [Build directory level configuration (generated by the build)](#build-configuration)
2. [Global level configuration variables](#global-configuration)
3. [Default configuration (compiled into ffx)](#default-configuration)


### Runtime configuration

Runtime configuration is set by the user on the command line when invoking ffx.
The top-level command accepts a configuration parameter:

```posix-terminal
ffx --config "property-name=value" ...
```

The runtime parameter takes the format of comma separated key-value pairs
("{key}={value},{key}={value},etc...") because this is not strongly typed, any
configurations set here will be assumed to be strings.

#### Dot notation for nested configuration

Dot notation (.) allows you to define nested JSON objects directly in the
command line. When a configuration key contains a dot, each word preceding a
dot is interpreted as a JSON object containing the subsequent part of the key.

For example, `log.dir` tells `ffx` that `log` is a JSON object, and inside we
will set the `dir` property. Therefore running
`ffx --config "log.dir=/path/to/dir" ...` is equivalent to setting the
following JSON configuration:

```json
{
    "log": {
        "dir": "/path/to/dir"
    }
}
```

Note:

The daemon runs as its own process and currently the runtime
configuration is not transferred from the CLI to the daemon if the daemon is
started up. It's expected that if you want to configure the daemon using
the runtime configurations, the daemon command will be run manually:

```posix-terminal
ffx --config "config-test=runtime" daemon start --background
```

### User configuration

User configuration is configuration set in the user's home directory and
applies to all invocations of ffx by that user. User configuration is only
overridden by runtime configuration.

User configuration is set using the `ffx config set` command.

```posix-terminal
ffx config set property-name value
```

### Build-directory configuration

Build configuration is associated with a build directory. It is intended to be
used to set properties describing the output of the build. It should be
generated as part of the build process, and is considered read-only by ffx.

The file format is a JSON object:

```json
{
    "product": {
        "path": "/out/project/dir/product_bundle",
        "name": "sample_project"
    },
    "fidl": {
        "ir": "$BUILD_DIR/fidling/gen/ir_root"
    }
}
```

Note:

`$BUILD_DIR` in this example is not a shell environment variable, but an
internal ffx variable placeholder. See [value representations](#value-representations)
for more details.

### Global configuration

Global configuration is intended to be a system-wide configuration level.
It is intended to be used when installing ffx on a host system to set
organizational properties that would be the same for a collection of users.

It is created outside the `ffx` workflow, and is considered read-only by ffx.

The file format is a JSON object:

```json
{
    "gcs": {
        "release_bucket": "gs://project/releases",
    }
}
```

### Default configuration

Default configurations are provided through GN build rules across all
subcommands and are hard-coded and immutable.

## Value representations

The values stored in the ffx configuration are encoded as JSON values.

* Number, both integer and floating point numbers.
* String
* Boolean, true|false.
* Null, represented as `null`
* Arrays of values
* Object

### String interpolation

Some strings can include placeholders that are interpolated. This allows properties
to be set relative to directories, or resolve values from the running process
environment.

Placeholders defined by ffx are:

* `$BUILD_DIR` - the build directory determined when running an ffx command. It
  can be empty if no build directory is located, nor configured.
* `$CACHE` - the directory to use to store cached data.
* `$CONFIG` - the directory to store configuration data.
* `$DATA` - the directory to store persistent data.
* `$SHARED_DATA` - the directory for persistent data that is shared between all
  isolates and instances of `ffx` on the current host machine. This is used for
  data that is used to manage global state, such as processes that are opening
  TCP/IP ports.
* `$FIND_WORKSPACE_ROOT` - the first parent directory containing a Bazel workspace.
* `$HOME` - the home directory of the current user.
* `$RUNTIME` - the directory to store all runtime information. On Linux this is
  typically `$HOME/.local/share/Fuchsia/ffx`.

Additionally, any string consisting of `$` followed by a name in all-capitals,
digits, and other allowed characters is resolved from the process environment.

### Array processing

Arrays are commonly used to provide an ordered list of possible values, and then
return the first non-empty value.

For example, to attempt to use the ssh key from the environment,
otherwise falling back to a standard location:

```json
{
    "ssh_key": [ "$SSH_KEY_FROM_ENV", "$HOME/.ssh/ssh_key"]
}
```


## Configuration environment settings

The command collection `ffx config env` is used to manage the configuration
of how to locate the various configuration level data files.

For example, to set the path to the global configuration:

```posix-terminal
ffx config env set --level global /etc/fuchsia/ffx_global_props.json
```