{"id":13587316,"url":"https://github.com/mklement0/ttab","last_synced_at":"2025-05-16T15:09:11.744Z","repository":{"id":33005247,"uuid":"36637626","full_name":"mklement0/ttab","owner":"mklement0","description":"macOS and Linux CLI for opening a new terminal tab/window, optionally with a command to execute and/or display settings","archived":false,"fork":false,"pushed_at":"2025-03-10T23:18:33.000Z","size":477,"stargazers_count":290,"open_issues_count":6,"forks_count":15,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-16T15:09:05.043Z","etag":null,"topics":["cli","macos","tabs","tabs-management","terminal","ttab"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":"Unmaintained","scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mklement0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-06-01T04:22:25.000Z","updated_at":"2025-04-16T15:23:33.000Z","dependencies_parsed_at":"2024-01-18T02:37:19.053Z","dependency_job_id":"2853dd17-c804-4cc5-be06-47e742b72281","html_url":"https://github.com/mklement0/ttab","commit_stats":{"total_commits":59,"total_committers":7,"mean_commits":8.428571428571429,"dds":0.3389830508474576,"last_synced_commit":"5e2320aaa634b5386f6adc17590b70716abd17e2"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fttab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fttab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fttab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mklement0%2Fttab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mklement0","download_url":"https://codeload.github.com/mklement0/ttab/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","macos","tabs","tabs-management","terminal","ttab"],"created_at":"2024-08-01T15:06:09.185Z","updated_at":"2025-05-16T15:09:06.735Z","avatar_url":"https://github.com/mklement0.png","language":"Shell","readme":"[![npm version](https://img.shields.io/npm/v/ttab.svg)](https://npmjs.com/package/ttab) [![license](https://img.shields.io/npm/l/ttab.svg)](https://github.com/mklement0/ttab/blob/master/LICENSE.md)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n**Contents**\n\n- [ttab \u0026mdash; programmatically open a new terminal tab or window](#ttab-mdash-programmatically-open-a-new-terminal-tab-or-window)\n- [Installation](#installation)\n  - [Installation via Homebrew (macOS only)](#installation-via-homebrew-macos-only)\n  - [Installation from the npm registry](#installation-from-the-npm-registry)\n  - [Manual installation](#manual-installation)\n- [Examples](#examples)\n- [Usage](#usage)\n- [License](#license)\n  - [Acknowledgements](#acknowledgements)\n  - [npm dependencies](#npm-dependencies)\n- [Changelog](#changelog)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# ttab \u0026mdash; programmatically open a new terminal tab or window\n\nA 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).\n\n- On **[macOS](https://www.apple.com/macos)**: either `Terminal` (the default terminal emulator) or popular alternative [`iTerm2`](http://www.iterm2.com/).\n- On **Linux**, [Gnome Terminal](https://help.gnome.org/users/gnome-terminal) (`gnome-terminal`), thanks to a contribution by [@ksvirsky](https://github.com/ksvirsky).\n- Note: `ttab` does _not_ support **Windows**; consider using the [Windows Terminal](https://github.com/microsoft/terminal/blob/main/README.md)-based [`wttab`](https://github.com/lalilaloe/wttab) utility there.\n\nNote: `iTerm2` and `gnome-terminal` support is currently not covered by the automated tests run before every release.\n\n# Installation\n\n**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_.\nIf you're not prompted on first run and get an error message instead, go to `System Preferences \u003e Security \u0026 Privacy`, tab `Privacy`, select `Accessibility`, unlock, and make sure `Terminal.app` / `iTerm.app` is in the list on the right and has a checkmark.\nFor more information, see [Apple's support article on the subject](https://support.apple.com/en-us/HT202802).\n\n## Installation via Homebrew (macOS only)\n\nWith [Homebrew](https://brew.sh/) installed, run the following:\n\n* Initial installation:\n\n```sh\nbrew tap mklement0/ttab https://github.com/mklement0/ttab.git\nbrew install mklement0/ttab/ttab\n```\n\n* Later updates:\n\n```sh\nbrew upgrade mklement0/ttab/ttab\n```\n\nNote:\n\n- The Homebrew version may lag behind the npm registry version if later versions relate solely to the Linux-only Gnome Terminal functionality.\n- To remove `ttab` later, run `brew rm ttab`.\n\n## Installation from the npm registry\n\nWith [Node.js](http://nodejs.org/) installed, install from the [npm registry](https://www.npmjs.com/package/ttab):\n\n* Initial installation:\n\n      [sudo] npm install ttab -g\n\n* Later update:\n\n      [sudo] npm upgrade ttab -g\n\n**Note**:\n\n- Whether you need `sudo` depends on how you installed Node.js and whether you've [changed permissions later](https://docs.npmjs.com/getting-started/fixing-npm-permissions); if you get an `EACCES` error, try again with `sudo`.\n- The `-g` ensures [_global_ installation](https://docs.npmjs.com/getting-started/installing-npm-packages-globally) and is needed to put `ttab` in your system's `$PATH`.\n- To remove `ttab` later, run `[sudo] npm rm ttab -g`.\n\n## Manual installation\n\n- Download [this `bash` script](https://raw.githubusercontent.com/mklement0/ttab/stable/bin/ttab) as `ttab`.\n- Make it executable with `chmod +x ttab`.\n- Move it to a folder in your `$PATH`, such as `/usr/local/bin`.\n\n# Examples\n\n```shell\n# Open a new tab in the current terminal window.\nttab\n\n# Open a new tab in a new terminal window.\nttab -w\n\n# Open new horizontal split tab in the current terminal window:\nttab -h\n\n# Open new vertical split tab in the current terminal window, changing the path to the\n# given path, but without checking the presence of the target directory:\nttab -v -i -d \"$HOME/Library/Application Support\"\n\n# Open a new tab and execute the specified command before showing the prompt.\nttab ls -l \"$HOME/Library/Application Support\"\n\n# Open a new tab and execute the specified command *after a delay* of 0.8 secs,\n# to accommodate shells with lengthy initialization-file processing.\n# Note: You may preset the delay via environment variable TTAB_CMD_DELAY\nttab -l 0.8 ls -1\n\n# Open a new tab and execute *multiple* commands in it - note how the entire\n# command line is specified as *single, quoted string*.\nttab 'git branch; git status'\n\n# Open a new tab, switch to the specified dir., then execute the specified\n# command before showing the prompt.\nttab -d ~/Library/Application\\ Support ls -1\n\n# Open a new tab with title 'How Green Was My Valley' and settings 'Grass'.\n# See the note re use of -t in iTerm2 below.\nttab -t 'How Green Was My Valley' -s Grass\n\n# Open a new tab and execute the specified script before showing the prompt.\nttab /path/to/someScript\n\n# Open a new tab, execute the specified script, and exit.\nttab exec /path/to/someScript\n\n# Open a new tab, execute a command, wait for a keypress, and exit.\nttab 'ls \"$HOME/Library/Application Support\"; echo Press a key to exit.; read -rsn 1; exit'\n\n# Open a new tab in iTerm2 (if installed).\nttab -a iTerm2 echo 'Hi from iTerm2.'\n\n# Execute the command in the current tab of the current terminal window:\nttab -c 'ls \"$HOME/Library/Application Support\"'\n```\n\n# Usage\n\nFind concise usage information below; for complete documentation, read the [manual online](doc/ttab.md), or, once installed, run `man ttab` (`ttab --man` if installed manually).\n\n\u003c!-- DO NOT EDIT THE FENCED CODE BLOCK and RETAIN THIS COMMENT: The fenced code block below is updated by `make update-readme/release` with CLI usage information. --\u003e\n\n```nohighlight\n$ ttab --help\n\n\nOpens a new terminal tab or window, on macOS in either Terminal.app or  \niTerm2.app; on Linux in Gnome Terminal, if available.\n\n    ttab [-w|-v|-h|-c] [-i] [-s \u003csettings\u003e] [-t \u003ctitle\u003e] [-q] [-g|-G] [-d \u003cdir\u003e] [\u003ccmd\u003e ...]\n\n    -w                  Open new tab in new terminal window.\n    -v                  iTerm only: create a new vertical split\n    -h                  iTerm only: create a new horizontal split\n    -c                  Terminal/iTerm only: do not open any new window or\n                        tab, run in the current tab of the current window.\n    -i                  Suppress up-front verification of the existence of\n                        the target directory specified via the -d option.\n    -s \u003csettings\u003e       Assign a settings set (profile).\n    -t \u003ctitle\u003e          Specify title for new tab.\n    -q                  Clear the new tab's screen.\n    -g                  Terminal/iTerm only: create in background (don't\n                        activate application).\n    -G                  Terminal/iTerm: don't activate new tab and create in\n                        background.\n                        gnome-terminal: don't activate new tab, except with -w.\n    -d \u003cdir\u003e            Specify working directory; -d '' disables inheriting\n                        the current dir. in Terminal/iTerm.\n    -l \u003csecs\u003e           Terminal/iTerm only: delay startup command submission;\n                        may be preset via env. var. TTAB_CMD_DELAY\n    -a Terminal | iTerm Open the new tab in the given terminal app on macOS.\n    \u003ccmd\u003e ...           Command to execute in the new tab.\n    \"\u003ccmd\u003e ...; ...\"    Multi-command command line (passed as single operand).\n\nStandard options: --help, --man, --version, --home\n```\n\nNote to **iTerm2 users**: The `-t` option for specifying a title only works if\nthe new tab's active profile is configured to show the session name in the\ntitle, which can be configured via the Preferences dialog as shown by\n@francis-lookback [here](https://github.com/mklement0/ttab/issues/23#issuecomment-645210109).\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n# License\n\nCopyright (c) 2015-2024 Michael Klement \u003cmklement0@gmail.com\u003e (http://same2u.net), released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).\n\n## Acknowledgements\n\nA thank you to all contributors to this repo, especially the following major ones:\n\n* [@ksvirsky](https://github.com/ksvirsky)\n* [@HofiOne](https://github.com/HofiOne)\n\nThis project gratefully depends on the following open-source components, according to the terms of their respective licenses.\n\n[npm](https://www.npmjs.com/) 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.\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n## npm dependencies\n\n* [doctoc (D)]()\n* [json (D)]()\n* [marked (D)](https://marked.js.org)\n* [marked-man (D)]()\n* [replace (D)]()\n* [semver (D)]()\n* [tap (D)](http://www.node-tap.org/)\n* [urchin (D)]()\n\n\u003c!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. --\u003e\n\n# Changelog\n\nVersioning complies with [semantic versioning (semver)](http://semver.org/).\n\n\u003c!-- NOTE: An entry template for a new version is automatically added each time `make version` is called. Fill in changes afterwards. --\u003e\n\n* **[v0.9.0](https://github.com/mklement0/ttab/compare/v0.8.0...v0.9.0)** (2024-05-22):\n  * [enhancement] Thanks to [@HofiOne](https://github.com/HofiOne), `ttab` now supports new macOS-focused options, `-h`, `-v`, `-c`, and `-i`, \n    which notably includes support for splitting the current tab horizontally (`-h`) or vertically (`-v`) in iTerm2.\n  * [fix] Attempts to use options that are not supported in the target terminal now consistently result in errors.\n  * [breaking change] Since `-h` now requests horizontal splitting, it can no longer be used to invoke help; use `--help` instead.\n\n* **[v0.8.0](https://github.com/mklement0/ttab/compare/v0.7.3...v0.8.0)** (2023-01-12):\n  * [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).\n\n* **[v0.7.3](https://github.com/mklement0/ttab/compare/v0.7.2...v0.7.3)** (2022-08-11):\n  * [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.\n\n* **[v0.7.2](https://github.com/mklement0/ttab/compare/v0.7.1...v0.7.2)** (2021-10-26):\n  * [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.\n\n* **[v0.7.1](https://github.com/mklement0/ttab/compare/v0.7.0...v0.7.1)** (2021-04-06):\n  * [fix] Fix for #13: `-g` and `-G` now work in macOS Big Sur too.\n\n* **[v0.7.0](https://github.com/mklement0/ttab/compare/v0.6.1...v0.7.0)** (2020-08-24):\n  * [enhancement] Thanks to [@ksvirsky](https://github.com/ksvirsky), `ttab` is now also available on Linux, assuming `gnome-terminal` is available.\n\n* **[v0.6.1](https://github.com/mklement0/ttab/compare/v0.6.0...v0.6.1)** (2017-11-08):\n  * [fix] macOS 10.13 (High Sierra compatibility), which makes `-G` work again.\n  * [installation] Homebrew formula added (added post-release, on 2019-12-22).\n\n* **[v0.6.0](https://github.com/mklement0/ttab/compare/v0.5.1...v0.5.2)** (2017-06-21):\n  * [enhancement] `-d ''` now prevents `ttab` from implicitly changing to what\n    it thinks the working directory should be; useful for creating tabs/windows\n    that set their own working directory.\n\n* **[v0.5.1](https://github.com/mklement0/ttab/compare/v0.5.0...v0.5.1)** (2017-03-23):\n  * [doc] Sample command fixed.\n  * [dev] Reliability of tests improved.\n\n* **[v0.5.0](https://github.com/mklement0/ttab/compare/v0.4.0...v0.5.0)** (2016-10-01):\n  * [new feature] `-q` now allows clearing the \"screen\" of the new tab after\n     opening using `clear`, assuming any command (list) passed succeeded.\n  * [enhancement] A quoted multi-command shell command string can now be \n    specified as a single - and only - operand, without having to precede with\n    an explicit `eval` command. \n  * [behavior change] If no custom title is specified with `-t \u003ctitle\u003e`, no\n    attempt is made anymore to auto-derive a meaningful tab title from the\n    shell command specified, as there is no heuristic that works well in all\n    cases.\n  * [fix] [Issue #7](https://github.com/mklement0/ttab/issues/7): iTerm2\n    now also preserves the current working dir. when opening a new tab in the \n    current window.\n\n* **[v0.4.0](https://github.com/mklement0/ttab/compare/v0.3.1...v0.4.0)** (2016-09-13):\n  * [enhancement] `-a Terminal|iTerm2` now allows specifying the target Terminal\n    application, which is useful for launching `ttab` from non-terminal applications\n    such as [Alfred](http://alfredapp.com).\n  * [fix] Specifying a syntactically invalid shell command to execute in the\n    new tab now causes `ttab` to report a nonzero exit code.\n\n* **[v0.3.1](https://github.com/mklement0/ttab/compare/v0.3.0...v0.3.1)** (2016-06-03):\n  * [enhancement] Support for iTerm2 v3 added (whose AppleScript syntax changed fundamentally)\n  * [enhancement] Setting a tab title is now also supported in iTerm2 v2.\n\n* **[v0.3.0](https://github.com/mklement0/ttab/compare/v0.2.1...v0.3.0)** (2016-05-04):\n  * [enhancement] Experimental support for iTerm2 (`iTerm.app`) added.\n\n* **[v0.2.1](https://github.com/mklement0/ttab/compare/v0.2.0...v0.2.1)** (2015-09-15):\n  * [dev] Makefile improvements; various other behind-the-scenes tweaks.\n\n* **[v0.2.0](https://github.com/mklement0/ttab/compare/v0.1.8...v0.2.0)** (2015-09-14):\n  * [enhancement] You can now use embedded (escaped, if necessary) double-quotes inside a multi-command string passed via `eval`.\n  * [doc] If installed via the npm registry, a man page is now installed (view with `man ttab`); if installed manually, `ttab --man`\n    shows a plain-text version. `ttab -h` now only prints concise, single-page usage information.\n\n* **[v0.1.8](https://github.com/mklement0/ttab/compare/v0.1.7...v0.1.8)** (2015-09-11):\n  * [doc] Incorrect new-window option corrected in examples.\n  * [doc, dev] Read-me improved together with the Makefile to turn off syntax highlighting for the CLI help chapter.\n\n* **[v0.1.7](https://github.com/mklement0/ttab/compare/v0.1.6...v0.1.7)** (2015-06-26):\n  * [doc] Read-me: npm badge changed to shields.io; license badge added.\n  * [dev] Makefile updated.\n\n* **v0.1.6** (2015-06-01):\n  * [doc] Read-me improvements; typo in CLI usage help fixed.\n\n* **v0.1.5** (2015-06-01):\n  * [doc] Improved CLI usage help.\n\n* **v0.1.4** (2015-06-01):\n  * [doc] Improved CLI usage help; keywords added to `package.json`.\n  * [dev] `make browse` now opens the GitHub repo in the default browser.\n\n* **v0.1.3** (2015-06-01):\n  * [fix] The -g and -G options again correctly do not activate Terminal.app when creating the desired tab.\n  * [enhancement] Option parsing now accepts option-arguments directly attached to the option.\n  * [dev] Tests added.\n\n* **v0.1.2** (2015-06-01):\n  * [doc] Manual-installation link and instructions fixed; examples fixed.\n\n* **v0.1.1** (2015-06-01):\n  * [doc] README.md improved with respect to manual installation instructions.\n\n* **v0.1.0** (2015-06-01):\n  * Initial release.\n","funding_links":[],"categories":["Shell","cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Fttab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmklement0%2Fttab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmklement0%2Fttab/lists"}