How do I reset the scrollback in the terminal via a shell command?

Question

When using Terminal.app, you can clear the screen by using the shell builtin clear or by pressing ^+L (Control-L).

However, all this does is push the current screen content back one screen height and reset the cursor/input at the first line. Meaning you can still scroll back and see it.

What you are also able to do, is reset your entire scrollback by pressing ⌘+K (Command-K).

After you've done this, you cannot scroll back at all.

In certain situations (notably, before running screen or vim), I'd like to reset the scroll back before the command actually executes.

Is there a command (like clear) that is implemented in OS X that allows me to do this? Given the existence of pbcopy and pbpaste, I'm thinking something similar might exist that will allow me to do this.

Answer 1

Terminal supports an extension of the ED (Erase in Display) escape sequence to erase the scroll-back. It is also supported by xterm. The ED command, described in the VT100 manual, accepts these values for the Ps parameter:

ESC [ Ps J

Parameter   Parameter Meaning

0           Erase from the active position to the end of the screen
1           Erase from start of the screen to the active position
2           Erase all of the display

Terminal (and xterm) adds:

3           Erase the scroll-back (aka “Saved Lines”)

Note that this only erases the scroll-back, not the screen. This allows you to erase one or the other, or both by sending two escape sequences.

For example, you can clear the screen and the scroll-back with the following shell command: clear && printf '\e[3J'

(The clear command looks up the appropriate sequence for clearing the screen for the current terminal, but the “erase scroll-back” escape sequence is custom and must be hard-coded. If you put this in a shell script that you don’t know for certain will only ever be run with Terminal, you should check that $TERM_PROGRAM is Apple_Terminal before sending it.)

Answer 2

⌘K, shortcut to “View > Clear scrollback”.

UPDATE: This can be automated with AppleScript by the following command:

osascript -e 'tell application "System Events" to keystroke "k" using command down'

…which you can of course alias to whatever you want, or store in a function in your ~/.profile login script  :)

As a security though, to be able to use this even in background without risking to issue a keystroke to a wrong front app, I'd advise surrounding it with the following test:

if application "Terminal" is frontmost

…which gives us the following code:

osascript -e 'if application "Terminal" is frontmost then tell application "System Events" to keystroke "k" using command down'

…which in turns, properly escaped and aliased, ends in:

alias clear="osascript -e 'if application \"Terminal\" is frontmost then tell application \"System Events\" to keystroke \"k\" using command down'"

And here is your new clear!  :)

Answer 3

Here's code that works for both macOS' Terminal, and iTerm2. It doesn't need the window to be in the foreground, either.

printf '\033[2J\033[3J\033[1;1H'

How it works

This is a composition of 3 ANSI escape sequences, particularly "Control Sequence Introducer" commands.

\033 is an escape sequence that hardcodes the code point for the character it represents. The leading 0 indicates that the rest of the sequence encodes an octal value, in this case, 33 in octal. The decimal value of that is 27 (3 * 8^1 + 3 * 8^0 = 3 * 8 + 3 = 24 + 3 = 27). In ASCII, code point 27 is the "ESC" (escape) character.

CSI commands start with ESC [, a.k.a. \033[. Knowing this, we can split up the string into its 3 parts.

1. CSI 2 J
   • This is an instance of the "ED – Erase in Display" command, which has the form CSI n J
   • The n value is set to 2 in this case, which invokes the second variant: "If n is 2, clear entire screen (and moves cursor to upper left on DOS ANSI.SYS)."
2. CSI 3 J:
   • This is an instance of the "ED – Erase in Display" command, which has the form CSI n J
   • The n value is set to 3 in this case, which invokes the third variant: "If n is 3, clear entire screen and delete all lines saved in the scrollback buffer (this feature was added for xterm and is supported by other terminal applications)."
3. CSI 1 ; 1 H:
   • This is an instance of the "ED – Erase in Display" command, which has the form CSI n ; m H

     Moves the cursor to row n, column m. The values are 1-based, and default to 1 (top left corner) if omitted. A sequence such as CSI ;5H is a synonym for CSI 1;5H as well as CSI 17;H is the same as CSI 17H and CSI 17;1H

   • The n and m values are both set to 1, which means this command moves the cursor to the top-leftmost corner.