[RFC] Terminal UI

[anthonyshew]

Thank you for feedback

The terminal UI has been released in 2.0! 🥳

We appreciate everyone who participated and look forward to continuing to work with the Turbo community going forward.

If you believe you've found a bug, please report it in Issues.

If you have an idea or enhancement you'd like to suggest, please open a new Discussion.

---

RFC

In Turborepo 1.13, we're releasing a new terminal UI that changes the way you experience your Turborepo locally.

Because this new experience is quite different from the previous one, we're creating this RFC to collect community feedback.

What is the new terminal UI?

The new UI allows you to:

• Toggle through the logs of each of your tasks with your arrow keys, making them easier to follow and read
• Interact with your persistent tasks by entering and exiting the task’s shell, giving you the ability to re-run unit tests, for example

v1


new-ui-2.mp4

How do I enable the new terminal UI?

The new UI can be enabled two ways:

• Use the --experimental-ui flag when you run your turbo commands
• Add the experimentalUI key to your turbo.json

{
  "experimentalUI": true
}

How do I make a task interactive?

Set the interactive key to true on any task that you'd like to make interactive. Note that any interactive task must also have the persistent key set to true, as well.

{
  "pipeline": {
    "test:dev": {
      "interactive": true,
      "persistent": true
    }
  }
}

How do I give feedback?

We're excited to hear from you! Please comment below with any feedback you have, whether it be an issue or other general feedback. The core team will triage comments here and move issues to the Issues board as needed.

[weyert]

Thanks for the amazing work! It's looking great so far.

I have some feedback:

• If you use Warp.app it doesn't show the top bar as shown in the screenshot
• How do I scroll in task window? E.g. sometimes you might want scroll back
• I think it would be nice to be able to ignore switching between cached tasks with suppressed logs (e.g. build tasks) see also: Allow to ignore cache hit or non-persistent tasks from the Turbo UI #7779

[arlyon]

There are APIs for mouse scrolling which would be very cool also

[weyert]

Cool, yeah, think scrolling would be nice.

Now while I thought of using a virtual term myself to get this all going I have to say I am impressed you were able to achieve it :)
Looks like Rust got some nice crates related to it. Super cool. And I didn't know terminal supported mouse scrolling.

Does making your window taller have the top bar show up? Was just messing around with a few things and noticed this myself.

Ah yeah, looks like making it a lot taller seems to work. Not sure if it is because it is trying to display all packages, which would be roughly ~50 packages (36 ^build tasks and then 10 dev persistent tasks)

[chris-olszewski]

First pass at scrolling: #7807
I'll can see how capturing mouse events works via crossterm later today as a scroll wheel would be very intuitive.
PR has been updated so mouse scroll wheel now work.

Ctrl-UpArrow, Ctrl-DownArrow?

Ctrl-Up/Ctrl-Down aren't good candidates for this since macOS has those as default keybinds.

[anthonyshew]

Ah, heck, duh. I'd still wonder about something more intuitive for the non-Vimmers of the world.

[rafaeltab]

Any chance we could be able to customize the controls somehow? Maybe a $HOME/.config/turbo/... folder where we could add configuration for the current user.

I would love for there to be a programmable api that I could integrate into neovim myself. Perhaps an option to start a socket server, and run a command (Run the socket server and then pass the local address to the command as an argument). This could also be integrated with vscode with an extension.

If that is not an option I think actually the most optimal scenario would be a combination of the three.

• Vim motions for vimmers like myself, I'd prefer these keybinds to be as extensive as possible (g, G, <C-d>, <C-u>, w, W, etc).
• Arrows for the people who are not familiar with vim
• Scroll for people who don't like keyboard

[devjiwonchoi]

Context

I am using turbo in a single Next.js app to benefit from remote cache.

Problem

1. The build log for next build gets cleared. - Is this intended?
2. I need to manually enlarge the terminal size to view the rest of the logs.

Info

Turbo: 1.13.0-canary.4

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.1.0: Mon Oct  9 21:32:11 PDT 2023; root:xnu-10002.41.9~7/RELEASE_ARM64_T6030
  Available memory (MB): 18432
  Available CPU cores: 11
Binaries:
  Node: 18.17.0
  npm: 9.6.7
  Yarn: N/A
  pnpm: 8.15.4
Relevant Packages:
  next: 14.2.0-canary.34 // Latest available version is detected (14.2.0-canary.34).
  eslint-config-next: 14.2.0-canary.28
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.4.2
Next.js Config:
  output: N/A

