Configuration

import VersionLabel from '@site/src/components/Docs/VersionLabel';

We support configuration at both the project-level and user-level using a TOML based .prototools file. This file can be used to pin versions of tools, provide tool specific configuration, enable new tools via plugins, define proto settings, and more.

Locations<VersionLabel version="0.41.0" />

proto supports 3 locations in which a .prototools file can exist. These locations are used throughout the command line and proto's own settings.

• local -> ./.prototools, .\.prototools (current directory)
• global -> ~/.proto/.prototools, %USERPROFILE%\.proto\.prototools
• user -> ~/.prototools, %USERPROFILE%\.prototools

Local is a bit of a misnomer as a .prototools file can theoretically exist in any directory, but when reading/writing to a file, local refers to the current working directory.

Where to configure?

With so many locations to store proto configuration, the question of where to store certain configurations become blurred, especially when resolution comes into play. We suggest the following locations:

• Default/fallback versions of tools -> global
• Project specific versions of tools -> local
• Project specific settings -> local
• Shared/developer settings -> user
• Non-project related -> user

Resolution mode<VersionLabel version="0.40.0" />

When a proto command or shim is ran, we must find and load all applicable .prototools files. We then deeply merge all of these configuration files into a final configuration object, with the current directory taking highest precedence.

The order in which to resolve configuration can be defined using the --config-mode (-c) command line option, or the PROTO_CONFIG_MODE environment variable. The following 4 modes are supported:

global

In this mode, proto will only load the ~/.proto/.prototools file. This "global" file acts as configuration at the user-level and allows for fallback settings.

~/.proto/.prototools

local

In this mode, proto will only load the .prototools file in the current directory.

./.prototools

upwards

In this mode, proto will traverse upwards starting from the current directory, and load .prototools within each directory, until we reach the system root or the user directory (~), whichever comes first.

~/Projects/app/.prototools (cwd)
~/Projects/.prototools
~/.prototools

This is the default mode for the activate, install, outdated, and status commands.

upwards-global / all

This mode works exactly like upwards but with the functionality of global as well. The global ~/.proto/.prototools file is appended as the final entry.

~/Projects/app/.prototools (cwd)
~/Projects/.prototools
~/.prototools
~/.proto/.prototools

This is the default mode for all other commands not listed above in upwards.

Environment mode<VersionLabel version="0.29.0" />

We also support environment specific configuration, such as .prototools.production or .prototools.development, when the PROTO_ENV environment variable is set. This is useful for defining environment specific aliases, or tool specific configuration.

These environment aware settings take precedence over the default .prototools file, for the directory it's located in, and are merged in the same way as the default configuration. For example, the lookup order would be the following when PROTO_ENV=production:

~/Projects/.prototools.production
~/Projects/.prototools
~/.prototools.production
~/.prototools
~/.proto/.prototools

The global ~/.proto/.prototools file does not support environment modes.

Pinning versions

proto supports pinning versions of tools on a per-directory basis through our .prototools configuration file. This file takes precedence during version detection and can be created/updated with proto pin.

At its most basic level, you can map tools to specific versions, for the directory the file is located in. A version can either be a fully-qualified version, a partial version, a range or requirement, or an alias.

node = "16.16.0"
npm = "9"
go = "~1.20"
rust = "stable"

Lock proto version<VersionLabel version="0.39.0" />

You can also pin the version of proto that you want all tools to execute with by adding a proto version entry. This approach uses shims and dynamic version detection like other tools.

proto = "0.38.0"

Available settings

[env]<VersionLabel version="0.29.0" />

This setting is a map of environment variables that will be applied to all tools when they are executed, or when proto activate is ran in a shell profile. Variables defined here will not override existing environment variables (either passed on the command line, or inherited from the shell).

[env]
DEBUG = "*"

Additionally, false can be provided as a value, which will remove the environment variable. This is useful for removing inherited shell variables.

[env]
DEBUG = false

Variables also support substitution using the syntax ${VAR_NAME}. When using substitution, variables in the current process and merged [env] can be referenced. Recursive substitution is not supported!

This functionality enables per-directory environment variables!

file<VersionLabel version="0.43.0" />

This is a special field that points to a dotenv file, relative from the current configuration file, that will be loaded into the environment variables mapping. Variables defined in a dotenv file will be loaded before variables manually defined within [env].

This feature utilizes the dotenvy crate for parsing dotfiles.

[env]
file = ".env"

[settings]

auto-install

When enabled, will automatically install a missing version of a tool when proto run is ran, instead of erroring. Defaults to false or PROTO_AUTO_INSTALL.

[settings]
auto-install = true

