Skip to content
alpha 0.1.0-alpha.7 is on crates.io. Install the CLI Start here

0002 - Configuration

Status: Implemented (Phase 0 closed 2026-11-17; Phase 2 signing keys added in spec 0011)

Auro.toml is the only file an app author edits to describe their app. This spec fixes its location, format, every Phase 0 key, the merge rules, and what makes it invalid.

Decisions

D1 - TOML, kebab-case, next to the crate manifest

  • File: Auro.toml at the app crate root, beside Cargo.toml.
  • Keys: kebab-case (TOML idiom). Section and field names mirror Tauri's tauri.conf.json, so a Tauri user recognises the shape; the case convention is the only translation. Mapping is mechanical and lives in auro-bundle when it lands.
  • Unknown keys are errors, not warnings. A typo in a config file must not silently do nothing.

Rejected: JSON. It is the format Tauri uses, but it costs comments and trailing commas for no benefit in a file humans maintain by hand. Rejected: TOML with camelCase keys. It satisfies neither idiom.

D2 - Load order and overrides

  1. AURO_CONFIG (a path) if set, otherwise Auro.toml in the app directory (current directory, or the one --dir names), falling back to the executable's directory.
  2. Auro.<platform>.toml where platform is macos, windows or linux, merged key by key.
  3. AURO_CONFIG_OVERRIDES, a JSON Merge Patch set by auro dev from --config key=value flags, merged last. This environment variable is the only CLI-to-app channel. auro build gains overrides with embedded config in Phase 2; a Phase 0 build has no runtime to hand them to.

Merge is recursive for tables and replacing for arrays: a platform file that declares app.windows replaces the list; it does not append to it. Merging arrays positionally is how config systems become unreadable. The rule is JSON Merge Patch (RFC 7396) minus the null-deletes case, which TOML cannot express.

auro dev --config uses the resolved config as a type hint. A field that is a string keeps a bare 123 as "123"; numeric, boolean, array and object fields parse JSON. A nullable field has no value to hint from, so both the string and the JSON form are tried against the resolved Config: Option<String> keeps 123 as a string and Option<u32> parses it as a number. Quoting the value always produces a JSON string. Numeric path segments index arrays. Because a merge patch replaces arrays wholesale, an indexed path seeds its array from the resolved config before changing one element, so app.windows.0.width=800 keeps that window's label and the other windows. An index past the resolved array is rejected: a patch cannot insert a TOML-null slot or invent a complete element. null is rejected because TOML has no null value.

In Phase 0 the file is read at runtime. Bundled apps embed it in Phase 2.

D3 - Windows are a list

app.windows is an array of tables; the first one is the default unless app.default-window names another. Labels are unique and stable: they are what a capability targets later.

Schema

Required: app.identifier, app.product-name, app.version, and at least one window.

Top level also accepts "$schema" (string): an editor hint pointing at the published JSON Schema. It is never read at runtime and never affects behaviour.

[app]

KeyTypeDefaultNotes
identifierstringrequiredreverse-DNS, [A-Za-z0-9.-], no leading/trailing dot; becomes the bundle id
product-namestringrequiredwindow-title default and bundle display name
versionstringrequiredSemVer; must match Cargo's concrete package.version (including version.workspace = true) or the build fails
descriptionstring""one line, used by the bundle metadata
authorsarray of string[]"Name <email>"
homepagestring""URL
licensestring""SPDX expression; must be compatible with MIT OR Apache-2.0
default-windowstringfirst window's labelmust match a declared label

[[app.windows]]

KeyTypeDefaultNotes
labelstringrequiredunique, [A-Za-z0-9_-]
titlestringapp.product-name
widthinteger960logical pixels
heightinteger640logical pixels
min-widthintegernone
min-heightintegernone
max-widthintegernone
max-heightintegernone
resizablebooltrue
decorationsbooltrue
transparentboolfalse
always-on-topboolfalse
visiblebooltrue
centerbooltrue
fullscreenboolfalse
theme"light" | "dark" | "system""system"

[dev]

KeyTypeDefaultNotes
watcharray of string["src", "Auro.toml"]paths relative to the app dir
run-argsarray of string[]passed to the spawned binary in relaunch mode; dx owns the process in hot mode and auro dev prints a note
build-argsarray of string[]passed to cargo build
hotboolfalserun dx serve --hot-patch instead of rebuild-and-relaunch; needs dx (dioxus-cli 0.7.x) on PATH or AURO_DX, plus the app's hot-reload feature. auro dev refuses with the missing feature named, and auro doctor reports availability. Patches are applied by dx, so run-args are not forwarded, target-dir builds belong to dx, and only code reached through auro::hot::hot/hot_with reloads in-process. The generated layout puts the boundary in data/src and reports it through hot_frame/rendered; edits outside data/src are host code and restart the devserver/app with the snapshot restored

