embr install

embr install [--locked] [--refresh]
embr i                    # alias

Installs dependencies and tools.

The fast path#

When ember.toml, ember.lock, and the global tools file (~/.ember/tools.toml) are unchanged since the last successful install, and the indices were checked within the last 5 minutes, install verifies the pinned tools (repairing any that are missing) and does nothing else — single-digit milliseconds.

Once the 5-minute window lapses, the next install re-checks the indices for real, so version = "^" still picks up new releases automatically, at most 5 minutes late. If nothing resolved differently, the rebuild is skipped (~0.7 s) and the window resets. The window length is EMBER_INDEX_TTL_SECS (Files & locations).

Two things the fast path cannot see: hand-edits inside an installed packages/ folder, and a repository that commits its packages/ folders (those packages really are present, and tools still verify, so skipping is correct). Workspaces never take the fast path.

Flags#

• --refresh skips nothing: re-resolves, re-pulls every index, and re-downloads archives even when caches are fresh. It is the "check right now" and "my cache is somehow wrong" escape hatch.
• --locked installs exactly what ember.lock records without consulting any index, and errors if the lockfile is missing. It bypasses the fast path and never marks the project as up to date — a --locked install applies the lockfile without reconciling it against the manifest, so the next plain install always re-checks. It also refuses a version 1 lockfile, since replaying one would scatter trees across environment roots; run a plain embr install once to regenerate it.

Resolution#

Re-resolves everything on each full install (the fast path skips this while nothing has changed), so version = "^" picks up new releases.

Downloads#

Packages download and unpack concurrently, and downloaded archives are cached under ~/.ember/archive-cache, so reinstalls skip the network. embr cache clean empties the cache.

Patches#

[patches] entries (embr patch) attach to the resolved graph before anything downloads, and each one is applied to its package's freshly extracted tree — before link generation and require rewriting. A patch that cannot land exactly (the package left the graph, resolved to a different version, or would cover only some environment roots) is a hard error, never a silent skip. Patch file bytes are part of the fast path's state, and --locked verifies each file still matches the hash the lockfile recorded.

Output folders#

Rebuilds output folders from scratch on every full install — each environment's configured output folder is deleted and rebuilt, so removing the last dependency leaves nothing stale. Each folder is a self-contained root: a dependency tree installs entirely under its root's environment, not under each package's own.

Don't keep hand-written files inside packages-out folders. They are deleted on the next full install, and the fast path cannot see them.

The lockfile#

Writes ember.lock on every full install (even when empty, so it always mirrors the manifest). --locked never rewrites it. Commit the lockfile — see Dependencies & installing for its format.

Tools#

After dependencies, install handles tools: the project's [tools] plus global tools (~/.ember/tools.toml), deduplicating identical pins. Tools are pinned to exact versions, so they have no lockfile entries and install identically with and without --locked. Install warns when another toolchain manager's executable (aftman, rokit) shadows an Ember shim on PATH.

Workspaces#

In a workspace root, install covers the root project first, then every member — each into its own packages folders, each writing its own lockfile.

Offline#

Indices are git clones cached under ~/.ember/index-cache; a successful check keeps an index fresh for 5 minutes, and when a refresh fails the stale cache is used with a warning.

Per-package warnings#

Install continues past these, with a warning:

• No entry point found → no link file is generated.
• Entry point fails to parse → linked without type re-exports.

Hooks#

A preinstall script runs before anything is resolved or downloaded, and postinstall runs after the install completes — a natural place for embr build. In a workspace, each manifest's hooks bracket its own portion, so a root postinstall sees a fully installed workspace. See Lifecycle hooks.