ember
Documentation menu

Commands

embr add

Last updated October 23, 2026

embr add <scope>/<name> [--version <req>] [--index <key>] [--alias <name>]
        [--scoped] [--refresh]
embr add <name>

Records a dependency in [dependencies].

Behavior#

  • Resolves first, edits after — a typo'd package or impossible version fails before ember.toml is touched.
  • Without --index it prompts for an index key ("press enter to use Ember's index"); empty input means the default index — the default key under [indices] if defined, Ember's own registry otherwise. Pass --index to skip the prompt (needed for non-interactive shells).
  • A name with no scope is a local package. Ember finds it by its name in every scope of the local registry and adds it with index = "local", with no prompt. If two scopes have that name, use embr add <scope>/<name> --index local.
  • --version defaults to ^ (latest).
  • --alias sets the [dependencies] key (defaults to the package's short name); the alias is also the link file's name.
  • --scoped keys the dependency by its full scope/name, such as "mayari/core". Install then links it at packages/<environment>/mayari/core.luau, in a folder named after the scope. It cannot be used with --alias. See scoped keys.
  • Resolves against an index up to 5 minutes old. If resolution fails on a stale index, Ember refreshes it and retries once before reporting an error, so a just-published package is still addable without any flag. --refresh re-fetches the index up front instead.
  • Names are lowercased. Edits preserve comments and formatting in ember.toml.
  • Prints the resolved version and reminds you to run embr install.

Examples#

embr add chief/core                            # latest, Ember registry
embr add evaera/promise --index wally          # from the wally index
embr add chief/lifecycles --version "^0.2" --alias Cycles
embr add mayari/core --scoped                  # key "mayari/core"
embr add my-lib                                # a local package

Hooks#

A preadd script runs before the index prompt, so it can set up whatever resolving needs; postadd runs after ember.toml has been written. See Lifecycle hooks.

See also#