rtx-cli 0.1.0

Polyglot runtime manager
rtx-cli-0.1.0 is not a library.
Visit the last successful build: rtx-cli-2023.11.9

rtx

Crates.io rtx

Polyglot runtime manager

Quickstart (macOS)

Install rtx:

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

Hook rtx up to your shell:

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

Install a runtime and set it as the default:

$ 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.:

$ 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:

$ 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

$ brew install jdxcode/tap/rtx

Cargo

$ cargo install rtx-cli

npm

$ npm install -g rtx-cli

GitHub Releases

Download the latest release from GitHub.

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

Ubuntu

TODO

Arch Linux

TODO

Other Shells

Bash

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

Fish

$ 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):

# whether to prompt to install plugins and runtimes if they're not already installed
missing_runtime_behavior = '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.

$ 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>
          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 <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>
          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>
          Shell type to generate environment variables for
          
          [default: fish]
          [possible values: bash, fish, zsh]

  -r, --runtime <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>
          runtime(s) to start
          
          e.g.: nodejs@20 python@3.10

  -c, --command <C>
          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 <RUNTIME>

Arguments:
  <RUNTIME>
          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 <PLUGIN>

Arguments:
  <PLUGIN>
          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] <RUNTIME>...

Arguments:
  <RUNTIME>...
          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 <NAME> [GIT_URL]

Arguments:
  <NAME>
          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 <PLUGIN>

Arguments:
  <PLUGIN>
          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:

$ just test

E2E tests are run with:

$ just e2e