Screen.Recording.2024-03-22.at.1.29.19.AM.mov

[chris-olszewski]

The build log for next build gets cleared. - Is this intended?

This is a known behavior at the moment. The UI needs to be properly integrated with --output-logs to have the correct behavior when it comes to persisting logs.

I need to manually enlarge the terminal size to view the rest of the logs.

The layout of the UI is currently hard coded and not designed well for small terminals. I'm working on making it more reactive to the terminal size.

[devjiwonchoi]

Thank you for answering!

[anthonyshew]

@devjiwonchoi We just put up a newer design on the latest canary. Would love for you to give it a try!

[devjiwonchoi]

Looks awesome!!

[weyert]

I like the newer design only wish the left column would take half the space. Maybe limit it to the maximum width of the package? Now it's 50/50

[imranbarbhuiya]

in my windows vscode terminal, pressing the arrow key moves 2 packages at a time, and pressing enter does nothing

turbo.json.-.Sofi-Site.-.Visual.Studio.Code.-.Insiders.2024-03-21.22-39-35.mp4

also pressing ctrl+c keeps the logs in the same place

[chris-olszewski]

Promoted this to an issue: #7808
The double key press issue should be addressed by #7809
Looking into why the terminal clear wouldn't trigger.

[Talent30]

How would it look like in CI/CD?

[chris-olszewski]

The UI is only usable in an interactive terminal so it is unusable in CI/CD. (Unless you do extra work to open up a psuedoterminal, but that wouldn't be recommended)

[imranbarbhuiya]

Once it becomes stable, will it replace the old UI? Although this UI looks good, most of the time I'll want to see all the logs at the same time instead of manually changing the package so keeping the existing UI and introducing a flag like --interactive to opt-in for the new UI will be great

[chris-olszewski]

Due to the fact that we'll always need to support running in non-interactive terminals, the old UI will remain. (Could either be flagged on or forced via something like turbo build | cat)

That being said, I'd love to try to address any shortcomings you have with the UI.

I'll want to see all the logs at the same time instead of manually changing the package

A few things we've discussed:

• Logs will be persisted to the terminal (space above the UI) on completion. Similar to how --log-order=grouped works now.
• Automatically jump to logs of a running task e.g. once ui#build finishes, jump to web#build. User can still use arrow keys to inspect finished tasks.

We're also open to any suggestions that would make the new UI an acceptable default.

[weyert]

Automatically jump to logs of a running task e.g. once ui#build finishes, jump to web#build. User can still use arrow keys to inspect finished tasks.

I am not sure how this work? What happens when you need to build 30+ packages before web#build? Would cause a lot of jumping around, right?

[anthonyshew]

@weyert Just want to let you know. We tried it out and it didn't work out to be the experience we thought it was going to be. We all were excited to see it and then, once we saw it, quickly agreed it was definitely not right. 😄

[steveluscher]

When an error is encountered, would you consider leaving the experimental UI onscreen with the errored task made active? I was surprised to see the experimental UI close when there was an error.

[chris-olszewski]

Can you try 1.13.1-canary.0 which contains #7805 and see if that's the behavior you'd want?

[steveluscher]

Yeah, 100%. Thanks!

[anthonyshew]

We ironed out a few more things on the most recent canary, as well, including a redesign. Would love for you to take another look!

[dBianchii]

I have two feedbacks:

1. I didn't see any reason to use the new experimental UI on linter/formatter and typecheck tasks. I tried using it, but it was very hard to see what was failing, and it immediatelly kicked me out of the UI and I wasn't able to see where the errors were happening. I guess this UI is more useful for long running tasks like running servers with dev scripts or drizzle/prisma studio.

2. I can't Cntrl+click links that appear in the terminal:
   

[chris-olszewski]

I tried using it, but it was very hard to see what was failing

Can you try the latest canary? It now persists all task logs to the terminal so after turbo exits you can see failures/outputs.

I can't Cntrl+click links that appear in the terminal

Looking into what it'll take to support this.

[haydnhkim]

I think it should take the opposite approach and consider providing a simple terminal ui option.

• inherited stdin option
• option to turn off task names on stdout and output to raw (mixed log is fine)

The new terminal UI feels like it limits a lot of the functionality of the original terminal app.
It also feels less responsive.
I would like to be able to view and copy the output logs raw.

[chris-olszewski]

inherited stdin option

This is deemed as too dangerous and unintuitive to support. Dangerous as stdin is an uncaptured input so users could poison the shared cache. Unintuitive because inheriting stdin means users wouldn't be able to send specific input to specific tasks, just forward input to all tasks that inherit stdin.

option to turn off task names on stdout and output to raw (mixed log is fine)

This is achievable right now with the --log-prefix=none flag

It also feels less responsive.

Can you elaborate on this? What part of the UI or invocation of turbo feels less responsive? Is it task output?

[haydnhkim]

@chris-olszewski
Thanks for pointing me to the --log-prefix setting.

stdin forwarding is primarily needed when requesting specific functionality from a running process in the dev pipeline.
For example)
#1235
#7332

