@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mise/references/dev-tools/backends/forgejo-html.md

@@ -0,0 +1,533 @@
+Forgejo Backend
+
+Forgejo Backend [​](#forgejo-backend)
+
+You can install release assets from Codeberg and other Forgejo-compatible instances directly using the `forgejo` backend. It downloads release assets from Forgejo repositories and is ideal for tools that distribute pre-built binaries through Forgejo releases.
+
+By default, the Forgejo backend uses the public Codeberg instance at <https://codeberg.org>. For other Forgejo instances, including self-hosted ones, specify a custom API URL with the `api_url` tool option.
+
+The code for this is inside the mise repository at [`src/backend/github.rs`](https://github.com/jdx/mise/blob/main/src/backend/github.rs).
+
+## Usage [​](#usage)
+
+On Linux, install Forgejo Runner from its own Forgejo instance and check the executable. Its releases publish Linux binaries; choose a project with matching assets if you are installing on another operating system:
+
+sh
+
+```
+mise use 'forgejo:forgejo/runner[api_url=https://code.forgejo.org/api/v1,bin=forgejo-runner]'
+mise exec -- forgejo-runner --version
+```
+
+Quote the complete tool argument so shell globbing does not interpret its square brackets. This writes the following project configuration:
+
+toml
+
+```
+[tools]
+"forgejo:forgejo/runner" = {
+  version = "latest",
+  api_url = "https://code.forgejo.org/api/v1",
+  bin = "forgejo-runner",
+}
+```
+
+Add `-g` to `mise use` for a global tool. This installs the runner executable; registering it with a server and running it as a service are separate steps. For Codeberg repositories, omit `api_url`.
+
+## Authentication [​](#authentication)
+
+For private repositories or higher API limits, mise supports several Forgejo token sources.
+
+### Token priority [​](#token-priority)
+
+mise checks these sources in order and uses the first token found:
+
+1. `MISE_FORGEJO_ENTERPRISE_TOKEN` (for non- `codeberg.org` hosts)
+2. `MISE_FORGEJO_TOKEN`
+3. `FORGEJO_TOKEN`
+4. `credential_command` (if set)
+5. `forgejo_tokens.toml` (per host)
+6. `fj` CLI config ( `keys.json`, if enabled)
+7. `git credential fill` (if `forgejo.use_git_credentials=true`)
+
+### Environment variables [​](#environment-variables)
+
+sh
+
+```
+export MISE_FORGEJO_TOKEN="forgejo-token"
+```
+
+For self-hosted Forgejo instances:
+
+sh
+
+```
+export MISE_FORGEJO_ENTERPRISE_TOKEN="forgejo-enterprise-token"
+```
+
+### Token file (`forgejo_tokens.toml`) [​](#token-file-forgejo-tokens-toml)
+
+toml
+
+```
+# ~/.config/mise/forgejo_tokens.toml
+[tokens."codeberg.org"]
+token = "forgejo-public-token"
+
+[tokens."forgejo.mycompany.com"]
+token = "forgejo-enterprise-token"
+```
+
+### `credential_command` [​](#credential-command)
+
+Set this in your **global** `~/.config/mise/config.toml`. Project configuration cannot set `credential_command`. The command must print only the token to stdout:
+
+toml
+
+```
+[settings.forgejo]
+credential_command = "op read 'op://Private/Forgejo Token/credential'"
+```
+
+mise executes this command with the configured default inline shell. The target hostname is available as `MISE_CREDENTIAL_HOST`, and the provider name (`forgejo`) is available as `MISE_CREDENTIAL_PROVIDER`. For compatibility, recognized sh-compatible shells (`ash`, `bash`, `dash`, `ksh`, `sh`, and `zsh`) also receive the hostname as `$1`/`${1}`.
+
+Planned deprecation
+
+The legacy `$1`/`${1}` hostname argument is deprecated. Use `MISE_CREDENTIAL_HOST` instead. mise will start warning in `2026.11.0`, and `$1` compatibility will be removed in `2027.11.0`.
+
+### `fj` CLI integration [​](#fj-cli-integration)
+
+mise can read tokens from the [`fj` CLI](https://codeberg.org/forgejo-contrib/forgejo-cli) (`keys.json`) as a fallback. It checks:
+
+1. `$XDG_DATA_HOME/forgejo-cli/keys.json` (defaults to `~/.local/share/forgejo-cli/keys.json`)
+2. `~/Library/Application Support/forgejo-cli.forgejo-cli/keys.json` (macOS)
+3. `~/Library/Application Support/Cyborus.forgejo-cli/keys.json` (legacy macOS location)
+
+Disable this fallback with:
+
+toml
+
+```
+[settings.forgejo]
+fj_cli_tokens = false
+```
+
+### `git credential fill` fallback [​](#git-credential-fill-fallback)
+
+As a last resort, mise can query git credential helpers:
+
+toml
+
+```
+[settings.forgejo]
+use_git_credentials = true
+```
+
+This uses `git credential fill` and supports credentials stored by helpers such as macOS Keychain.
+
+### Debugging token resolution [​](#debugging-token-resolution)
+
+Use `mise token forgejo` to see which token mise would use for a given host:
+
+sh
+
+```
+mise token forgejo
+mise token forgejo forgejo.mycompany.com
+```
+
+Token diagnostics are masked by default. `--unmask` prints the actual credential; use it only when you need the secret itself, and keep it out of shared logs.
+
+## Tool Options [​](#tool-options)
+
+Platform-specific download URLs support the same version templates as the [GitHub backend](https://mise.jdx.dev/dev-tools/backends/github.html#platform-specific-urls).
+
+The following [tool-options](https://mise.jdx.dev/dev-tools/#tool-options) are available for the `forgejo` backend—these go in `[tools]` in `mise.toml`.
+
+### Asset Autodetection [​](#asset-autodetection)
+
+When no `asset_pattern` is specified, mise automatically selects the best asset for your platform. It scores assets on:
+
+- **OS compatibility** (linux, macos, windows)
+- **Architecture compatibility** (x64, arm64, x86, arm)
+- **Libc variant** (gnu or musl for Linux, msvc for Windows)
+- **Archive format preference** (tar.gz, zip, etc.)
+- **Build type** (avoids debug/test builds)
+
+For most tools, you can install without specifying a pattern:
+
+sh
+
+```
+mise install forgejo:user/repo
+```
+
+TIP
+
+The autodetection logic is implemented in [`src/backend/asset_matcher.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_matcher.rs), which is shared by the GitHub, GitLab, and Forgejo backends.
+
+### `asset_pattern` [​](#asset-pattern)
+
+Specifies the pattern to match against release asset names. This is useful when there are multiple assets for your OS/arch combination or when you need to override autodetection.
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", asset_pattern = "tool_*_linux_x64.tar.gz" }
+```
+
+### `matching` [​](#matching)
+
+Narrows asset selection to names containing the given substring, **while keeping platform autodetection**. Unlike [`asset_pattern`](https://mise.jdx.dev/dev-tools/backends/forgejo.html#asset-pattern) (which replaces autodetection entirely), `matching` only refines the candidate set — autodetection still chooses the correct OS/arch from the narrowed list, so a single config stays portable across platforms.
+
+This is the option to reach for when a repository ships **multiple binaries as separate per-platform assets** and autodetection can't tell which one you want.
+
+toml
+
+```
+[tools]
+# When a release ships several binaries per platform (e.g. `mytool-cli` and
+# `mytool-server`), matching picks one on every OS/arch without hardcoding a
+# platform-specific asset_pattern.
+"forgejo:user/repo" = { version = "latest", matching = "mytool-cli" }
+```
+
+Tool options can also be passed inline on the command line using `[key=value]` syntax:
+
+sh
+
+```
+mise use "forgejo:user/repo[matching=mytool-cli]"
+```
+
+`matching` is a case-sensitive substring test, so a value that is also a substring of another asset's name (e.g. `matching = "tool"` when both `tool-*` and `tool-extras-*` are published) won't uniquely select your binary. Use [`matching_regex`](https://mise.jdx.dev/dev-tools/backends/forgejo.html#matching-regex) with an anchor when you need a precise match.
+
+If [`asset_pattern`](https://mise.jdx.dev/dev-tools/backends/forgejo.html#asset-pattern) is also set, it takes precedence and `matching`/`matching_regex` are ignored — `asset_pattern` replaces autodetection entirely, so there is no candidate set left for them to narrow. They are ignored silently: when `asset_pattern` is set, a `matching_regex` is never consulted and an invalid one is not reported, since mise does not error on a superseded option.
+
+### `matching_regex` [​](#matching-regex)
+
+Like [`matching`](#matching), but the asset name must match the given regular expression. Use this when a substring isn't selective enough. The match is case-sensitive; use an inline `(?i)` flag for case-insensitive matching.
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", matching_regex = "^mytool-cli-" }
+```
+
+If both `matching` and `matching_regex` are set, an asset must satisfy **both** (logical AND) to remain a candidate.
+
+WARNING
+
+`matching`/`matching_regex` are **not** part of the install path — it is keyed by the tool name (`user/repo`, or a `tool_alias`) and version. To install two binaries from the same release, give each its own [`tool_alias`](https://mise.jdx.dev/dev-tools/backends/github.html#multiple-assets-from-the-same-release) so they get distinct install directories; reusing the same `forgejo:user/repo` string with different `matching` values resolves to the same directory and the second install overwrites the first.
+
+### `version_prefix` [​](#version-prefix)
+
+Specifies a custom version prefix for release tags. By default, mise handles the common `v` prefix (e.g., `v1.0.0`), but some repositories use different prefixes like `release-`, `version-`, or no prefix at all.
+
+When `version_prefix` is configured, mise will:
+
+- Filter available versions with the prefix and strip it
+- Add the prefix when searching for releases
+- Try both prefixed and non-prefixed versions during installation
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", version_prefix = "release-" }
+```
+
+**Examples:**
+
+- With `version_prefix = "release-"`:
+  - User specifies `1.0.0` → mise searches for the `release-1.0.0` tag
+  - Available versions show as `1.0.0` (prefix stripped)
+- With `version_prefix = ""` (empty string):
+  - User specifies `1.0.0` → mise searches for the `1.0.0` tag (no prefix)
+  - Useful for repositories that don't use any prefix
+
+### `prerelease` [​](#prerelease)
+
+By default, releases flagged `prerelease: true` on Forgejo are excluded from `mise ls-remote` and from `latest` resolution. Set `prerelease = true` to include them:
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", prerelease = true }
+```
+
+When set:
+
+- Pre-release tags (e.g. `v1.0.0-rc1`, `v0.1.2-dev.86`) appear in `mise ls-remote`.
+- `latest` resolves to the newest version across stable and pre-releases, rather than taking the Forgejo `/repos/{owner}/{repo}/releases/latest` shortcut.
+- Fuzzy version queries (e.g. `1.2`) match pre-release tags under that prefix.
+
+Draft releases are always excluded.
+
+### Platform-specific Asset Patterns [​](#platform-specific-asset-patterns)
+
+For different asset patterns per platform:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "latest"
+
+[tools."forgejo:user/repo".platforms]
+linux-x64 = { asset_pattern = "tool_*_linux_x64.tar.gz" }
+macos-arm64 = { asset_pattern = "tool_*_macOS_arm64.tar.gz" }
+```
+
+### `checksum` [​](#checksum)
+
+Set an expected digest for a **specific version and artifact**. Replace the placeholder below with the full SHA-256 digest obtained from a trusted source:
+
+toml
+
+```
+[tools."forgejo:owner/repo"]
+version = "1.0.0"
+asset_pattern = "tool-1.0.0-x64.tar.gz"
+checksum = "sha256:REPLACE_WITH_THE_64_HEX_DIGIT_DIGEST"
+```
+
+*Instead of specifying the checksum here, you can use [mise.lock](https://mise.jdx.dev/dev-tools/mise-lock.html) to manage checksums.*
+
+### Platform-specific Checksums [​](#platform-specific-checksums)
+
+Each platform needs its own digest. These values are placeholders; fill them from the publisher before installing, or generate [mise.lock](https://mise.jdx.dev/dev-tools/mise-lock.html).
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "1.0.0"
+
+[tools."forgejo:user/repo".platforms]
+linux-x64 = {
+  asset_pattern = "tool_*_linux_x64.tar.gz",
+  checksum = "sha256:REPLACE_WITH_THE_64_HEX_DIGIT_DIGEST",
+}
+macos-arm64 = {
+  asset_pattern = "tool_*_macOS_arm64.tar.gz",
+  checksum = "sha256:REPLACE_WITH_THE_64_HEX_DIGIT_DIGEST",
+}
+```
+
+### `size` [​](#size)
+
+Optionally check the expected byte count. The number below is illustrative; use the selected artifact's actual size and pin its version. A size check does not authenticate the publisher or replace a checksum:
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "1.0.0", size = "12345678" }
+```
+
+### `strip_components` [​](#strip-components)
+
+Number of directory components to strip when extracting archives:
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", strip_components = 1 }
+```
+
+INFO
+
+When both `strip_components` and `bin_path` are unset, mise automatically applies `strip_components = 1` when the extracted archive contains exactly one directory at the root and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `mytool-14.1.0-x86_64-unknown-linux-musl/mytool`). The autodetection ensures the binary is placed directly in the install path where mise expects it.
+
+### `bin` [​](#bin)
+
+Rename the downloaded binary to a specific name. This is useful when downloading single binaries that have platform-specific names:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "2.29.1"
+bin = "my-tool"  # Rename the downloaded binary to my-tool
+```
+
+INFO
+
+When downloading single binaries (not archives), mise automatically removes OS/arch suffixes from the filename. For example, `docker-compose-linux-x86_64` becomes `docker-compose` automatically. Use the `bin` option only when you need a specific custom name.
+
+### `rename_exe` [​](#rename-exe)
+
+Rename the executable after extraction from an archive. This is useful when the archive contains a binary with a platform-specific name:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "latest"
+asset_pattern = "tool_linux.zip"
+rename_exe = "tool"  # Rename the extracted binary to tool
+```
+
+TIP
+
+Use `rename_exe` for archives whose binary has a different name than you want. Use `bin` for single-binary downloads (non-archives).
+
+### `no_app` [​](#no-app)
+
+Skip macOS .app bundle assets during autodetection and prefer standalone CLI binaries. This is useful when a repository provides both a macOS .app bundle (often an Xcode extension or GUI application) and a standalone command-line tool:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "latest"
+no_app = true
+```
+
+When `no_app = true`:
+
+- Assets containing `.app.` (e.g., `Tool.app.zip`, `Tool.for.Xcode.app.zip`) are penalized during autodetection
+- Standalone archives are preferred
+- The option is mainly useful for macOS asset selection; non-macOS `.app.` assets are already penalized by platform matching
+- Only autodetection is affected; explicit `asset_pattern` values are used as-is
+
+### `bin_path` [​](#bin-path)
+
+Paths are relative to the install directory **after** `strip_components` is applied. Setting `bin_path` disables automatic root stripping. For an archive shaped like `tool-VERSION/bin/tool`, either retain the outer directory and use `bin_path = "tool-/bin"`, or set both `strip_components = 1` and `bin_path = "bin"`.
+
+Specify the directory containing binaries within the extracted archive, or where to place the downloaded file. This supports Tera templating with `{{ version }}` and the `{{ os() }}` / `{{ arch() }}` functions:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "latest"
+strip_components = 0
+bin_path = "tool-{{ version }}/bin" # retain the outer tool-1.0.0 directory
+```
+
+Both functions take keyword arguments that remap the value mise would emit (`linux`, `macos`, `windows` for `os()`; `x64`, `arm64` for `arch()`), for cases where upstream names the directory differently:
+
+toml
+
+```
+[tools."forgejo:user/repo"]
+version = "latest"
+# expands to tool-1.0.0-linux-x86_64/bin
+strip_components = 0
+bin_path = 'tool-{{ version }}-{{ os() }}-{{ arch(x64="x86_64", arm64="aarch64") }}/bin'
+```
+
+TIP
+
+Use a single-quoted TOML string when the template contains double quotes, as above.
+
+There are no bare `{{ os }}` / `{{ arch }}` variables, and no `{{ x86_64_arch }}`-style aliases — `{{ arch(x64="x86_64", arm64="aarch64") }}` is how you get those names.
+
+**Binary path lookup order:**
+
+1. If `bin_path` is specified, use that directory
+2. If `bin_path` is not set, look for a `bin/` directory in the install path
+3. If the install path root contains an executable file, use the install path root
+4. If no `bin/` directory exists, search subdirectories for `bin/` directories
+5. If no `bin/` directories are found, search immediate subdirectories for any executable files. If an executable is found directly within a subdirectory, that subdirectory is treated as a binary path.
+6. If no executables are found, use the root of the extracted directory
+
+### `filter_bins` [​](#filter-bins)
+
+List of binaries to symlink into a filtered `.mise-bins` directory. This is useful when the tool comes with extra binaries that you do not want to expose on PATH.
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", filter_bins = "tool" }
+"forgejo:user/other-repo" = { version = "latest", filter_bins = ["tool", "helper"] }
+```
+
+When enabled:
+
+- A `.mise-bins` subdirectory is created with symlinks only to the specified binaries
+- Other binaries (like `tool-helper` or `tool-server`) are not exposed on PATH
+
+### `api_url` [​](#api-url)
+
+For other Forgejo-compatible or self-hosted instances, specify the API URL. mise uses it to list releases and look up release assets, and may also use it to download assets when browser download URLs are not reachable or when using custom/private instances:
+
+toml
+
+```
+[tools]
+"forgejo:user/repo" = { version = "latest", api_url = "https://forgejo.mycompany.com/api/v1" }
+```
+
+## Self-hosted Forgejo [​](#self-hosted-forgejo)
+
+If you are using a self-hosted Forgejo instance, set the `api_url` tool option and optionally the `MISE_FORGEJO_ENTERPRISE_TOKEN` environment variable for authentication:
+
+sh
+
+```
+export MISE_FORGEJO_ENTERPRISE_TOKEN="your-token"
+```
+
+## Supported Forgejo Syntax [​](#supported-forgejo-syntax)
+
+- **Forgejo shorthand for latest release version:** `forgejo:user/repo`
+- **Forgejo shorthand for specific release version:** `forgejo:user/repo@2.40.1`
+
+## Settings [​](#settings)
+
+### `forgejo.credential_command`[](#forgejo.credential_command)
+
+- Type: `string`
+- Env: `MISE_FORGEJO_CREDENTIAL_COMMAND`
+- Default:
+
+When set, mise executes this command via `sh -c` and reads the token from stdout. The hostname is exposed as `MISE_CREDENTIAL_HOST`, making the command host-aware for self-hosted Forgejo environments. This replaces the `git credential fill` fallback and does not require `forgejo.use_git_credentials` to be enabled.
+
+The command should print a single token to stdout. Trailing whitespace is trimmed.
+
+Example: `op read "op://Private/Forgejo Token/credential"`
+
+### `forgejo.fj_cli_tokens`[](#forgejo.fj_cli_tokens)
+
+- Type: `boolean`
+- Env: `MISE_FORGEJO_FJ_CLI_TOKENS`
+- Default: `true`
+
+When enabled, mise will read tokens from the fj CLI keys file (`~/.local/share/forgejo-cli/keys.json` on Linux, `~/Library/Application Support/forgejo-cli.forgejo-cli/keys.json` on macOS, with the legacy `Cyborus.forgejo-cli` location as a fallback). This is used as a fallback when no `FORGEJO_TOKEN` or `MISE_FORGEJO_TOKEN` environment variable is set.
+
+Set to `false` to disable this behavior.
+
+### `forgejo.use_git_credentials`[](#forgejo.use_git_credentials)
+
+- Type: `boolean`
+- Env: `MISE_FORGEJO_USE_GIT_CREDENTIALS`
+- Default: `false`
+
+When enabled, mise will run `git credential fill` to obtain Forgejo tokens using the credential helpers configured in your `.gitconfig`.
+
+This covers tokens stored in system keyrings (macOS Keychain, Windows Credential Manager), and any other git credential helper.
+
+Used as a last resort — after environment variables, `forgejo_tokens.toml`, and fj CLI tokens are checked. Results are cached per host for the duration of the session.
+
+Set to `true` to enable this behavior.
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/forgejo.md)
+
+Last updated:
+
+Pager
+
+[Previous pagedotnet](https://mise.jdx.dev/dev-tools/backends/dotnet.html)
+
+[Next pagegem](https://mise.jdx.dev/dev-tools/backends/gem.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/backends/gem-html.md

@@ -0,0 +1,77 @@
+gem Backend
+
+gem Backend [​](#gem-backend)
+
+The `gem` backend installs Ruby command-line applications from RubyGems into separate tool directories. Keep application gems in your project's `Gemfile` and install them with Bundler. The code for this is inside of the mise repository at [`./src/backend/gem.rs`](https://github.com/jdx/mise/blob/main/src/backend/gem.rs).
+
+## Dependencies [​](#dependencies)
+
+This backend needs Ruby and its `gem` command. Gems with native extensions also need the compiler and libraries required by that gem.
+
+## Usage [​](#usage)
+
+Declare Ruby and RuboCop in the same project:
+
+sh
+
+```
+mise use ruby@3.4 gem:rubocop
+mise exec -- rubocop --version
+```
+
+This writes both entries to `mise.toml`. Add `-g` for global configuration.
+
+toml
+
+```
+[tools]
+ruby = "3.4"
+"gem:rubocop" = "latest"
+```
+
+mise's wrappers set `GEM_HOME` for the selected tool. A RuboCop configuration that uses project-specific plugins may be better run with `bundle exec rubocop` from a Gemfile that declares those plugins.
+
+## Ruby upgrades [​](#ruby-upgrades)
+
+If the Ruby version used by a gem package changes (whether managed by mise or the system), you may need to reinstall the gem. This can be done with:
+
+sh
+
+```
+mise install -f gem:rubocop
+```
+
+Reinstall under the Ruby version you intend to use. On Unix, mise-managed Ruby shebangs follow a minor-version path so patch upgrades can keep working; moving to another minor version or changing native-extension compatibility can still require a reinstall.
+
+## Settings [​](#settings)
+
+Set these with `mise settings set [VARIABLE]=[VALUE]` or by setting the environment variable listed.
+
+No settings available.
+
+## Tool Options [​](#tool-options)
+
+The following [tool-options](https://mise.jdx.dev/dev-tools/#tool-options) are available for the `gem` backend—these go in `[tools]` in `mise.toml`.
+
+### `install_env` [​](#install-env)
+
+Set environment variables for the `gem install` command. For gems that build native extensions, `MAKEFLAGS` controls parallel make jobs:
+
+toml
+
+```
+[tools]
+"gem:rubocop" = { version = "latest", install_env = { MAKEFLAGS = "-j4" } }
+```
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/gem.md)
+
+Last updated:
+
+Pager
+
+[Previous pageforgejo](https://mise.jdx.dev/dev-tools/backends/forgejo.html)
+
+[Next pagegithub](https://mise.jdx.dev/dev-tools/backends/github.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/backends/gem.md

@@ -0,0 +1,77 @@
+gem Backend
+
+gem Backend [​](#gem-backend)
+
+The `gem` backend installs Ruby command-line applications from RubyGems into separate tool directories. Keep application gems in your project's `Gemfile` and install them with Bundler. The code for this is inside of the mise repository at [`./src/backend/gem.rs`](https://github.com/jdx/mise/blob/main/src/backend/gem.rs).
+
+## Dependencies [​](#dependencies)
+
+This backend needs Ruby and its `gem` command. Gems with native extensions also need the compiler and libraries required by that gem.
+
+## Usage [​](#usage)
+
+Declare Ruby and RuboCop in the same project:
+
+sh
+
+```
+mise use ruby@3.4 gem:rubocop
+mise exec -- rubocop --version
+```
+
+This writes both entries to `mise.toml`. Add `-g` for global configuration.
+
+toml
+
+```
+[tools]
+ruby = "3.4"
+"gem:rubocop" = "latest"
+```
+
+mise's wrappers set `GEM_HOME` for the selected tool. A RuboCop configuration that uses project-specific plugins may be better run with `bundle exec rubocop` from a Gemfile that declares those plugins.
+
+## Ruby upgrades [​](#ruby-upgrades)
+
+If the Ruby version used by a gem package changes (whether managed by mise or the system), you may need to reinstall the gem. This can be done with:
+
+sh
+
+```
+mise install -f gem:rubocop
+```
+
+Reinstall under the Ruby version you intend to use. On Unix, mise-managed Ruby shebangs follow a minor-version path so patch upgrades can keep working; moving to another minor version or changing native-extension compatibility can still require a reinstall.
+
+## Settings [​](#settings)
+
+Set these with `mise settings set [VARIABLE]=[VALUE]` or by setting the environment variable listed.
+
+No settings available.
+
+## Tool Options [​](#tool-options)
+
+The following [tool-options](https://mise.jdx.dev/dev-tools/#tool-options) are available for the `gem` backend—these go in `[tools]` in `mise.toml`.
+
+### `install_env` [​](#install-env)
+
+Set environment variables for the `gem install` command. For gems that build native extensions, `MAKEFLAGS` controls parallel make jobs:
+
+toml
+
+```
+[tools]
+"gem:rubocop" = { version = "latest", install_env = { MAKEFLAGS = "-j4" } }
+```
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/gem.md)
+
+Last updated:
+
+Pager
+
+[Previous pageforgejo](https://mise.jdx.dev/dev-tools/backends/forgejo.html)
+
+[Next pagegithub](https://mise.jdx.dev/dev-tools/backends/github.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)