From 24954b3d6bdc7f0af7cd12b182dd1c6042b6d416 Mon Sep 17 00:00:00 2001 From: 0x4D5352 <67082011+0x4D5352@users.noreply.github.com> Date: Sat, 31 Jan 2026 10:45:27 -0600 Subject: [PATCH 1/3] fix: add documentation for `attrs` in custom_commands.md --- book/custom_commands.md | 160 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) diff --git a/book/custom_commands.md b/book/custom_commands.md index 2555a39db69..a0eeed6a0f3 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -935,6 +935,166 @@ The comments following the parameters become their description. Only a single-li A Nushell comment that continues on the same line for argument documentation purposes requires a space before the ` #` pound sign. ::: +## Adding Attributes to Custom Commands via `attr` + +As of version 0.103.0, Nushell allows authors of custom commands to enrich their work +with attributes with subcommands of the `attr` builtin, prefixed by the `@` symbol +before the defintion of the command. For those coming from Python, Java, or JavaScript, this +will appear similar to decorators or annotations, but serve a slightly different purpose. + +Let's improve the documentation for the `vip-greet` custom command. The `example` +attribute adds to the output of `help {command}` or `{command} -h`: + +```nu +# Greet guests along with a VIP +# +# Use for birthdays, graduation parties, +# retirements, and any other event which +# celebrates an event # for a particular +# person. +@example "Greet a VIP" {vip-greet "Bob"} --result "And a special welcome to our VIP today, Bob!" +@example "Greet multiple people" {vip-greet "Bob" ["Alice" "Charlie"]} --result $"Hello, Alice!(char newline)Hello, Charlie!(char newline)And a special welcome to our VIP today, Bob!" +def vip-greet [ + vip: string # The special guest + ...names: string # The other guests +] { + for $name in $names { + print $"Hello, ($name)!" + } + + print $"And a special welcome to our VIP today, ($vip)!" +} +``` + +Now, run `help vip-greet` to see the examples added: + +```text +Greet guests along with a VIP + +Use for birthdays, graduation parties, +retirements, and any other event which +celebrates an event # for a particular +person. + +Usage: + > vip-greet ...(names) + +Flags: + -h, --help: Display the help message for this command + +Parameters: + vip : The special guest + ...names : The other guests + +Input/output types: + ╭───┬───────┬────────╮ + │ # │ input │ output │ + ├───┼───────┼────────┤ + │ 0 │ any │ any │ + ╰───┴───────┴────────╯ + +Examples: + Greet a VIP + > vip-greet "Bob" + And a special welcome to our VIP today, Bob! + + Greet multiple people + > vip-greet "Bob" ["Alice" "Charlie"] + Hello, Alice! + Hello, Charlie! + And a special welcome to our VIP today, Bob! +``` + +When maintaining a script, module, plugin, or library written in nu, some custom +commands may end up being replaced by newer versions or removed completely, but +remain available temporarily to give users time to transition away from the older +functionality. + +The `deprecated` attribute raises a warning to the users upon running +the custom command. + +```nu +@deprecated +def greet [ + name: string + --all-caps +] { + let greeting = $"Hello, ($name)!" + if $all_caps { + $greeting | str upcase + } else { + $greeting + } +} +``` + +Run `greet` with a name argument to see the warning: + +```bash +> greet "bob" +Warning: nu::parser::deprecated + + ⚠ Command deprecated. + ╭─[entry #13:1:1] + 1 │ greet "bob" + · ─────┬───── + · ╰── greet is deprecated and will be removed in a future release. + ╰──── + +Hello, bob! +``` +If there is a replacement command, or if there is additional context that would +assist the user when updating their workflows, add text after `@deprecated`. +The `category` attribute assigns the specified label when using `scope commands` +or `help` commands; a `deprecated` category can be useful in these scenarios + +```nu +@deprecated "Use vip-greet as a replacement." +@category "deprecated" +def greet [ + name: string + --all-caps +] { + let greeting = $"Hello, ($name)!" + if $all_caps { + $greeting | str upcase + } else { + $greeting + } +} +``` + +```bash +> greet bob +Warning: nu::parser::deprecated + + ⚠ Command deprecated. + ╭─[entry #15:1:1] + 1 │ greet bob + · ────┬──── + · ╰── greet is deprecated and will be removed in a future release. + ╰──── + help: Use vip-greet as a replacement. + +Hello, bob! + +> help commands | where category == deprecated +╭───────┬──────────┬───────────────┬─────────────────┬────────────────┬───────────────────────────────────────────────────────────────────────────────────────┬───────────────────┬─────────────────┬─────────────╮ +│ # │ name │ category │ command_type │ description │ params │ input_output │ search_terms │ is_const │ +├───────┼──────────┼───────────────┼─────────────────┼────────────────┼───────────────────────────────────────────────────────────────────────────────────────┼───────────────────┼─────────────────┼─────────────┤ +│ 0 │ greet │ deprecated │ custom │ │ ╭───┬────────────┬────────┬──────────┬───────────────────────────────────────────╮ │ [list 0 items] │ │ false │ +│ │ │ │ │ │ │ # │ name │ type │ required │ description │ │ │ │ │ +│ │ │ │ │ │ ├───┼────────────┼────────┼──────────┼───────────────────────────────────────────┤ │ │ │ │ +│ │ │ │ │ │ │ 0 │ name │ string │ true │ │ │ │ │ │ +│ │ │ │ │ │ │ 1 │ --all-caps │ switch │ false │ │ │ │ │ │ +│ │ │ │ │ │ │ 2 │ --help(-h) │ switch │ false │ Display the help message for this command │ │ │ │ │ +│ │ │ │ │ │ ╰───┴────────────┴────────┴──────────┴───────────────────────────────────────────╯ │ │ │ │ +╰───────┴──────────┴───────────────┴─────────────────┴────────────────┴───────────────────────────────────────────────────────────────────────────────────────┴───────────────────┴─────────────────┴─────────────╯ +``` + +To see other attributes available for use within nushell, check the [command reference](/commands/docs/attr.html) +or run `help attr` from the nushell REPL. + ## Changing the Environment in a Custom Command Normally, environment variable definitions and changes are [_scoped_ within a block](./environment.html#scoping). This means that changes to those variables are lost when they go out of scope at the end of the block, including the block of a custom command. From c9c2b3d76c082e70e2efaf02e8582a2da1d1255b Mon Sep 17 00:00:00 2001 From: 0x4D5352 <67082011+0x4D5352@users.noreply.github.com> Date: Sat, 31 Jan 2026 11:06:12 -0600 Subject: [PATCH 2/3] fix: tweak wording and code block formatting --- book/custom_commands.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/book/custom_commands.md b/book/custom_commands.md index a0eeed6a0f3..d487591762f 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -953,7 +953,9 @@ attribute adds to the output of `help {command}` or `{command} -h`: # celebrates an event # for a particular # person. @example "Greet a VIP" {vip-greet "Bob"} --result "And a special welcome to our VIP today, Bob!" -@example "Greet multiple people" {vip-greet "Bob" ["Alice" "Charlie"]} --result $"Hello, Alice!(char newline)Hello, Charlie!(char newline)And a special welcome to our VIP today, Bob!" +@example "Greet multiple people" {vip-greet "Bob" ["Alice" "Charlie"]} --result "Hello, Alice! +Hello, Charlie! +And a special welcome to our VIP today, Bob!" def vip-greet [ vip: string # The special guest ...names: string # The other guests @@ -966,7 +968,7 @@ def vip-greet [ } ``` -Now, run `help vip-greet` to see the examples added: +Now, run `help vip-greet` to see the examples added. ```text Greet guests along with a VIP @@ -1028,7 +1030,7 @@ def greet [ } ``` -Run `greet` with a name argument to see the warning: +Run `greet {name}` to see the warning. ```bash > greet "bob" @@ -1043,10 +1045,12 @@ Warning: nu::parser::deprecated Hello, bob! ``` -If there is a replacement command, or if there is additional context that would + +If there is a replacement command or additional context that would assist the user when updating their workflows, add text after `@deprecated`. + The `category` attribute assigns the specified label when using `scope commands` -or `help` commands; a `deprecated` category can be useful in these scenarios +or `help` commands. ```nu @deprecated "Use vip-greet as a replacement." From 88f92187ee8f2577de9af4941529df254f568038 Mon Sep 17 00:00:00 2001 From: 0x4D5352 <67082011+0x4D5352@users.noreply.github.com> Date: Sat, 31 Jan 2026 11:09:46 -0600 Subject: [PATCH 3/3] fix: correct typo --- book/custom_commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/custom_commands.md b/book/custom_commands.md index d487591762f..47449e63249 100644 --- a/book/custom_commands.md +++ b/book/custom_commands.md @@ -939,7 +939,7 @@ A Nushell comment that continues on the same line for argument documentation pur As of version 0.103.0, Nushell allows authors of custom commands to enrich their work with attributes with subcommands of the `attr` builtin, prefixed by the `@` symbol -before the defintion of the command. For those coming from Python, Java, or JavaScript, this +before the definition of the command. For those coming from Python, Java, or JavaScript, this will appear similar to decorators or annotations, but serve a slightly different purpose. Let's improve the documentation for the `vip-greet` custom command. The `example`