rtx

Polyglot runtime manager

Quickstart (macOS)

Install rtx:

sh-session $ brew install jdxcode/tap/rtx $ rtx --version rtx 0.1.0

Hook rtx up to your shell:

sh-session $ echo 'source "$(rtx activate -s zsh)"' >> ~/.zshrc

Install a runtime and set it as the default:

sh-session $ rtx install nodejs@18 $ rtx global nodejs@18 $ node -v v18.10.9

Note
Note: rtx install is optional, rtx global will prompt to install the runtime if it's not already installed. This is configurable in ~/.rtx/config.toml.

About

rtx is a tool for managing runtime versions. For example, use this to install a particular version of node and ruby for a project. Using rtx activate, you can also have your shell automatically switch to the correct node and ruby versions when you cd into the project's directory.

asdf

It is inspired by asdf and uses asdf's plugin ecosystem under the hood. However it is much faster than asdf with a more friendly user experience.

Some commands are the same in asdf as they are in rtx and some are different. Everything that's possible in asdf should be possible in rtx but may use slighly different syntax. rtx has more forgiving commands, such as using fuzzy-matching, e.g.: rtx install nodejs@18. While in asdf you can run asdf install nodejs latest:18, you can't use latest:18 in a .tool-versions file or many other places. In rtx you can use fuzzy-matching everywhere.

asdf requires several steps to install a new runtime if the plugin isn't installed, e.g.:

sh-session $ asdf plugin add nodejs $ asdf install nodejs latest:18 $ asdf local nodejs latest:18

In rtx this can all be done in a single step to set the local runtime version. If the plugin and/or runtime needs to be installed it will prompt:

sh-session $ asdf local nodejs@18

I've found asdf to be particularly rigid and difficult to learn. rtx makes heavy use of aliases so you don't need to remember if it's rtx plugin add nodejs or rtx plugin install nodejs.

How it works

rtx installs as a shell extension (e.g. rtx activate -s zsh) that sets the PATH and other environment variables to point to the correct runtime versions. When you cd into a directory containing a .tool-versions file, rtx will automatically activate the correct versions.

Unlike asdf which uses shim files to dynamically locate runtimes when they're called, rtx modifies $PATH ahead of time so the runtimes are called directly. This is not only faster since it avoids a hefty overhead, but it also makes it so commands like which node work as expected. This also means there isn't any need to run asdf reshim after installing new runtime binaries.

Common example commands

rtx install nodejs@20.0.0          Install a specific version number
rtx install nodejs@20.0            Install a fuzzy version number
rtx local nodejs@20                Use node-20.x in current project
rtx global nodejs@20               Use node-20.x as default

rtx install nodejs                 Install the latest available version
rtx local nodejs                   Use latest node in current directory
rtx global system                  Use system node as default

rtx exec nodejs@20 -- node app.js  Run `node app.js` with the PATH pointing to node-20.x

Installation options

Warning
Warning: Regardless of the installation method, when uninstalling rtx, remove $RTX_DIR folder (usually ~/.rtx) to fully clean up.

Homebrew

sh-session $ brew install jdxcode/tap/rtx

Cargo

sh-session $ cargo install rtx-cli

npm

sh-session $ npm install -g rtx-cli

GitHub Releases

Download the latest release from GitHub.

sh-session $ curl https://github.com/jdxcode/rtx/releases/rtx-latest-macos-arm64.tar.xz | tar -xJ

Ubuntu

sh-session TODO

Arch Linux

sh-session TODO

Other Shells

Bash

sh-session $ echo 'source "$(rtx activate -s bash)"' >> ~/.bashrc

Fish

sh-session $ rtx activate -s fish | source

Configuration

.tool-versions

The .tool-versions file is used to specify the runtime versions for a project. An example of this is:

nodejs 20.0.0 # comments are allowed ruby 3.0.0

Create .tool-versions files manually, or use rtx local to create them automatically.

Global config: ~/.rtx/config.toml

rtx can be configured in ~/.rtx/config.toml. The following options are available (defaults shown):

```toml

whether to prompt to install plugins and runtimes if they're not already installed

missingruntimebehavior = 'prompt' # 'ignore', 'warn', 'prompt', 'autoinstall' ```

rtx can also be configured via envirmoment variables. The following options are available:

RTX_MISSING_RUNTIME_BEHAVIOR

This is the same as the missing_runtime_behavior config option in ~/.rtx/config.toml.

RTX_DIR

