nushell/nana

Experimental GUI version of Nushell

Nushell

A new type of shell.

Table of Contents

• Status
• Learning About Nu
• Installation
• Configuration
• Philosophy
  • Pipelines
  • Opening files
  • Plugins
• Goals
• Officially Supported By
• Contributing
• License

Status

This project has reached a minimum-viable-product level of quality. Many people use it as their daily driver, but it may be unstable for some commands. Nu's design is subject to change as it matures.

Learning About Nu

The Nushell book is the primary source of Nushell documentation. You can find a full list of Nu commands in the book, and we have many examples of using Nu in our cookbook.

We're also active on Discord and Twitter; come and chat with us!

Installation

To quickly install Nu:

# Linux and macOS
brew install nushell
# Windows
winget install nushell

To use Nu in GitHub Action, check setup-nu for more detail.

Detailed installation instructions can be found in the installation chapter of the book. Nu is available via many package managers:

For details about which platforms the Nushell team actively supports, see our platform support policy.

Configuration

The default configurations can be found at sample_config which are the configuration files one gets when they startup Nushell for the first time.

It sets all of the default configuration to run Nushell. From here one can then customize this file for their specific needs.

To see where config.nu is located on your system simply type this command.

$nu.config-path

Please see our book for all of the Nushell documentation.

Philosophy

Nu draws inspiration from projects like PowerShell, functional programming languages, and modern CLI tools. Rather than thinking of files and data as raw streams of text, Nu looks at each input as something with structure. For example, when you list the contents of a directory what you get back is a table of rows, where each row represents an item in that directory. These values can be piped through a series of steps, in a series of commands called a 'pipeline'.

Pipelines

In Unix, it's common to pipe between commands to split up a sophisticated command over multiple steps. Nu takes this a step further and builds heavily on the idea of pipelines. As in the Unix philosophy, Nu allows commands to output to stdout and read from stdin. Additionally, commands can output structured data (you can think of this as a third kind of stream). Commands that work in the pipeline fit into one of three categories:

• Commands that produce a stream (e.g., ls)
• Commands that filter a stream (e.g., where type == "dir")
• Commands that consume the output of the pipeline (e.g., table)

Commands are separated by the pipe symbol (|) to denote a pipeline flowing left to right.

> ls | where type == "dir" | table
╭────┬──────────┬──────┬─────────┬───────────────╮
│ #  │   name   │ type │  size   │   modified    │
├────┼──────────┼──────┼─────────┼───────────────┤
│  0 │ .cargo   │ dir  │     0 B │ 9 minutes ago │
│  1 │ assets   │ dir  │     0 B │ 2 weeks ago   │
│  2 │ crates   │ dir  │ 4.0 KiB │ 2 weeks ago   │
│  3 │ docker   │ dir  │     0 B │ 2 weeks ago   │
│  4 │ docs     │ dir  │     0 B │ 2 weeks ago   │
│  5 │ images   │ dir  │     0 B │ 2 weeks ago   │
│  6 │ pkg_mgrs │ dir  │     0 B │ 2 weeks ago   │
│  7 │ samples  │ dir  │     0 B │ 2 weeks ago   │
│  8 │ src      │ dir  │ 4.0 KiB │ 2 weeks ago   │
│  9 │ target   │ dir  │     0 B │ a day ago     │
│ 10 │ tests    │ dir  │ 4.0 KiB │ 2 weeks ago   │
│ 11 │ wix      │ dir  │     0 B │ 2 weeks ago   │
╰────┴──────────┴──────┴─────────┴───────────────╯

Because most of the time you'll want to see the output of a pipeline, table is assumed. We could have also written the above:

> ls | where type == "dir"

Being able to use the same commands and compose them differently is an important philosophy in Nu. For example, we could use the built-in ps command to get a list of the running processes, using the same where as above.

> ps | where cpu > 0
╭───┬───────┬───────────┬───────┬───────────┬───────────╮
│ # │  pid  │   name    │  cpu  │    mem    │  virtual  │
├───┼───────┼───────────┼───────┼───────────┼───────────┤
│ 0 │  2240 │ Slack.exe │ 16.40 │ 178.3 MiB │ 232.6 MiB │
│ 1 │ 16948 │ Slack.exe │ 16.32 │ 205.0 MiB │ 197.9 MiB │
│ 2 │ 17700 │ nu.exe    │  3.77 │  26.1 MiB │   8.8 MiB │
╰───┴───────┴───────────┴───────┴───────────┴───────────╯

