What causes "usage: asdf env " in asdf-vm/asdf?

Pass the tool command as an argument, e.g. `asdf env node` to print the environment asdf would use for node.

usage: asdf env <command>

Error message

usage: asdf env <command>

What it means

asdf's env command prints usage and returns this error when it is invoked without a shimmed command to wrap. envCommand requires a non-empty shimmedCommand argument (the tool command whose environment should be reproduced); without it there is nothing to build an environment for, so the CLI aborts with the usage message.

Source

Thrown at internal/cli/cli.go:513

}

func formatVersions(versions []string) string {
	switch len(versions) {
	case 0:
		return "______"
	case 1:
		return versions[0]
	default:
		return strings.Join(versions, " ")
	}
}

func envCommand(logger *log.Logger, shimmedCommand string, args []string) error {
	command := "env"

	if shimmedCommand == "" {
		logger.Printf("usage: asdf env <command>")
		return fmt.Errorf("usage: asdf env <command>")
	}

	if len(args) >= 2 {
		command = args[1]
	}

	realArgs := []string{}
	if len(args) > 2 {
		realArgs = args[2:]
	}

	conf, err := config.LoadConfig()
	if err != nil {
		logger.Printf("error loading config: %s", err)
		return err
	}

	_, plugin, version, err := getExecutable(logger, conf, shimmedCommand)

View on GitHub (pinned to 074a1722ca)

Solutions

Pass the tool command as an argument, e.g. `asdf env node` to print the environment asdf would use for node.
Run `asdf env --help` or `asdf help` to see required arguments.
In scripts, ensure the shimmed command variable is non-empty before calling `asdf env $CMD`.

Example fix

// before
asdf env
// after
asdf env node

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$1" ]; then echo "usage: asdf env <command>" >&2; exit 1; fi
asdf env "$1"

Try / catch

if ! asdf env "$CMD" 2>err.log; then cat err.log >&2; fi

Prevention

Always pass the shimmed tool command to asdf env
Check `asdf env --help` for argument order
In scripts, assert the command variable is non-empty before invoking

When it happens

Trigger: Running `asdf env` with no arguments, or invoking the env subcommand programmatically with shimmedCommand == "".

Common situations: Typing `asdf env` expecting to dump the current environment instead of a specific tool's; shell scripts calling asdf env without the required positional argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of asdf-vm/asdf@074a1722ca (2026-08-30). Data as JSON: /api/errors/12b0ad4cdf6d05ec. Report an issue: GitHub.