CLI

Configuration

Set the default package manager and engine version for new projects, review the environment variables the CLI reads, and check for a new CLI release.

The CLI keeps two settings in a file in your user configuration folder. They are the defaults for the commands that create projects. The config commands read and write them. This page also lists the environment variables the CLI reads and explains update, which checks for a new CLI release.

shell
bornengine config list
bornengine config set package-manager npm
bornengine config get package-manager
bornengine config set engine-version 0.18.2

The two settings

KeyValuesDefaultUsed by
package-managerpnpm, npm, or yarnpnpmcreate, new, init, and create server; also doctor when it cannot find a manager in the project
engine-versionlatest, or an exact stable version such as 0.18.2latestcreate, new, and init

You may write a key with a hyphen or an underscore. config list prints the current values:

plaintext
package-manager = pnpm
engine-version = latest

config set <key> <value> prints Set <key> = <value>. config get <key> prints only the value. Any other key stops with unsupported configuration key. The CLI checks values before it saves them. A package manager name is not case-sensitive and is stored in lowercase. An engine version must be latest or an exact stable semantic version: ranges, prereleases, and build metadata are rejected, and the file is left unchanged.

These settings are defaults, and an option on the command line wins over them. To choose the engine for a new project, create, new, and init use the first of these that is set:

  1. --engine-path on the command line.
  2. The BORNENGINE_PATH environment variable. It wins over --engine-version too.
  3. --engine-version on the command line.
  4. The engine-version setting, which is latest unless you changed it.

Commands that change an existing project, such as engine install and upgrade, do not read engine-version. They choose the package manager from the project first: the packageManager field of package.json, then a lockfile. They fall back to the package-manager setting only when the project names none.

The configuration file

config set creates the file the first time. Without the file, the CLI uses the defaults. The file lives here:

  • Linux: ~/.config/bornengine/config.toml, or under $XDG_CONFIG_HOME when that variable is set
  • macOS: ~/Library/Application Support/bornengine/config.toml
  • Windows: %APPDATA%\bornengine\config.toml

It is plain TOML with underscores in the key names:

toml
package_manager = "npm"
engine_version = "0.18.2"

You can edit it by hand. If you save a package manager the CLI does not know, a bad version, or invalid TOML, every command that loads the file fails with a message that names it, and that includes config itself. Fix the value or delete the file.

Environment variables

VariableRead byEffect
BORNENGINE_PATHcreate, new, initThe path of a local engine checkout, used instead of a published engine version.
BORNENGINE_PERRYEvery command that runs PerryThe full path of the Perry executable to use.
BORNENGINE_RELEASES_APIperry installReplaces the GitHub API address that is queried for Perry releases.
CARGO_TARGET_DIRNative builds, cache path, cache warmThe folder for compiled engine code. See Native build cache.
CARGO_BUILD_JOBSNative builds, cache warmThe number of parallel Cargo jobs when you do not pass --jobs.
PERRY_RUNTIME_DIRManaged PerryThe folder with Perry’s runtime libraries. The CLI sets it for a managed copy unless you already did.
PERRY_LLD_LINK and CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKERBuilds on 64-bit WindowsThe linker for Perry and for Cargo. See Build and run.
BORNENGINE_CLI_CACHE_DIRThe npm launcherThe folder where the launcher keeps the downloaded CLI binary.
BLOOM_NO_HOT_RELOADA running development build of your gameSet it to 1 to turn off the file watchers.

Check for a new CLI release

shell
bornengine update

update prints the version you run and asks GitHub for the latest release of the CLI repository. When a newer version exists, it prints the command that installs it: npm install --global @bornengine/cli. When you are current, it says so. If GitHub cannot be reached, or no release exists, it says so and prints the same command. It always exits with 0, and it never changes the installed program.

If you installed the CLI with Cargo, run your cargo install command again instead of the one that update prints. See Installation.

update is about the CLI program. To change the engine version of a project, use bornengine upgrade or the engine commands. See Engine versions.

Next steps

Command reference

Check for CLI updates

Check the release channel without silently replacing the CLI.

bornengine update

Options

  • -v, --verbose (repeatable)

Behavior

Checks for a newer CLI release and prints the installation command. It does not self-update the binary.

Examples

bornengine update

Set a CLI configuration value

Persist a named BornEngine CLI configuration value.

bornengine config set <key> <value>

Options

  • <key> is package-manager or engine-version
  • <value> is pnpm, npm, or yarn for package-manager; latest or an exact stable version for engine-version
  • -v, --verbose (repeatable)

Behavior

Validates the value and writes it to the user configuration file. The values are the defaults for create, new, and init.

Examples

bornengine config set package-manager pnpm

Read a CLI configuration value

Print the current value for one configuration key.

bornengine config get <key>

Options

  • <key> is package-manager or engine-version
  • -v, --verbose (repeatable)

Behavior

Reads one configuration key without changing it.

Examples

bornengine config get package-manager

List CLI configuration

Print the configuration values currently known to the CLI.

bornengine config list

Options

  • -v, --verbose (repeatable)

Behavior

Lists configuration keys and values to make project setup easier to inspect.

Examples

bornengine config list