asdf-vm / asdf-vm/asdf

Improve UX for users coming from rbenv (`local` vs `set` confusion)

Open Beginner friendly
#2,258 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
25.6k
Forks
941
Avg merge
9h 24m
Merged PRs (30d)
3

Description

Many developers transitioning from rbenv (and even AI-generated commands)
often try to run:

asdf local ruby 3.x.x

However, asdf uses:

asdf set ruby 3.x.x

This leads to confusion and a poor onboarding experience.

### Describe the proposed solution

1. Improve CLI error message when `local` is used:
Suggest `asdf set` as the correct alternative

2. (Optional) Consider a compatibility alias or soft redirect
This would improve developer experience and reduce friction,
especially for users switching from rbenv or relying on AI tools.

Happy to contribute a PR for this.

### Describe similar `asdf` features and why they are not sufficient

asdf previously supported commands like `asdf local` and `asdf global`,
but newer versions have standardized on `asdf set`.

While `asdf set` is functionally correct and more consistent, it differs
from tools like rbenv that many developers are already familiar with.

As a result, users transitioning from rbenv (and even AI-generated commands)
often attempt to use `asdf local`, which leads to confusion or errors.

Currently, when this happens, the CLI does not provide a helpful suggestion
or guidance toward the correct `asdf set` command.

Therefore, while the functionality exists (`asdf set`), the lack of
user guidance in this scenario makes the experience less intuitive
for new users.

### Describe other workarounds you've considered

Other Workarounds Considered:

1. **Documentation Updates**
- Adding clearer instructions in the README about the difference between `asdf local` and `asdf set`.
- While this helps users who read the docs, many users (especially those coming from rbenv or using AI-generated instructions) may still encounter confusion in real-time CLI usage.

2. **User Aliases**
- Users can manually create shell aliases such as:
```bash
alias asdf-local='asdf set'
```
- This works locally but requires individual setup for each user and is not discoverable for new users or automated scripts.

3. **Shell Completion Scripts**
- Some users may rely on shell completion to guide them.
- However, it doesn’t provide an error message or correction when a mistaken `local` command is typed.

4. **Training or AI Prompts**
- Some users attempt to rely on AI assistants for command guidance.
- Currently, AI tools often suggest the outdated `local` command, which fails without guidance from the CLI.

Conclusion:
- Existing workarounds either require manual setup or do not help users in the moment.
- A CLI-level UX improvement (e.g., suggesting `asdf set` when `local` is used incorrectly) would solve the problem globally without burdening users.

Contributor guide

Open the contributing guide

Research direction

Locate the CLI handling for an unrecognized `local` command and run `asdf local ruby 3.x.x` to observe the current error. Update the guidance so it points users to `asdf set`; treat the compatibility alias as optional unless the project specifies it, and verify the resulting CLI behavior with the relevant tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli, developer-experience
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.