Repository files navigation

Contents

• ttab — programmatically open a new terminal tab or window
• Installation
  • Installation via Homebrew (macOS only)
  • Installation from the npm registry
  • Manual installation
• Examples
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

A CLI for Unix-like platforms that programmatically opening a new terminal tab/window in one of the following terminal applications, optionally with a command to execute and/or a specific title and specific display settings (profile).

• OnmacOS: eitherTerminal (the default terminal emulator) or popular alternativeiTerm2.
• OnLinux,Gnome Terminal (gnome-terminal), thanks to a contribution by@ksvirsky.
• Note:ttab doesnot supportWindows; consider using theWindows Terminal-basedwttab utility there.

Note:iTerm2 andgnome-terminal support is currently not covered by the automated tests run before every release.

Important: On macOS, irrespective of installation method,Terminal /iTerm2 (iTerm.app) needs to be grantedaccess for assistive devices in order forttab to function properly, which is aone-time operation that requires administrative privileges.If you're not prompted on first run and get an error message instead, go toSystem Preferences > Security & Privacy, tabPrivacy, selectAccessibility, unlock, and make sureTerminal.app /iTerm.app is in the list on the right and has a checkmark.For more information, seeApple's support article on the subject.

WithHomebrew installed, run the following:

• Initial installation:

brew tap mklement0/ttab https://github.com/mklement0/ttab.gitbrew install mklement0/ttab/ttab

• Later updates:

brew upgrade mklement0/ttab/ttab

Note:

• The Homebrew version may lag behind the npm registry version if later versions relate solely to the Linux-only Gnome Terminal functionality.
• To removettab later, runbrew rm ttab.

WithNode.js installed, install from thenpm registry:

• Initial installation:

  [sudo] npm install ttab -g

• Later update:

  [sudo] npm upgrade ttab -g

Note:

• Whether you needsudo depends on how you installed Node.js and whether you'vechanged permissions later; if you get anEACCES error, try again withsudo.
• The-g ensuresglobal installation and is needed to putttab in your system's$PATH.
• To removettab later, run[sudo] npm rm ttab -g.

• Downloadthisbash script asttab.
• Make it executable withchmod +x ttab.
• Move it to a folder in your$PATH, such as/usr/local/bin.

# Open a new tab in the current terminal window.ttab# Open a new tab in a new terminal window.ttab -w# Open new horizontal split tab in the current terminal window:ttab -h# Open new vertical split tab in the current terminal window, changing the path to the# given path, but without checking the presence of the target directory:ttab -v -i -d"$HOME/Library/Application Support"# Open a new tab and execute the specified command before showing the prompt.ttab ls -l"$HOME/Library/Application Support"# Open a new tab and execute the specified command *after a delay* of 0.8 secs,# to accommodate shells with lengthy initialization-file processing.# Note: You may preset the delay via environment variable TTAB_CMD_DELAYttab -l 0.8 ls -1# Open a new tab and execute *multiple* commands in it - note how the entire# command line is specified as *single, quoted string*.ttab'git branch; git status'# Open a new tab, switch to the specified dir., then execute the specified# command before showing the prompt.ttab -d~/Library/Application\Support ls -1# Open a new tab with title 'How Green Was My Valley' and settings 'Grass'.# See the note re use of -t in iTerm2 below.ttab -t'How Green Was My Valley' -s Grass# Open a new tab and execute the specified script before showing the prompt.ttab /path/to/someScript# Open a new tab, execute the specified script, and exit.ttabexec /path/to/someScript# Open a new tab, execute a command, wait for a keypress, and exit.ttab'ls "$HOME/Library/Application Support"; echo Press a key to exit.; read -rsn 1; exit'# Open a new tab in iTerm2 (if installed).ttab -a iTerm2echo'Hi from iTerm2.'# Execute the command in the current tab of the current terminal window:ttab -c'ls "$HOME/Library/Application Support"'

Find concise usage information below; for complete documentation, read themanual online, or, once installed, runman ttab (ttab --man if installed manually).

$ ttab --helpOpens a new terminal tab or window, on macOS in either Terminal.app or  iTerm2.app; on Linux in Gnome Terminal, if available.    ttab [-w|-v|-h|-c] [-i] [-s <settings>] [-t <title>] [-q] [-g|-G] [-d <dir>] [<cmd> ...]    -w                  Open new tab in new terminal window.    -v                  iTerm only: create a new vertical split    -h                  iTerm only: create a new horizontal split    -c                  Terminal/iTerm only: do not open any new window or                        tab, run in the current tab of the current window.    -i                  Suppress up-front verification of the existence of                        the target directory specified via the -d option.    -s <settings>       Assign a settings set (profile).    -t <title>          Specify title for new tab.    -q                  Clear the new tab's screen.    -g                  Terminal/iTerm only: create in background (don't                        activate application).    -G                  Terminal/iTerm: don't activate new tab and create in                        background.                        gnome-terminal: don't activate new tab, except with -w.    -d <dir>            Specify working directory; -d '' disables inheriting                        the current dir. in Terminal/iTerm.    -l <secs>           Terminal/iTerm only: delay startup command submission;                        may be preset via env. var. TTAB_CMD_DELAY    -a Terminal | iTerm Open the new tab in the given terminal app on macOS.    <cmd> ...           Command to execute in the new tab.    "<cmd> ...; ..."    Multi-command command line (passed as single operand).Standard options: --help, --man, --version, --home

Note toiTerm2 users: The-t option for specifying a title only works ifthe new tab's active profile is configured to show the session name in thetitle, which can be configured via the Preferences dialog as shown by@francis-lookbackhere.

