ttab
v0.9.0
Published
OSX CLI for opening a new terminal tab/window, optionally with a command to execute and/or display settings
Downloads
153,346
Maintainers
Readme
Contents
ttab — programmatically open a new terminal tab or window
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).
- On macOS: either
Terminal
(the default terminal emulator) or popular alternativeiTerm2
. - On Linux, Gnome Terminal (
gnome-terminal
), thanks to a contribution by @ksvirsky. - Note:
ttab
does not support Windows; consider using the Windows Terminal-basedwttab
utility there.
Note: iTerm2
and gnome-terminal
support is currently not covered by the automated tests run before every release.
Installation
Important: On macOS, irrespective of installation method, Terminal
/ iTerm2
(iTerm.app
) needs to be granted access for assistive devices in order for ttab
to function properly, which is a one-time operation that requires administrative privileges.
If you're not prompted on first run and get an error message instead, go to System Preferences > Security & Privacy
, tab Privacy
, select Accessibility
, unlock, and make sure Terminal.app
/ iTerm.app
is in the list on the right and has a checkmark.
For more information, see Apple's support article on the subject.
Installation via Homebrew (macOS only)
With Homebrew installed, run the following:
brew tap mklement0/ttab https://github.com/mklement0/ttab.git
brew install 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 upgrade
ttab
to the latest version, runbrew upgrade ttab
. - To remove
ttab
later, runbrew rm ttab
.
Installation from the npm registry
With Node.js installed, install from the npm registry:
[sudo] npm install ttab -g
Note:
- Whether you need
sudo
depends on how you installed Node.js and whether you've changed permissions later; if you get anEACCES
error, try again withsudo
. - The
-g
ensures global installation and is needed to putttab
in your system's$PATH
.
Manual installation
- Download this
bash
script asttab
. - Make it executable with
chmod +x ttab
. - Move it to a folder in your
$PATH
, such as/usr/local/bin
.
Examples
# 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_DELAY
ttab -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.
ttab exec /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 iTerm2 echo 'Hi from iTerm2.'
# Execute the command in the current tab of the current terminal window:
ttab -c 'ls "$HOME/Library/Application Support"'
Usage
Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man ttab
(ttab --man
if installed manually).
$ ttab --help
Opens 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 to iTerm2 users: The -t
option for specifying a title only works if
the new tab's active profile is configured to show the session name in the
title, which can be configured via the Preferences dialog as shown by
@francis-lookback here.
License
Copyright (c) 2015-2024 Michael Klement [email protected] (http://same2u.net), released under the MIT license.
Acknowledgements
A thank you to all contributors to this repo, especially the following major ones:
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; the absence of a suffix denotes a required run-time dependency: (D)
denotes a development-time-only dependency, (O)
an optional dependency, and (P)
a peer dependency.
npm dependencies
Changelog
Versioning complies with semantic 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.
- [enhancement] Thanks to @HofiOne,
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).
- [enhancement] New
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.
- [fix] for #39;
v0.7.1 (2021-04-06):
- [fix] Fix for #13:
-g
and-G
now work in macOS Big Sur too.
- [fix] Fix for #13:
v0.7.0 (2020-08-24):
- [enhancement] Thanks to @ksvirsky,
ttab
is now also available on Linux, assuminggnome-terminal
is available.
- [enhancement] Thanks to @ksvirsky,
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).
- [fix] macOS 10.13 (High Sierra compatibility), which makes
v0.6.0 (2017-06-21):
- [enhancement]
-d ''
now preventsttab
from implicitly changing to what it thinks the working directory should be; useful for creating tabs/windows that set their own working directory.
- [enhancement]
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 after opening usingclear
, assuming any command (list) passed succeeded. - [enhancement] A quoted multi-command shell command string can now be
specified as a single - and only - operand, without having to precede with
an explicit
eval
command. - [behavior change] If no custom title is specified with
-t <title>
, no attempt is made anymore to auto-derive a meaningful tab title from the shell command specified, as there is no heuristic that works well in all cases. - [fix] Issue #7: iTerm2 now also preserves the current working dir. when opening a new tab in the current window.
- [new feature]
v0.4.0 (2016-09-13):
- [enhancement]
-a Terminal|iTerm2
now allows specifying the target Terminal application, which is useful for launchingttab
from non-terminal applications such as Alfred. - [fix] Specifying a syntactically invalid shell command to execute in the
new tab now causes
ttab
to report a nonzero exit code.
- [enhancement]
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.
- [enhancement] Experimental support for iTerm2 (
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 via
eval
. - [doc] If installed via the npm registry, a man page is now installed (view with
man ttab
); if installed manually,ttab --man
shows a plain-text version.ttab -h
now only prints concise, single-page usage information.
- [enhancement] You can now use embedded (escaped, if necessary) double-quotes inside a multi-command string passed via
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 to
package.json
. - [dev]
make browse
now opens the GitHub repo in the default browser.
- [doc] Improved CLI usage help; keywords added to
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.