I want to pass a keyword like rs or o regardless of the cache.
How about setting certain in-pipeline options differently from the experimentalUI options?

"pipeline": {
  "dev": {
    "stdin": true,
  }
}

Additionally, Maybe it would be nice to allow experimentalUI options to be set in the pipeline as well.
Perhaps there is a complexity to making it applicable only to the top-level pipeline.

---

I feel that when running with experimentalUI, the speed at which text is entered and logs are output is slower than in normal mode.
This is probably due to the fact that I'm using an Intel Mac.
I'm using Warp.app and it doesn't seem to expose all of the UI as weyert mentioned.

[juliusmarminge]

When everything is done, it'd be nice to be able to look at the output before "exiting". Right now it just exits as soon as the last task is done so you can't see any of the outputs.

[anthonyshew]

Logs should be being persisted to your terminal with latest releases!

[yamcodes]

The new UI looks great, but it feels like you need to reveal too much of the terminal for more than one task to be visible in the switcher. In other words, the terminal height needs to be set too high for the switcher to show multiple tasks. Normally I would have my terminal reveal maybe 10-15 lines, but to see multiple tasks I need 30-35.

What would be nice to have is a way to resize the interactive portion of the experimental UI so that we can select our own sweetspot between interactive terminal space and task switcher height.

[AndreaPontrandolfo]

Yes agree, the fact that the buffer size doesn't auto-rescale is unbearable

[anthonyshew]

Heard! There's a new design that should meet this need on the most recent canary. Would love for you to take a look!

[MickL]

What bothers me is that when I only have on task running (which is common e.g. for Drizzle) it still shows this task UI and I need to jump into the task with enter key. Instead Turbo could notice I am executing just one task and just show me the output of this task with nothing around it.

[MickL]

For me the output is cut off so I cant see what use action I am doing

[anthonyshew]

We've got a new design on the most recent canary that should hopefully help with this. Give it a look!

[juliusmarminge]

indentation gets weird sometimes...

[anthonyshew]

Try out the latest canary! Should be fixed.

[juliusmarminge]

file-links aren't clickable:
https://github.com/vercel/turbo/assets/51714798/b44a877d-8d4a-43bd-a855-f1c32668ee6b

[Willem-Jaap]

Thanks for this!
The terminal looks great but takes up a lot of screen real estate.