Opening files

Nu can load file and URL contents as raw text or structured data (if it recognizes the format). For example, you can load a .toml file as structured data and explore it:

> open Cargo.toml
╭──────────────────┬────────────────────╮
│ bin              │ [table 1 row]      │
│ dependencies     │ {record 25 fields} │
│ dev-dependencies │ {record 8 fields}  │
│ features         │ {record 10 fields} │
│ package          │ {record 13 fields} │
│ patch            │ {record 1 field}   │
│ profile          │ {record 3 fields}  │
│ target           │ {record 3 fields}  │
│ workspace        │ {record 1 field}   │
╰──────────────────┴────────────────────╯

We can pipe this into a command that gets the contents of one of the columns:

> open Cargo.toml | get package
╭───────────────┬────────────────────────────────────╮
│ authors       │ [list 1 item]                      │
│ default-run   │ nu                                 │
│ description   │ A new type of shell                │
│ documentation │ https://www.nushell.sh/book/       │
│ edition       │ 2018                               │
│ exclude       │ [list 1 item]                      │
│ homepage      │ https://www.nushell.sh             │
│ license       │ MIT                                │
│ metadata      │ {record 1 field}                   │
│ name          │ nu                                 │
│ repository    │ https://github.com/nushell/nushell │
│ rust-version  │ 1.60                               │
│ version       │ 0.72.0                             │
╰───────────────┴────────────────────────────────────╯

And if needed we can drill down further:

> open Cargo.toml | get package.version
0.72.0

Plugins

Nu supports plugins that offer additional functionality to the shell and follow the same structured data model that built-in commands use. There are a few examples in the crates/nu_plugins_* directories.

Plugins are binaries that are available in your path and follow a nu_plugin_* naming convention. These binaries interact with nu via a simple JSON-RPC protocol where the command identifies itself and passes along its configuration, making it available for use. If the plugin is a filter, data streams to it one element at a time, and it can stream data back in return via stdin/stdout. If the plugin is a sink, it is given the full vector of final data and is given free reign over stdin/stdout to use as it pleases.

The awesome-nu repo lists a variety of nu-plugins while the showcase repo shows off informative blog posts that have been written about Nushell along with videos that highlight technical topics that have been presented.

Goals

Nu adheres closely to a set of goals that make up its design philosophy. As features are added, they are checked against these goals.

• First and foremost, Nu is cross-platform. Commands and techniques should work across platforms and Nu has first-class support for Windows, macOS, and Linux.

• Nu ensures compatibility with existing platform-specific executables.

• Nu's workflow and tools should have the usability expected of modern software in 2022 (and beyond).

• Nu views data as either structured or unstructured. It is a structured shell like PowerShell.

• Finally, Nu views data functionally. Rather than using mutation, pipelines act as a means to load, change, and save data without mutable state.

Officially Supported By

Please submit an issue or PR to be added to this list.

• zoxide
• starship
• oh-my-posh
• Couchbase Shell
• virtualenv
• atuin
• clap
• Dorothy
• Direnv

Contributing

See Contributing for details. Thanks to all the people who already contributed!

License

The project is made available under the MIT license. See the LICENSE file for more information.

nana's Issues

wishlist 2 ?

Hey guys ! I just found out about your project and I think it is awesome ! I had posted on several discord servers an idea very similar to nana about 6 month ago so I wanted to share it with you. Maybe it can inspire you ! I know you do it more for macos and windows but personnaly I think it would be awesome to do it for linux. We could be the first to have an awesome 2022 new terminal, easier than before and more accessible to the noobs. Heres the post I did 6 month ago 👍

Hey guys I had an crazy idea, I'm not a developper and I know it would be very hard to do but I say it anyway here :

A terminal emulator who is showing gui things. Not for the old bastard like us that loves the black terminal but for young people that discover linux.
When you enter commands, it will have a scrolling menu (like in excel) that recommands commands, and custom simple commands with html/css output (like ls would be able to show a dolphin like screen)
and if you write it in rust everybody will LOVE you ahahah
I would love to help creating it, I'm not a developper but I can design maybe or idk
Heres a concept image :

Redundant empty cards are added on multiple 'Enter' presses

When submitted input in first card creates a second card as expected:

