ember
Documentation menuembr 0.13.0

Commands

embr template

Last updated November 3, 2026

embr template save <name> [--force]
embr template list
embr template show <name>
embr template remove <name>
embr template publish <name> [--private] [--repo <owner/name>] [--yes]
embr init --template <name | owner/repo[#ref] | folder>

A template is a project folder with an ember.toml at its root. Save a project as a template, start new projects from it with embr init --template, and put it on GitHub as a template repository. Templates need embr 0.13.0 or later.

A template carries the files that its author put in it, the [scripts] included. Ember adds no scripts of its own.

Save a project#

embr template save rojo-game

Run it in a folder with an ember.toml. Ember copies the project to ~/.ember/templates/rojo-game/. A name is letters, digits, - and _. A saved template of the same name is an error, and --force replaces it.

Ember leaves these out:

WhatWhich
Secret files.env*, *.pem, *.key, *.p12, *.pfx, id_rsa*, id_dsa*, id_ecdsa*, id_ed25519*, .netrc, .pypirc, and an .npmrc that holds a token or a password
Tool folders, at any depth.git, .ember, .ember-staging, .ember-patch, .alloy, .larvae, node_modules, target
Packages and build output, at the root onlypackages, ServerPackages, DevPackages, roblox_packages, lune_packages, luau_packages, build, dist, out, and the packages folders that [config] names
Lockfiles*.lock (such as ember.lock, wally.lock, pesde.lock), *.lockb, package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml
Ignored fileseach path that the root .gitignore matches; a ! rule takes a path back
Symlinksa template holds plain files only

The output names each file that it left out, the secret files on a line of their own:

✓ Saved template rojo-game with 12 files
Left out 2 secret files: .env, deploy.pem
Left out: .git/, ember.lock, game.rbxl, node_modules/, packages/

Ember reads only the .gitignore at the root of the project. A .gitignore in a subfolder and your global git excludes do not count. Check the list, and add a rule to the root file when a path must stay out.

List, show and remove#

embr template list            # each name, and the folder it came from
embr template show rojo-game  # the source, where the copy is, and every file
embr template remove rojo-game

list and remove also answer to ls and rm.

Start a project from a template#

embr init --template rojo-game
embr init --template acme/game-template
embr init --template acme/game-template#v2
embr init --template ../other-project

--template takes, in this order:

  1. the name of a saved template;
  2. a folder;
  3. a GitHub repository, owner/repo, with an optional #branch, #tag, or #commit.

The current folder must be empty. A .git folder is allowed, so you can clone an empty repository first. Ember copies the template, then:

  • When the template has a [package] table, Ember sets name from --name, from the name: question, or from the name that embr init guesses from git, and sets version to 0.1.0. The comments and the format of the file stay.
  • Ember changes nothing else. There are no placeholders to fill in, and init does not install.

Ember asks for the name before it writes a file, so a failed guess leaves the folder empty. A folder template goes through the same filter as save, so ../other-project brings no .git, packages or .env. A GitHub template arrives as its author committed it.

--template cannot go with --kind, --language or --environment, because the template has its own ember.toml.

In a terminal, embr init with no flags asks template: first. The choices are none, each saved template, and GitHub repository…, which asks for owner/repo.

Templates from GitHub#

Ember downloads the tarball of the repository from the GitHub API. A public repository needs no token. When GitHub answers 404, Ember tries again with a GitHub token, for a private repository. The token goes to api.github.com only, and not to the download host that GitHub redirects to.

Ember checks every entry of the tarball before it writes one. It refuses the whole archive when an entry has an absolute path, a .., or a .git folder, when a symlink points out of the project, when a path goes through a symlink, and when an entry is not a file, a folder or a symlink.

Publish a template to GitHub#

embr template publish rojo-game                  # public, as <you>/rojo-game
embr template publish rojo-game --private
embr template publish rojo-game --repo acme/game-template

publish creates a new GitHub repository, marked as a template repository, and pushes the files of the saved template as its first commit. Then "Use this template" on GitHub works, and so does embr init --template <owner>/<name>.

  1. Ember reads your GitHub login. Without --repo, the repository is <login>/<template name>. --repo can name an organization.
  2. It prints the files and asks Create the repository?. --yes skips the question. Without a terminal, publish stops here unless you pass --yes.
  3. It creates the repository: public, or private with --private.
  4. It pushes the files with git when git is on PATH, and with the GitHub API when it is not.

The repository name must be free. GitHub refuses a name that the owner already has, and Ember shows GitHub's message. When the push fails after the repository exists, the error names the repository. Delete it on GitHub, then publish again.

GitHub authentication#

Downloads of private templates and publish use the first token that Ember finds:

  1. gh auth token, when the GitHub CLI is installed and logged in;
  2. the GH_TOKEN variable;
  3. the GITHUB_TOKEN variable.

Ember reads the token on each run and never writes it to disk. The token must be able to create repositories for publish, and to read the repository for a private download. Without a token, the error tells you to run gh auth login or to set GH_TOKEN or GITHUB_TOKEN.

This is a GitHub token, not your Ember login. embr auth holds an Ember token for the registry, and templates do not use it.

See also#