This is the directory where rtx stores its data. The default is ~/.rtx.

sh-session $ RTX_MISSING_RUNTIME_BEHAVIOR=ignore rtx install nodejs@20 $ RTX_NODEJS_VERSION=20 rtx exec -- node --version

RTX_CONFIG_FILE

This is the path to the config file. The default is ~/.rtx/config.toml.

RTX_DEFAULT_TOOL_VERSIONS_FILENAME

Set to something other than ".tool-versions" to have rtx look for configuration with alternate names.

RTX_${PLUGIN}_VERSION

Set the version for a runtime. For example, RTX_NODEJS_VERSION=20 will use nodejs@20.x regardless of what is set in .tool-versions.

Plugins

rtx uses asdf's plugin ecosystem under the hood. See https://github.com/asdf-vm/asdf-plugins for a list.

FAQs

I don't want to put a .tool-versions file into my project since git shows it as an untracked file.

You can make git ignore these files in 3 different ways:

• Adding .tool-versions to project's .gitignore file. This has the downside that you need to commit the change to the ignore file.
• Adding .tool-versions to project's .git/info/exclude. This file is local to your project so there is no need to commit it.
• Adding .tool-versions to global gitignore (core.excludesFile). This will cause git to ignore .tool-versions files in all projects. You can explicitly add one to a project if needed with git add --force .tool-versions.

How do I create my own plugin?

Windows support?

This is unlikely to ever happen since this leverages the vast ecosystem of asdf plugins which are built on Bash scripts. At some point it may be worth exploring an alternate plugin format that would be Windows compatible.

Commands

rtx activate

``` Enables rtx to automatically modify runtimes when changing directory

This should go into your shell's rc file. (e.g. ~/.bashrc)

Usage: activate [OPTIONS]

Options: -s, --shell Shell type to generate script for

      e.g.: bash, zsh, fish

      [possible values: bash, fish, zsh]

-h, --help Print help (see a summary with '-h')

Examples: $ eval "$(rtx activate -s bash)" $ eval "$(rtx activate -s zsh)" $ rtx activate -s fish | source

```

rtx current

``` get the latest runtime version available for install

Usage: current [OPTIONS]

Options: -r, --runtime plugin and version to fetch

      e.g.: ruby, nodejs@20

-h, --help Print help (see a summary with '-h')

Examples: $ rtx latest nodejs 20.0.0

$ rtx latest nodejs@18 18.20.1

```

rtx deactivate

``` disable rtx for current shell session

This can be used to temporarily disable rtx from automatically modifying $PATH.

Usage: deactivate [OPTIONS]

Options: -s, --shell shell type to generate the script for

      e.g.: bash, zsh, fish

      [possible values: bash, fish, zsh]

-h, --help Print help (see a summary with '-h')

Examples: $ eval "$(rtx deactivate -s bash)" $ eval "$(rtx deactivate -s zsh)" $ rtx deactivate -s fish | source

```

rtx env

``` exports environment variables to use rtx in current directory

Use this to modify a single shell session to have rtx enabled. rtx activate will do this automatically. Use this if you don't want to permanently install rtx.

Usage: env [OPTIONS]

Options: -s, --shell Shell type to generate environment variables for

      [default: fish]
      [possible values: bash, fish, zsh]

-r, --runtime runtime version to use

-h, --help Print help (see a summary with '-h')

Examples: $ eval "$(rtx env -s bash)" $ eval "$(rtx env -s zsh)" $ rtx env -s fish | source

```

rtx exec

``` execute a command with runtime(s) set

use this to avoid modifying the shell session or to run ad-hoc commands with alternate runtimes set.

This will default the runtimes to the same .tool-version config in other commands.

Usage: exec [OPTIONS] [COMMAND]...

Arguments: [COMMAND]... the command string to execute (same as --command)

Options: -r, --runtime runtime(s) to start

      e.g.: nodejs@20 python@3.10

-c, --command the command string to execute

-h, --help Print help (see a summary with '-h')

Examples: rtx exec nodejs@20 -- node ./app.js rtx exec --runtime nodejs@20 -- node ./app.js

Specify command as a string: rtx exec nodejs@20 python@3.11 --command "node -v && python -V"

```

rtx install

