Integrate consoles, shells, and terminals inside Obsidian.
Repository · Changelog · Community plugin · Related · Features · Installation · Usage · Contributing · Security
For first time users, read the installation section first!
This file is automatically opened on first install. You can reopen it in settings or command palette.
- Start external terminals from Obsidian.
- Integrate terminals into Obsidian.
- Has an emulated developer console usable on all platforms.
- Supports multiple terminal profiles.
- Has built-in keyboard shortcuts.
- Automatically save and restore integrated terminal history.
- Find in terminal.
- Save terminal history as file.
- Customize terminal appearance.
- Install plugin.
- Community plugins
- Install the plugin from community plugins directly.
- Manual
- Create directory
terminal
under.obsidian/plugins
of your vault. - Place
manifest.json
,main.js
, andstyles.css
from the latest release into the directory.
- Create directory
- Building (latest)
- Clone this repository, including its submodules.
- Install npm.
- Run
npm install
in the root directory. - Run
npm run obsidian:install <vault directory>
in the root directory.
- Obsidian42 - BRAT (latest)
- See their readme.
- Community plugins
- (optional for Windows, recommended) Install Python and dependencies.
- Install Python 3.10/+.
- (Windows only) Run
pip3 install psutil==5.9.5 pywinctl==0.0.50 typing_extensions==4.7.1
. - Configure Python executable in profile settings. Press the "Check" button to validate the Python configuration. Each profile needs to be configured separately.
- Enable plugin.
- (optional) Configure plugin settings.
- To start a new external or integrated terminal
- Ribbon
- Click on the
Open terminal
ribbon. - Choose the desired profile.
- Click on the
- Context menu
- Right-click on files, folders, or tab headers.
- Choose the desired action (and profile).
- Command palette
- Press
Ctrl
+P
or click on theOpen command palette
ribbon next to the left window border. - Choose the desired action (and profile).
- Press
- Select profile modal
- Choose the desired profile. Press
Ctrl
to edit the profile before use. The item(Temporary profile)
starts a terminal with a temporary profile.
- Choose the desired profile. Press
- Ribbon
- To save and restore integrated terminal history
- Keep the terminal open when exiting Obsidian.
- Terminal history will be restored next time Obsidian is opened.
- Additional actions
- Includes
- Clear terminal: (1), (4)
- Copy terminal: (1)
- Edit terminal: (1)
- Export, import, or edit settings: (2), (3)
- Find in terminal: (1), (4)
- Open documentation: (2), (3)
- Restart terminal: (1)
- Save terminal history: (1)
- Available by
- (1) Right-click on tab header/
More options
- (2) Open settings
- (3) Open command palette
- (4) Use keyboard shortcuts
- (1) Right-click on tab header/
- Includes
The keyboard shortcuts can be customized in hotkeys settings.
Global
- Toggle focus on last terminal:
Ctrl
+Shift
+`
- Focus on last terminal: (unbound; useful if you want separate keys for focus and unfocus)
Terminal is focused
When a terminal is focused, other keyboard shortcuts (including Obsidian and plugin hotkeys) are disabled. Only the following keyboard shortcuts work. Thus you can ignore Obsidian complaining about conflicting keys for the following keyboard shortcuts.
- Clear terminal:
Ctrl
+Shift
+K
,Command
+Shift
+K
(Apple) - Close terminal:
Ctrl
+Shift
+W
,Command
+Shift
+W
(Apple) - Find in terminal:
Ctrl
+Shift
+F
,Command
+Shift
+F
(Apple) - Toggle focus on last terminal:
Ctrl
+Shift
+`
(same as above)- Unfocus terminal: (unbound; useful if you want separate keys for focus and unfocus)
Theming is possible. However, there is no user-friendly interface for now.
- Open the profile editing modal.
- Click on the
Edit
button labeledData
. It should open up a new modal in which there is a large textbox. - Notice
terminalOptions
in the text area labeledData
. Refer to thexterm.js
documentation (ITerminalOptions
) to set the options. Nested objects may need to be used. - Save the profile. Changes should apply immediately.
This plugin comes with several profile presets that you can reference.
When setting up a terminal profile, you need to distinguish between shells and terminal emulators. (Search online if needed.) Generally, integrated profiles only work with shells while external ones only work with terminal emulators.
Shells
- Bash:
bash
- Bourne shell:
sh
- Command Prompt:
cmd
- Dash:
dash
- Git Bash:
<Git installation>\bin\bash.exe
(e.g.C:\Program Files\Git\bin\bash.exe
) - PowerShell Core:
pwsh
- Windows PowerShell:
powershell
- Windows Subsystem for Linux:
wsl
orwsl -d <distribution name>
- Z shell:
zsh
Terminal emulators
- Command Prompt:
cmd
- GNOME Terminal:
gnome-terminal
- Konsole:
konsole
- Terminal (macOS):
/System/Applications/Utilities/Terminal.app/Contents/macOS/Terminal "$PWD"
- Windows Terminal:
wt
- iTerm2:
/Applications/iTerm.app/Contents/MacOS/iTerm2 "$PWD"
- xterm:
xterm
This plugin patches require
so that require("obsidian")
and other Obsidian modules work in the developer console. It is toggleable as Expose internal modules
in settings.
In the developer console, a context variable $$
is passed into the code, which can be used to dynamically change terminal options.
The full API is available from src/@types/obsidian-terminal.ts
.
- Is the plugin useful on mobile?
- Compared to on desktop, it is much less useful. The only use for it for now is opening a developer console on mobile.
- Why do hotkeys not work?
- If the terminal is in focus, all Obsidian hotkeys are disabled so that you can type special characters into the terminal. You can unfocus the terminal by pressing
Ctrl
+Shift
+`
, then you can use Obsidian hotkeys again.
- If the terminal is in focus, all Obsidian hotkeys are disabled so that you can type special characters into the terminal. You can unfocus the terminal by pressing
Contributions are welcome!
This project uses changesets
to manage the changelog. When creating a pull request, please add a changeset describing the changes. Add multiple changesets if your pull request changes several things. End each changeset with ([PR number](PR link) by [author username](author link))
. For example, the newly created file under the directory .changeset
should look like:
---
"example": patch
---
This is an example change. ([GH#1](https://github.com/ghost/example/pull/1) by [@ghost](https://github.com/ghost))
The todos here, ordered alphabetically, are things planned for the plugin. There are no guarantees that they will be completed. However, we are likely to accept contributions for them.
- Connect to remote shells.
- Detect sandboxed environment and notify users.
- External link confirmation.
- Filter console log by severity in the developer console.
- Indicate that the terminal resizer has crashed or is disabled.
- Shared terminal tabs.
- Vim mode switch.
We hope that there will never be any security vulnerabilities, but unfortunately it does happen. Please report them!
Version | Supported |
---|---|
latest | ✅ |
outdated | ❌ |
Please report a vulnerability by opening an new issue. We will get back to you as soon as possible.