
# Command line, environment and --dart-define

Config files hold the values an application ships with. The sources on this page change them at launch or at build time, without editing a file. Each one wins over the config files; the full order is on [the overview](index.md#which-source-wins).

## Why

A server in a container gets its settings as environment variables. A CI job passes options on the command line. A Flutter app has neither, so it gets per-build values as `--dart-define`s. All of them reach the same keys, under the names each source can write.

## Example

```yaml
# lib/resources/application.yml
shop:
  max-basket-size: 10
  api-url: http://localhost:8080
```

```bash
dart run bin/main.dart --shop.max-basket-size=30         # command line
SHOP_MAXBASKETSIZE=30 dart run bin/main.dart             # environment variable
SPRING_APPLICATION_JSON='{"shop":{"max-basket-size":30}}' dart run bin/main.dart
flutter run --dart-define=SHOP_API_URL=https://api.neon.books   # build time
```

All four set `shop.max-basket-size` (or `shop.api-url`), which `@Value(r'${shop.max-basket-size}')` and `@ConfigurationProperties('shop')` read.

## Command line

```bash
dart run bin/main.dart --shop.max-basket-size=30 --spring.profiles.active=prod --debug
```

- `--key=value` sets `key`; only the first `=` separates.
- `--flag` alone sets `flag` to an empty value (`--debug` turns on the condition report).
- A repeated option keeps all its values, joined with commas.
- A lone `--` ends the options; what follows are plain arguments.
- Plain arguments are not properties. Runners get them through `ApplicationArguments.nonOptionArgs` (see [Runners](../runners.md)).

A Flutter desktop app passes its arguments with `SpringApplicationWidget(args: ...)`.

## Environment variables

`SHOP_MAXBASKETSIZE=20` sets `shop.max-basket-size`. The name is split at `_` and lower-cased, and dashes do not matter. A part that is a number becomes an index:

| Variable | Key |
|---|---|
| `SHOP_MAXBASKETSIZE` | `shop.max-basket-size` (also `shop.maxBasketSize`) |
| `SHOP_HOSTS_0_` or `SHOP_HOSTS_0` | `shop.hosts[0]` |
| `APP_MAIN_SERVER_HOST` | `app.main-server.host` (bound to a nested object) |
| `SPRING_PROFILES_ACTIVE` | `spring.profiles.active` |
| `LOGGING_LEVEL_NEON_CHECKOUT` | `logging.level.neon.checkout` |

Phones and browsers have no useful environment. A Flutter app reads it only when the build defines `spring.flutter.scan-os-environment=true`.

## Relaxed names

A property has a canonical name in kebab case: lower-case words joined by `-`, such as `shop.max-basket-size`. Each source may write it its own way, and it still matches:

| Written as | Where |
|---|---|
| `shop.max-basket-size` | the canonical form, recommended in files |
| `shop.maxBasketSize` | camel case, in files |
| `shop.max_basket_size` | underscores, in files |
| `SHOP_MAXBASKETSIZE`, `SHOP_MAX_BASKET_SIZE` | environment variables and `--dart-define` |

Inside `[...]`, a map key is taken exactly as written. Code that reads a key (`@Value`, `environment.getProperty`) should use the canonical form.

## --dart-define

Values given at build time with `--dart-define` (`-DKEY=value` for `dart run` and `dart compile`) are a property source right below the command line, above the environment and the config files. They take the relaxed names of environment variables:

```bash
flutter build apk --dart-define=SPRING_PROFILES_ACTIVE=prod \
  --dart-define=API_URL=https://api.neon.books
flutter build apk --dart-define-from-file=config/prod.json
dart compile exe bin/main.dart -DSHOP_MAXBASKETSIZE=30
```

```dart
@Value(r'${API_URL}') String apiUrl     // https://api.neon.books
@Value(r'${api.url}') String sameUrl    // relaxed, like an environment variable
```

`SPRING_PROFILES_ACTIVE` activates `application-prod.yml`, so profiles can replace build flavors.

On the web and in AOT builds, `String.fromEnvironment` works only as a `const` with a literal key, so a define must be known when the program is compiled. The generator therefore lists every key the application can read, each also in its environment form, as `SpringApplication(dartDefines: ...)`:

- the `${...}` placeholders of annotations;
- the `@ConditionalOnProperty` names;
- the fields of `@ConfigurationProperties` classes;
- the keys and placeholders of the `application*` config files;
- `spring.profiles.active`.

A key read only in code (`environment.getProperty('x')`) is not listed: put it in `application.properties` (even empty), or pass it to `SpringApplication(dartDefines: {...})` yourself. See [--dart-define keys](../../spring-core-dart-generator/dart-defines.md).

Defines are compiled into the program and can be read from an APK, an IPA or `main.dart.js`. Never pass passwords or private keys this way.

## SPRING_APPLICATION_JSON

A JSON object in the environment variable `SPRING_APPLICATION_JSON`, or in the property `spring.application.json` (for example on the command line). It is flattened into properties right above the environment variables, below the command line and the `--dart-define`s. Handy where a platform passes configuration as one variable:

```bash
SPRING_APPLICATION_JSON='{"shop":{"hosts":["a","b"],"max-basket-size":30}}' dart run bin/main.dart
# shop.hosts[0]=a, shop.hosts[1]=b, shop.max-basket-size=30

dart run bin/main.dart --spring.application.json='{"server":{"port":9090}}'
```

The JSON comes from the first source that has either name. It is read before the config files, so it can set `spring.config.*` and `spring.profiles.active`. JSON that cannot be parsed, or that is not an object, fails the start.

## In code

| Where | Precedence | Use |
|---|---|---|
| `SpringApplication(defaultProperties: {...})`, or `setDefaultProperties` | Lowest: every file overrides it | Defaults of a program that may run without a config file |
| `run(args, properties: {...})` | Highest: above the command line | Tools and tests (`springBootTest(properties:)` is built on it) |
| `run(args, systemEnvironment: {...})` | Replaces the OS environment | Tests |
| `SpringApplication(environmentPostProcessors: [...])` | Any: the code adds sources where it wants | Settings from a server or a vault, computed profiles |

```dart
// A tool that works without application.properties.
void main(List<String> args) => SpringApplication(
      [toolBeans],
      defaultProperties: {'tool.output': 'out/', 'logging.level.root': 'warn'},
    ).run(args);
```

`EnvironmentPostProcessor` is described on [Imports](imports.md#your-own-kind-of-location).

## Placeholders

A value can contain other properties: `${key}` is replaced by the value of `key`, and `${key:default}` uses `default` when `key` is not set.

```yaml
shop:
  name: NEON Books
  title: ${shop.name} (${spring.profiles.active:local})
  url: ${SHOP_URL:http://localhost:8080}
  api: ${shop.url}/api/v${shop.api-version:1}
  literal: \${not.a.placeholder}
```

- `\${` gives a literal `${`. In `.properties` write `\\${`.
- `${db:url}` is first looked up as the key `db:url`, then as `db` with the default `url`, as in Spring 6.2.
- A placeholder that cannot be resolved and has no default fails where the value is needed (`@Value`, `getProperty`), with a report naming it. `@ConfigurationProperties` binding keeps it as written.
- In Dart, write `@Value` strings as raw strings (`r'${shop.name}'`), because `'${...}'` is Dart's string interpolation.
- `#{...}` (SpEL) is evaluated only in `@Value` and `@ConditionalOnExpression`, never in config files.

See [Placeholders](../../spring-core-dart/config/placeholders.md).

## Random values

`${random.*}` gives a new random value on every read, for values that must differ per run:

| Placeholder | Value |
|---|---|
| `${random.int}`, `${random.long}` | Any int or long (at most 53 bits on the web) |
| `${random.int(10)}`, `${random.int[5,10]}`, `${random.long(100)}` | A number in a range; the upper bound is excluded |
| `${random.uuid}` | A random version 4 UUID |
| `${random.value}`, or any other `random.*` | 32 random hex digits |

## Writing values

Every value is text; it is converted when it is bound to a typed field.

| Type | Forms |
|---|---|
| `Duration` | `10s`, `500ms`, `5m`, `1h`, `2d` (units `ns`, `us`, `ms`, `s`, `m`, `h`, `d`, any case); ISO-8601 `PT10S`, `P1DT2H` (no years or months); a plain number is milliseconds, or the unit of `@DurationUnit` |
| `DataSize` | `512B`, `10KB`, `5MB`, `1GB`, `1TB`, any case, powers of 1024, whole numbers only; a plain number is bytes, or the unit of `@DataSizeUnit` |
| `bool` | `true`, `on`, `yes`, `1` / `false`, `off`, `no`, `0`, any case; anything else fails the start |
| enums | Matched ignoring case and separators: `ONLY_SHOW_SELECTED`, `only-show-selected`, `onlyShowSelected` |
| numbers | Decimal, or hex (`0x1F`, `#1F`); an empty value counts as "not set" |
| lists | A comma list, a YAML list or indexed keys |

See [Durations](../../spring-core-dart/conversion/durations.md) and [Data sizes](../../spring-core-dart/conversion/data-size.md).

## Renamed properties

A few of Spring Boot's prefixes carry Java history that means nothing in Dart. They have other names here:

| Spring Boot | Here |
|---|---|
| `spring.jackson.*` | `spring.json.*` |
| `spring.cloud.openfeign.*` | `spring.feign.*` |
| `spring.servlet.multipart.*` | `spring.web.multipart.*` |
| `server.servlet.*` | `server.*` |
| `logging.logback.rollingpolicy.*` | `logging.file.rolling-policy.*` |
| `spring.flyway.*` | `spring.sql.migration.*` |

An old name is never ignored in silence. Any key under an old prefix, in any source (a file, the command line, a `--dart-define`, an environment variable such as `SPRING_JACKSON_TIME_ZONE`), stops the start:

```text
Description:

These properties have been renamed:

  - spring.jackson.default-property-inclusion is now
    spring.json.default-property-inclusion
```

Spring Boot's `spring-boot-properties-migrator` only warns and keeps reading the old name; a forgotten `server.servlet.session.*` would then leave the sessions on their defaults.

## In Spring (Java)

The command line, environment variables, relaxed binding, `SPRING_APPLICATION_JSON`, placeholders and random values follow Spring Boot. `--dart-define` has no Java counterpart (the nearest is `-Dkey=value` system properties). There is no `.env` file support.

## See also

- [Overview: which source wins](index.md)
- [Config files](config-files.md)
- [@ConfigurationProperties](../configuration-properties.md)
- [Environment](../../spring-core-dart/config/environment.md)
- [@Value](../../spring-core-dart/config/value.md)
