Configuration

1 min

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.

Resolution order

When a proto command or shim is ran, we load the .prototools file in the current directory, and traverse upwards loading .prototools within each directory, until we reach the system root or the user directory (~), whichever comes first. Once complete, we then load the special ~/.proto/.prototools file, which acts as configuration at the user-level and includes fallback settings. This operation may look like the following:

~/Projects/web-app/packages/components/src/.prototools
~/Projects/web-app/packages/components/.prototools
~/Projects/web-app/packages/.prototools
~/Projects/web-app/.prototools
~/Projects/.prototools
~/.prototools
~/.proto/.prototools

We then deeply merge all of these configuration files into a final configuration object, with the current directory taking highest precedence.

Environment modev0.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 semantic version, a partial version, a range or requirement, or an alias.

.prototools

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

Available settings

[env]v0.29.0

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

.prototools

[env]
DEBUG = "*"

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

.prototools

[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!

[settings]

auto-install

When enabled, will automatically installing missing tools when proto run is run, instead of erroring. Defaults to false or PROTO_AUTO_INSTALL.

.prototools

[settings]
auto-install = true

auto-clean

When enabled, will automatically clean up the proto cache when proto use is run. Defaults to false or PROTO_AUTO_CLEAN.

.prototools

[settings]
auto-clean = true

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. v0.34.0

.prototools

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

pin-latest

When defined and a tool is installed with the "latest" version, 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.

.prototools

[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.

.prototools

[settings]
telemetry = false

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

[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.

.prototools

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

proxies

A list of proxy URLs to use for requests.

.prototools

[settings.http]
proxies = ["https://internal.proxy", "https://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.

.prototools

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

[plugins]

Additional plugins can be configured with the [plugins] section. Learn more about this syntax.

.prototools

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

Once configured, you can run a plugin as if it was a built-in tool:

$ proto install my-tool

Tool specific settings

[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).

.prototools

[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.

.prototools

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

[tools.*.env]v0.29.0

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

.prototools

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

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.

.github/workflows/ci.yml

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