:::warning

This functionality requires shims (not activation) and will only work after a tool has been installed at least once. This is because the shim executable handles the interception and the shim is created after a tool is installed.

:::

auto-clean

When enabled, will automatically clean up the proto store in the background, by removing unused tools and outdated plugins. Defaults to false or PROTO_AUTO_CLEAN.

[settings]
auto-clean = true

builtin-plugins<VersionLabel version="0.39.0" />

Can be used to customize the built-in plugins within proto. Can disable all built-ins by passing false, or enabling a select few by name. Defaults to true, which enables all.

[settings]
# Disable all
builtin-plugins = false
# Enable some
builtin-plugins = ["node", "bun"]

cache-duration<VersionLabel version="0.50.1" />

The duration in seconds in which to cache downloaded plugins. Defaults to 30 days.

[settings]
cache-duration = 3600

detect-strategy

The strategy to use when detecting versions. Defaults to first-available or PROTO_DETECT_STRATEGY.

• first-available - Will use the first available version that is found. Either from .prototools or a tool specific file (.nvmrc, etc).
• prefer-prototools - Prefer a .prototools version, even if found in a parent directory. If none found, falls back to tool specific file.
• only-prototools - Only use a version defined in .prototools. <VersionLabel version="0.34.0" />

[settings]
detect-strategy = "prefer-prototools"

pin-latest

When defined and a tool is installed with the "latest" alias, will automatically pin the resolved version to the configured location. Defaults to disabled or PROTO_PIN_LATEST.

• global - Pins globally to ~/.proto/.prototools.
• local - Pins locally to ./.prototools in current directory.
• user - Pins to the user's ~/.prototools in their home directory. <VersionLabel version="0.41.0" />

[settings]
pin-latest = "local"

telemetry

When enabled, we collect anonymous usage statistics for tool installs and uninstalls. This helps us prioritize which tools to support, what tools or their versions may be broken, the plugins currently in use, and more. Defaults to true.

[settings]
telemetry = false

The data we track is publicly available and can be found here.

unstable-lockfile<VersionLabel version="0.51.0" />

When enabled, will create a .protolock file relative to this configuration file. The lockfile will record and lock all tools, their versions, and checksums from the configuration file, ensuring consistency across machines, and reliability.

[settings]
unstable-lockfile = true

unstable-registries<VersionLabel version="0.51.0" />

A list of OCI registries to query for plugins by reference. Registries will be queried in the order they are configured. Each registry object supports the following fields:

• registry - The registry host, e.g. ghcr.io.
• namespace - The namespace (or organization) that the plugin belongs to.

[settings]
unstable-registries = [
  { registry: "ghcr.io", namespace: "moonrepo" }
]

url-rewrites<VersionLabel version="0.50.0" />

Provides a mechanism for rewriting most URLs used by proto, such as those used for downloading tools. This setting accepts a map of Rust regular expressions to replacement strings. When a URL is rewritten, all entries in the map are applied in order, and all matches are replaced.

[settings.url-rewrites]
"github.com/(\\w+)/(\\w+)" = "gh-mirror.corp.com/$1/$2"
"mo+n" = "lunar"

The following types of URLs are rewritten:

• Tool download/checksum URLs (even from third-party plugins)
• Plugin download URLs
• Build script URLs
• Archive URLs

The following are not rewritten:

• Git repository URLs
• proto version check/telemetry URLs

[settings.build]<VersionLabel version="0.46.0" />

Can be used to customize the build from source flow.

exclude-packages

Configures a list of packages that should be excluded during installation.

[settings.build]
exclude-packages = ["git", "python3", "libssl-dev"]

install-system-packages

When enabled, will install packages required for building using the system package manager. Defaults to true.

[settings.build]
install-system-packages = false

system-package-manager

Customize the system package manager to use when installing system packages and their dependencies. By default we attempt to detect the package manager to use from the environment.

This setting accepts a map, where the key is the name of the operating system, and the value is the package manager to use. Both the key and value are in kebab-case.

[settings.build.system-package-manager]
windows = "choco"

write-log-file

When a build has completed, write a log file to the current directory. This is always true when a build fails, but false otherwise.

[settings.build]
write-log-file = true

[settings.http]

Can be used to customize the HTTP client used by proto, primarily for requesting files to download, available versions, and more.

allow-invalid-certs

When enabled, will allow invalid certificates instead of failing. This is an escape hatch and should only be used if other settings have failed. Be sure you know what you're doing! Defaults to false.

[settings.http]
allow-invalid-certs = true

proxies

