nself yaml

nself.yaml

← Configuration

---

nself.yaml (or nself.yml) is the project manifest nself build reads to decide which plugins and bundles belong to the project. It holds no configuration values: those live in .env files (see Config-Env-Vars).

Keys nself reads

Key	Type	Meaning
app	string	Project name.
cli_min_version	string (optional semver, with or without v)	Minimum nself CLI version this project needs. Older releases get a doctor warning with E060 and Fix: nself update; development builds skip comparison. Build and start are unchanged.
bundle	string	One bundle to install, expanded from the bundle catalog.
bundles	list of strings	Several bundles.
plugins	list of strings, or a map with free and pro lists	Plugins to wire in.

Every other key is not read. The same list, as a machine contract, is schemas/nself-yaml.v1.schema.json, generated by tools/schemagen from the ProjectManifest Go type (never hand-edited; make schemas regenerates it and make contract-check fails when it drifts).

app: myapp
cli_min_version: 1.4.0
bundle: task
plugins:
  free: [cron, notify]
  pro: [ai]
x-display-name: My App      # extension key: ignored

The x- rule

A key that starts with x- is an extension. nself ignores it and the validator accepts it, at the top level and inside the plugins map. Use it for app metadata that tools other than nself read (a display name, an owner, a tier). Rename an unread key tier to x-tier to keep it without a finding.

Validation

nself config validate also checks nself.yaml when the project has one. It runs after the existing validators. Each finding goes to stderr as file:line:col: severity: path: [code] message (fix).

Code	Finding
E436	An unknown key, at any depth the types describe (for example plugins.required). The fix names a close match when there is one (project suggests app) and the x- rename.
E435	A syntax error, an unreadable file, a duplicate key (the finding names the key and the line of the first one; nself build rejects it too), or a value of the wrong type (plugins: 7, a plugin entry that is a map, a non-string app).
E061	cli_min_version is not a complete semantic version such as 1.4.0 or v1.4.0. It warns in v1.4 mode and fails validation in v1.5 mode.

Mode	Findings are	Exit status
v1.4 (default)	warnings	unchanged: config validate exits as it did without the check
v1.5 (opt in; see Compat-V15)	errors	1 when there is any finding

Scalars that build coerces: quote them

nself build turns a number, boolean or date written where a string belongs into text (app: true becomes "true", bundle: 1.5 becomes "1.5", app: 2024-01-01 becomes a date string). That is rarely what you meant, so the validator reports it as E435 and the fix is to quote the value: app: "1.5". (YAML 1.2 readers keep no and yes as text, so those need no quotes.)

Merge keys, extra documents, empty files

• Merge keys (<<: *anchor, or <<: [*a, *b]) are resolved, and the merged keys are validated like explicit ones; explicit keys win. The JSON Schema cannot see merges, so for a file that uses << the validator is authoritative and the schema is not compared.
• Only the first YAML document is read. A later document (after ---) is ignored by nself build; the validator says so with a warning in both modes.
• An empty file, or one holding only ~ or null, is an empty manifest: valid, and the schema accepts a null document.

See Compat-V15 and error-codes. nself build parsing is not changed by the validator: a file that builds today still builds.

Reference apps

The reference-app manifests carry keys nothing reads (display_name, version, tier, auth_mode, services, project). In v1.4 they show up as warnings. The migration to x- keys is done in the reference-app repos, not here.