I think there is some space that can be freed up, maybe a `'experimentalUIStyle: "compact" | "default"' prop?

Maybe the interactions can be moved to top right and using symbols.
↑↓ to navigate, ⏎ to interact, ctrl+z to stop

[anthonyshew]

We did a redesign that should help with this! Try out the latest canary. 👍

[juliusmarminge]

Is it necessary for all logs to be prefixed? Maybe the header should be bold and colorful instead of the line inside of the block?

[juliusmarminge]

Ok with a bit more info in the task it looks a bit better, still think that the header should be more visible and remove the prefix inside of the block?

[anthonyshew]

We did some redesigning that should address these. Try the latest canary!

[ColinCee]

Is the interaction ability bugged? Pressing enter doesn't allow me to send commands to jest watch. a, f, o, q and nothing happens

on Turbo v1.13.2

Screen.Recording.2024-04-09.at.12.10.50.mov

my task config

    "test:watch": {
      "dependsOn": ["@right-track/common#build"],
      "cache": false
    },

I'm using zsh in vscode integrated terminal

[ColinCee]

Interesting, so by default it's not interactive? The message with "Press 'Enter' to interact..." is misleading in that case

[anthonyshew]

Fair! cc @chris-olszewski

[MickL]

I didnt set this option but it was interactive for me on macOS

[ColinCee]

Adding "interactive": true to the task definition fixed the issue, not sure why you don't need it @MickL but it doesn't work for me without it

[anthonyshew]

We've updated this behavior. Any persistent task is now interactive by default!

[pjmlp]

While the UI looks nice, it is completly unusable for me, I am completly lost on how to find errors, and documentation doesn't help.

Had to disable it.

[anthonyshew]

This is currently an experimental feature so we haven't documented it yet. Could you be more specific about the problems you had?

[pjmlp]

Basically I was left with "Build error" kind of message, without being able to see the actual compilation trace that lead to the error.

I had to revert to the old UI, to finally being able to read that environment variables validation was giving an error regarding current configuration, something that with a plain "Build Error", I would never find out.

[anthonyshew]

It sounds like we hadn't implemented scrolling yet, which should be available now. If you can, try out the latest canary. Interested to hear what you think.

[stuible]

Loving this new UI so far, appreciate all the work that's gone into it! One request, it would be useful to be able to switch to a view that combines the all the logs into one stream (without having to exit, disable the new UI and restart the application).

[anthonyshew]

This was something that we thought about - but, unfortunately, can't support due to how some CLIs paint to the terminal. A streamed log can't be interactive, some CLIs hard overwrite liners with their spinners, and a litany of other issues. This new UI is meant to solve many of those problems (along with creating an overall better experience) in one swoop.

If you do still like the log stream, you'll still be able to set it with --log-order=stream.

[samcx]

There is a flash of the UI when you get a full turbo.

[Willem-Jaap]

I just tried the latest canary, the layout looks more organized (which resolves my previous comment #7802 (comment)), great job!

However, the tasks show a loading spinner for long running tasks like dev which is quite distracting

[tungtranpendle]

Hi @anthonyshew, the new UI is great but may I ask how do I copy from the raw output of the latest experimental UI? It seems not compatible with the default terminal, hope you will support that feature

[dBianchii]

I can't highlight, or copy from the terminal.

[trungtin]

Note here if someone using iterm2 like me and cannot make it scroll.

Go to Profile > Terminal > Enable mouse reporting:

• Report mouse wheel events: enable to make the panel scrollable
• Report mouse clicks & drags: disable to be able to highlight and copy from terminal (or temporary disable by holding alt/option key)

[mstade]

This new UI is FIRE 🔥 Thank you! 🙏

[weyert]

How do we disable the UI in the latest canary build?

[venables]

set "ui": "stream" in your turbo.json

https://turbo.build/repo/docs/reference/configuration#ui

[ehaynes99]

Is there a way to do it on an individual basis, such as an env var? I don't want to disable it for my whole org, as some might like it, but it's not for me.

[MickL]

Feedback for 1.13.4-canary.5:

• Scrolling with trackpad doesnt seem to work. I scroll down and it scrolls up again and again.
• When starting just one task I cant enter interact with it. I can scroll (more or less...) but I when I press enter it doesnt work with confirming Drizzle Studio.
• Even when disabling the new UI I cant interact with the task AND it is cut off as well. Same for 1.13.3:
• When starting just one task (e.g. with --filter="...") there should be no left sidebar. Actually in this case the whole terminal UI can be deactivated
• Otherwise when starting just one task and there is a left sidebar, the task should be interactive immediately. It is very scary to do something like drizzle:push and then it asks "Do you really want to push changes? > Yes, No " and I need to press enter to get into the task
• When I scroll in the terminal it scrolls the tasks on the left but not visible logs. This is very annoying because I need to go in the task first to be able to scroll.

Are you guys even reading this? I am afraid you will release the new version of Turbo with the UI that is not usable at all atm (see point 1-3).

[jamesvclements]

Looks like some items are hidden on the left unless I manually press down to reveal them:

CleanShot.2024-06-04.at.15.34.20.mp4

[anthonyshew]

Appreciate this report. I've converted it to an issue as #8310. Let's follow up there.

[jamesvclements]

It also seems like native inertia scrolling isn't supported, so scrolling through feels quite slow / sticky compared to the normal terminal, on a Mac OS trackpad / magic mouse at least

[ehaynes99]

I don't think that's possible to solve that in a TUI. Terminals don't have scrolling; it's a feature of a terminal emulator, and that's a desktop application that can take advantage of OS features. A TUI is a terminal application that effectively has no scrollback,

[siawyoung]

This new UI breaks when I'm running it in husky precommit:

In my root package.json:

    "lint": "turbo lint",

and in .husky/pre-commit:

pnpm lint

when running this, it gives:

$ git commit -m "Test commit"
• Packages in scope: ....
• Running lint in 8 packages
• Remote caching disabled
  × internal errors encountered: receiver dropped,receiver dropped,receiver dropped

The only way to fix this that I've found dso far is to add "ui": "stream" to the root turbo.json.

[anthonyshew]

Thanks for this report. I've created a new issue from this at #8311. We will follow up there.