A list of proxy URLs to use for requests. As an alternative, the HTTP_PROXY and HTTPS_PROXY environment variables can be set. URLs that start with http:// will be considered insecure, while https:// will be secure.

[settings.http]
proxies = ["https://internal.proxy", "https://corp.net/proxy"]

secure-proxies<VersionLabel version="0.40.3" />

A list of proxy URLs that will be considered secure, regardless of the HTTP protocol.

[settings.http]
secure-proxies = ["http://internal.proxy", "http://corp.net/proxy"]

root-cert

The path to a root certificate to use for requests. This is useful for overriding the native certificate, or for using a self-signed certificate, especially when in a corporate/internal environment. Supports pem and der files.

[settings.http]
root-cert = "/path/to/root/cert.pem"

[settings.offline]<VersionLabel version="0.41.0" />

Can be used to customize how we detect an internet connection for offline based logic. These settings are useful if you're behind a VPN or corporate proxy.

custom-hosts

A list of custom hosts to ping. Will be appended to our default list of hosts and will be ran last.

[settings.offline]
custom-hosts = ["proxy.corp.domain.com:80"]

override-default-hosts

If our default hosts are blocked or are too slow, you can disable pinging them by setting this option to true. Our default hosts are Google DNS, Cloudflare DNS, and then Google and Mozilla hosts.

This should be used in parallel with custom-hosts.

[settings.offline]
override-default-hosts = true

timeout

The timeout in milliseconds to wait for a ping against a host to resolve. Default timeout is 750ms.

[settings.offline]
timeout = 500

[plugins]

This setting was renamed to [plugins.tools] in v0.52 but exists for backwards compatibility.

Backend specific settings

[plugins.backends]<VersionLabel version="0.52.0" />

Custom backend plugins can be configured with the [plugins.backends] section. Learn more about this syntax.

[plugins.backends]
my-backend = "https://raw.githubusercontent.com/my/backend/master/proto-plugin.toml"

Once configured, you can manage a tool plugin using your custom backend:

$ proto install my-backend:tool-id

[backends.*]<VersionLabel version="0.53.0" />

Backends support custom configuration that will be passed to their WASM plugin, which can be used to control the behavior for all tools managed by the backend. Please refer to the official documentation around backends.

[backends.example]
setting = true

[backends.*.env]<VersionLabel version="0.53.0" />

This setting is a map of environment variables for a specific backend, and will be applied when that backend is executed through a managed tool, or when proto activate is ran in a shell profile. These variables will override those defined in [env]. Refer to [env] for usage examples.

[backends.example.env]
KEY = "value"

file<VersionLabel version="0.53.0" />

Like [env].file, this is a path to a dotenv file, relative from the current configuration file, that will be loaded into the environment variables mapping for this specific backend.

[backends.example.env]
file = "backend/.env"

Tool specific settings

[plugins.tools]<VersionLabel version="0.52.0" />

Custom tool plugins can be configured with the [plugins.tools] section. Learn more about this syntax.

[plugins.tools]
my-tool = "https://raw.githubusercontent.com/my/tool/master/proto-plugin.toml"

Once configured, you can manage a tool plugin:

$ proto install my-tool

[tools.*]

Tools support custom configuration that will be passed to their WASM plugin, which can be used to control the business logic within the plugin. Please refer to the official documentation of each tool (typically on their repository) for a list of available settings.

As an example, let's configure Node.js (using the node identifier).

npm = "bundled" # use bundled npm instead of specific version

[tools.node]
bundled-npm = true

[tools.npm]
shared-globals-dir = true

[tools.*.aliases]

Aliases are custom and unique labels that map to a specific version, and can be configured manually within .prototools, or by calling the proto alias command.

[tools.node.aliases]
work = "18"
oss = "20"

[tools.*.env]<VersionLabel version="0.29.0" />

This setting is a map of environment variables for a specific tool, and will be applied when that tool is executed, or when proto activate is ran in a shell profile. These variables will override those defined in [env]. Refer to [env] for usage examples.

[tools.node.env]
NODE_ENV = "production"

file<VersionLabel version="0.43.0" />

Like [env].file, this is a path to a dotenv file, relative from the current configuration file, that will be loaded into the environment variables mapping for this specific tool.

[tools.node.env]
file = "frontend/.env"

GitHub Action

To streamline GitHub CI workflows, we provide the moonrepo/setup-toolchain action, which can be used to install proto globally, and cache the toolchain found at ~/.proto.

# ...
jobs:
  ci:
    name: 'CI'
    runs-on: 'ubuntu-latest'
    steps:
      - uses: 'actions/checkout@v4'
      - uses: 'moonrepo/setup-toolchain@v0'
        with:
          auto-install: true