``` install a runtime

Usage: install [RUNTIME]...

Arguments: [RUNTIME]... the plugin+version to install

      e.g.: nodejs@18

Options: -h, --help Print help (see a summary with '-h')

Examples: $ rtx install nodejs@18.0.0 # install specific nodejs version $ rtx install nodejs@18 # install fuzzy nodejs version $ rtx install nodejs # install latest nodejs version—or what is specified in .tool-versions $ rtx install # installs all runtimes specified in .tool-versions

```

rtx latest

``` get the latest runtime version of a plugin's runtimes

Usage: latest

Arguments: Runtime to get the latest version of

Options: -h, --help Print help (see a summary with '-h')

Examples: $ rtx latest nodejs@18 # get the latest version of nodejs 18 18.0.0

$ rtx latest nodejs # get the latest version of nodejs 20.0.0

```

rtx list

``` list installed runtime versions

Usage: list [PLUGIN]

Arguments: [PLUGIN] The tuple of the plugin to filter by (e.g.: nodejs)

Options: -h, --help Print help (see a summary with '-h')

Examples: $ rtx list -> nodejs 20.0.0 (set by ~/src/myapp/.rtxrc) -> python 3.11.0 (set by ~/.rtxrc)

```

rtx list-remote

``` list runtime versions available for install

Usage: list-remote

Arguments: Plugin

Options: -h, --help Print help (see a summary with '-h')

Examples: $ rtx list-remote nodejs 18.0.0 20.0.0

```

rtx local

``` sets .tool-versions to include a specific runtime

use this to set the runtime version when within a directory use rtx global to set a runtime version globally

Usage: local [OPTIONS] ...

Arguments: ... runtimes

      e.g.: nodejs@20

Options: -p, --parent recurse up to find a .tool-versions file rather than using the current directory only by default this command will only set the runtime in the current directory ("$PWD/.tool-versions")

-h, --help Print help (see a summary with '-h')

Examples: # set the current version of nodejs to 20.x for the current directory $ rtx local -r nodejs@20

# set nodejs to 20.x for the current project (recurses to find .tool-versions) $ rtx local -p -r nodejs@20

```

rtx plugins install

``` install a plugin

note that rtx automatically can install plugins when you install a runtime e.g.: rtx install nodejs@18 will autoinstall the nodejs plugin

This behavior can be modified in ~/.rtx/config.toml

Usage: install [GIT_URL]

Arguments: The name of the plugin to install

      e.g.: nodejs

[GIT_URL] The git url of the plugin

      e.g.: https://github.com/asdf-vm/asdf-nodejs.git

Options: -h, --help Print help (see a summary with '-h')

EXAMPLES: $ rtx install nodejs # install the nodejs plugin using the shorthand repo: # https://github.com/asdf-vm/asdf-plugins

$ rtx install nodejs https://github.com/asdf-vm/asdf-nodejs.git
                      # install the nodejs plugin using the git url

$ rtx install https://github.com/asdf-vm/asdf-nodejs.git
                      # install the nodejs plugin using the git url only
                      # (nodejs is inferred from the url)

```

rtx plugins list

``` List installed plugins Can also show remotely available plugins to install.

Examples: $ rtx plugins list $ rtx plugins list --all

Usage: list [OPTIONS]

Options: -a, --all list all available remote plugins

      same as `rtx plugins ls-remote`

-u, --urls show the git url for each plugin

      e.g.: https://github.com/asdf-vm/asdf-nodejs.git

-h, --help Print help (see a summary with '-h')

```

rtx plugins list-remote

``` List all available remote plugins

These are fetched from https://github.com/asdf-vm/asdf-plugins

Examples: $ rtx plugins ls-remote

Usage: list-remote [OPTIONS]

Options: -u, --urls show the git url for each plugin

      e.g.: https://github.com/asdf-vm/asdf-nodejs.git

-h, --help Print help (see a summary with '-h')

```

rtx plugins uninstall

``` removes a plugin

Usage: uninstall

Arguments: plugin to remove

Options: -h, --help Print help (see a summary with '-h')

Examples: $ rtx uninstall nodejs

```

rtx plugins update

``` updates a plugin to the latest version

note: this updates the plugin itself, not the runtime versions

Usage: update [PLUGIN]

Arguments: [PLUGIN] plugin to update

Options: -h, --help Print help (see a summary with '-h')

Examples: rtx plugins update # update all plugins rtx plugins update nodejs # update only nodejs

```

rtx version

``` Show rtx version

Usage: version

Options: -h, --help Print help

```

Development

Run tests with just:

sh-session $ just test

E2E tests are run with:

sh-session $ just e2e