[bundle]

Validated in Phase 0 and consumed by auro bundle (spec 0010) in Phase 2. Nothing here changes auro build.

KeyTypeDefaultNotes
activebooltrue
targetsarray of string | "all""all"app, dmg, msi, nsis, appimage, deb, rpm; the list must be non-empty; unsupported per host is an error, not a skip
iconarray of string[]first existing format wins per platform
resourcesarray of string[]glob patterns, relative to the app dir
categorystring"DeveloperTool"Apple/XDG category name
short-descriptionstring""installer metadata
long-descriptionstring""
copyrightstring""
license-filestring""shipped in the bundle when set

[bundle.macos]

Code signing and notarization inputs. tauri-bundler reads APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID (or the Apple API key variables) from the environment; those credentials are never config keys. notarize-profile selects Auro's keychain-profile path instead.

KeyTypeDefaultNotes
signing-identitystringnonepassed to codesign
entitlementsstringnoneplist path relative to the app dir
hardened-runtimebooltruedistribution default
skip-staplingboolfalsedo not wait for/stapling the notarization ticket
notarize-profilestringnonexcrun notarytool keychain profile; auro bundle notarizes and verifies the produced .app/.dmg, and ignores the key on hosts that produce no macOS artifact (spec 0032)

[bundle.windows]

Authenticode signing inputs.

KeyTypeDefaultNotes
certificate-thumbprintstringnoneSHA-1 of the signing certificate
digest-algorithmstringnonee.g. sha256
timestamp-urlstringnonetimestamp server
tspboolfalseRFC 3161 timestamping
sign-commandstringnonecustom signer; %1 in sign-args is the binary
sign-argsarray of string[]arguments for sign-command
allow-downgradesbooltrueallow an older version to replace a newer one

webview-install-mode is not configurable: Auro has no webview and always skips WebView2.

Validation

Failures are AuroError::Config { path, key, message } and abort before a window opens. Rules:

  1. Unknown key: reported with the key path and the closest known key, if any.
  2. Wrong type or missing required key: reported with the key path.
  3. app.version differing from Cargo.toml: reported by auro build and auro dev, naming both values. The running app cannot see the manifest, so it does not perform this check.
  4. Duplicate window labels, or default-window naming nothing: error.
  5. bundle.targets naming a package format the host cannot produce: error listing the valid set for that host. The known formats are app, dmg, msi, nsis, appimage, deb and rpm; the host sets are macOS app/dmg, Windows msi/nsis, and Linux appimage/deb/rpm. An explicit list that is empty is rejected; use "all" to request the host set.
  6. Relative watch, icon, license-file, resources or bundle.macos.entitlements paths escaping the app directory: error.
  7. Window width/height must be greater than zero; a set min-width/min-height/ max-width/max-height must be greater than zero, a minimum must not exceed its maximum, and the initial size must lie inside the configured bounds.
  8. A window declared in app.windows without a matching App::root/App::root_with is a typed AuroError::Window before the event loop starts, not a headless process.

Interfaces

# Auro.toml - the smallest valid file
[app]
identifier = "com.example.demo"
product-name = "Demo"
version = "0.1.0"

[[app.windows]]
label = "main"
title = "Demo"
width = 960
height = 640
pub struct Config { pub app: AppConfig, pub dev: DevConfig, pub bundle: BundleConfig }
impl Config {
    /// Tries `AURO_CONFIG`, then `<dir>/Auro.toml`, then the executable's directory; merges the
    /// platform file and `AURO_CONFIG_OVERRIDES`, validates, returns.
    pub fn load(dir: &Path) -> Result<Config, AuroError>;
}

Acceptance

  • The smallest valid file parses; every default in the tables above is the value the app uses where the platform can express it. auro doctor lists the keys the current platform cannot honor.
  • A missing Auro.toml fails with exit code 2 and a message naming the paths searched.
  • An unknown key under [app] fails with a message naming it.
  • Auro.linux.toml overriding app.windows replaces the list; overriding app.product-name changes only that key.
  • A version mismatch against Cargo.toml fails auro build and auro dev.
  • Round-trip test: every documented key is set to a non-default value, serialized back, and equals the original.

Status (2026-11-17)

Implemented and accepted with Phase 0. Coverage lives in auro-core/src/config.rs (parses_the_minimal_file_and_applies_defaults, platform_file_replaces_arrays_and_merges_tables, rejects_unknown_keys, missing_config_names_both_places_searched, falls_back_to_the_executable_directory, rejects_a_bundle_target_this_host_cannot_produce, every_documented_key_survives_a_round_trip), in auro-cli/src/project.rs (refuses_a_config_version_that_disagrees_with_the_manifest, accepts_matching_versions), and in auro doctor against a real app.