Skip to main content

Configuration

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.

Locationsv0.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 (current directory)
  • global -> ~/.proto/.prototools
  • user -> ~/.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 modev0.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 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 version, a partial version, a range or requirement, or an alias.

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

Lock proto versionv0.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 entry does not support partial versions and must contain a fully-qualified semantic version.

.prototools
proto = "0.38.0"

Locking is currently enforced through proto activate, and when activated, all shims (tools) will be executed with that explicit version of proto. This does not apply to the version of proto globally installed (in some situations), or for binaries linked in ~/.proto/bin.

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

.prototools
[env]
DEBUG = "*"

Additionally, false can be provided as a value, which will remove the environment variable. 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 ran, 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 store in the background, by removing unused tools and outdated plugins. Defaults to false or PROTO_AUTO_CLEAN.

.prototools
[settings]
auto-clean = true

builtin-pluginsv0.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.

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

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.
  • user - Pins to the user's ~/.prototools in their home directory. v0.41.0
.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. As an alternative, the HTTPS_PROXY environment variable can be set.

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

[settings.offline]v0.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.

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

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

.prototools
[settings.offline]
timeout = 500

[plugins]​

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

.prototools
[plugins]
my-tool = "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
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.

.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, or when proto activate is ran in a shell profile. 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