However, If I again press an Enter from first card it will create an additional third card:

Two empty cards are redundant. Here, we can reuse the second card without creating a new card. Also, we may only create a new card if we are submitting input from the last card.

don't accept/apply command until i hit enter

if i type half a command pipeline, switch windows, then switch back, it has accepted and applied my command line.

Is the project alive? What plans does the core team have regarding the sophisticated terminal emulator?

Thank you for developing such an extraordinary project like nushell.

The main benefit of nushell for me is its structured output and terminal emulator which extends this idea further is a perfect synergy for it.

Are there any official plans on nana development?

Thank you in advance!

JSX based framework?

Not trying to start a flame war but convert_json_obj_to_html_inner would be extremely way more readable, maintainable and simple if you were using any framework with JSX support. How strongly opinionated are you about this? I could easily port whats already implemented, given the current small codebase, and add some UI improvements at the same time!

can't build in windows

I can't build in windows any longer. Seems like it's coming from the tauri-runtime-wry dependency.

   Compiling tauri-runtime v0.3.4
   Compiling tauri-runtime-wry v0.3.5
error[E0061]: this function takes 4 arguments but 3 arguments were supplied
   --> src\run_external.rs:128:44
    |
128 |                     let mut process = self.create_process(&input, true, head)?;
    |                                            ^^^^^^^^^^^^^^ ------  ----  ---- supplied 3 arguments
    |                                            |
    |                                            expected 4 arguments
    |
note: associated function defined here
   --> src\run_external.rs:332:8
    |
332 |     fn create_process(
    |        ^^^^^^^^^^^^^^
333 |         &self,
    |         -----
334 |         input: &PipelineData,
    |         --------------------
335 |         use_cmd: bool,
    |         -------------
336 |         use_external_terminal: bool,
    |         ---------------------------
337 |         span: Span,
    |         ----------

For more information about this error, try `rustc --explain E0061`.
error: could not compile `nana` due to previous error
Terminate batch job (Y/N)? Terminate batch job (Y/N)? y

Opening large file blocks view

Not entirely sure what is the exact issue here, but open large_file.txt blocks rendering, and also slows down the typing experience by quite a bit.

Once the precise issue is determined, it could be fixed by a mix of the following:

• Paginating server responses to client (meaning the server has to store all of the responses)
• Virtualized scrolling on client (possible, another thing to implement)
• React 18's concurrent apis (which are supposed to let you be able to prioritize some tasks as “low-priority” so e.g. typing in an input always remains fast).

ci checks?

Should there be some ci checks we should be running on PRs?

autocapitalize appears to be broken on macos

on macos, the input box where you type want to auto-capitalize at the start of each box. previously i disabled this with @rgwood's advice of autocapitalize='none' and it worked with svelte. now that we're on react, it's not working anymore even though it's enabled.

nana/src/app/Prompt.tsx

Line 95 in 350ec0e

autoCapitalize="none"

i'm not sure if it's maybe in the wrong place or if it needs to be somewhere else. all i know is that the same bad behavior still exists on macos.

Sorting is slow, sometimes

Sorting is unexpectedly slow sometimes and I'm not sure why.

Steps to reproduce

1. ls in a folder with a small number of files (~10)
2. Click on a column header a few times to sort it, reverse sort direction, repeat

Sometimes it sorts instantly, sometimes it takes almost 1s. This is on a fast Windows desktop, in release mode.

It's worth profiling or adding some instrumention to figure out where the slowdown is (Rust? React? The serialization/deserialization that occurs when passing data from the back-end to the front-end?) - it really shouldn't be this slow.

We should publish builds

It's a bit hard for people who aren't experienced with Rust to try Nana out. It would be nice if we could build executables+installers in GitHub Actions and publish them (probably in GitHub releases).

Wishlist

• click on filenames to cd or open them if they are a directory or file (respectively)
• ctrl+click or shift+click to select more than one cell to use as parameters to the next command
• pressing 'up' to get the previous history should put me at the end of the input
• tab-completions based on what we have in Nushell
• once you hit enter, we can "lock in" the input if it was successful and syntax highlight it for you. You can click on it again and edit more.
• ctrl+up and ctrl+down could move between cards
• on the left-hand side we can add bookmarks/quick access to things we want. Like drag over a filename or drag over a pipeline
• we may want to bring back "value shell" and let users not only explore the filesystem but also explore any data source they want