Copyright (c) 2015-2024 Michael Klementmklement0@gmail.com (http://same2u.net), released under theMIT license.

A thank you to all contributors to this repo, especially the following major ones:

• @ksvirsky
• @HofiOne

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

npm dependencies below have optional suffixes denoting the type of dependency; theabsence of a suffix denotes a requiredrun-time dependency:(D) denotes adevelopment-time-only dependency,(O) anoptional dependency, and(P) apeer dependency.

• doctoc (D)
• json (D)
• marked (D)
• marked-man (D)
• replace (D)
• semver (D)
• tap (D)
• urchin (D)

Versioning complies withsemantic versioning (semver).

• v0.9.0 (2024-05-22):

  • [enhancement] Thanks to@HofiOne,ttab now supports new macOS-focused options,-h,-v,-c, and-i,which notably includes support for splitting the current tab horizontally (-h) or vertically (-v) in iTerm2.
  • [fix] Attempts to use options that are not supported in the target terminal now consistently result in errors.
  • [breaking change] Since-h now requests horizontal splitting, it can no longer be used to invoke help; use--help instead.

• v0.8.0 (2023-01-12):

  • [enhancement] New-l option / env. var.TTAB_CMD_DELAY allows specifying a delay before submitting a startup command to a new tab, to accommodate shells whose initialization-file processing takes a while (iTerminal / iTerm2 only).

• v0.7.3 (2022-08-11):

  • [fix] for #43; the way that keeping the shell alive is emulated in Gnome Terminal now also works when the startup command is aborted with Ctrl-C.

• v0.7.2 (2021-10-26):

  • [fix] for #39;ttab now works correctly when iTerm's "Exclude from Dock and ⌘-Tab Application Switcher" preference is enabled, albeit without support for-g and-G, for technical reasons.

• v0.7.1 (2021-04-06):

  • [fix] Fix for #13:-g and-G now work in macOS Big Sur too.

• v0.7.0 (2020-08-24):

  • [enhancement] Thanks to@ksvirsky,ttab is now also available on Linux, assuminggnome-terminal is available.

• v0.6.1 (2017-11-08):

  • [fix] macOS 10.13 (High Sierra compatibility), which makes-G work again.
  • [installation] Homebrew formula added (added post-release, on 2019-12-22).

• v0.6.0 (2017-06-21):

  • [enhancement]-d '' now preventsttab from implicitly changing to whatit thinks the working directory should be; useful for creating tabs/windowsthat set their own working directory.

• v0.5.1 (2017-03-23):

  • [doc] Sample command fixed.
  • [dev] Reliability of tests improved.

• v0.5.0 (2016-10-01):

  • [new feature]-q now allows clearing the "screen" of the new tab afteropening usingclear, assuming any command (list) passed succeeded.
  • [enhancement] A quoted multi-command shell command string can now bespecified as a single - and only - operand, without having to precede withan expliciteval command.
  • [behavior change] If no custom title is specified with-t <title>, noattempt is made anymore to auto-derive a meaningful tab title from theshell command specified, as there is no heuristic that works well in allcases.
  • [fix]Issue #7: iTerm2now also preserves the current working dir. when opening a new tab in thecurrent window.

• v0.4.0 (2016-09-13):

  • [enhancement]-a Terminal|iTerm2 now allows specifying the target Terminalapplication, which is useful for launchingttab from non-terminal applicationssuch asAlfred.
  • [fix] Specifying a syntactically invalid shell command to execute in thenew tab now causesttab to report a nonzero exit code.

• v0.3.1 (2016-06-03):

  • [enhancement] Support for iTerm2 v3 added (whose AppleScript syntax changed fundamentally)
  • [enhancement] Setting a tab title is now also supported in iTerm2 v2.

• v0.3.0 (2016-05-04):

  • [enhancement] Experimental support for iTerm2 (iTerm.app) added.

• v0.2.1 (2015-09-15):

  • [dev] Makefile improvements; various other behind-the-scenes tweaks.

• v0.2.0 (2015-09-14):

  • [enhancement] You can now use embedded (escaped, if necessary) double-quotes inside a multi-command string passed viaeval.
  • [doc] If installed via the npm registry, a man page is now installed (view withman ttab); if installed manually,ttab --manshows a plain-text version.ttab -h now only prints concise, single-page usage information.

• v0.1.8 (2015-09-11):

  • [doc] Incorrect new-window option corrected in examples.
  • [doc, dev] Read-me improved together with the Makefile to turn off syntax highlighting for the CLI help chapter.

• v0.1.7 (2015-06-26):

  • [doc] Read-me: npm badge changed to shields.io; license badge added.
  • [dev] Makefile updated.

• v0.1.6 (2015-06-01):

  • [doc] Read-me improvements; typo in CLI usage help fixed.

• v0.1.5 (2015-06-01):

  • [doc] Improved CLI usage help.

• v0.1.4 (2015-06-01):

  • [doc] Improved CLI usage help; keywords added topackage.json.
  • [dev]make browse now opens the GitHub repo in the default browser.

• v0.1.3 (2015-06-01):

  • [fix] The -g and -G options again correctly do not activate Terminal.app when creating the desired tab.
  • [enhancement] Option parsing now accepts option-arguments directly attached to the option.
  • [dev] Tests added.

• v0.1.2 (2015-06-01):

  • [doc] Manual-installation link and instructions fixed; examples fixed.

• v0.1.1 (2015-06-01):

  • [doc] README.md improved with respect to manual installation instructions.

• v0.1.0 (2015-06-01):

  • Initial release.