ShellHistory

About

ShellHistory keeps every command you run in Terminal, with where and how it ran, and makes it easy to find again. It works with zsh, bash and fish in any terminal app, and syncs your history between your Macs, iPhone and iPad through your private iCloud.

With ShellHistory you can:

• Search years of shell history in an instant, and filter it by shell, machine, session, directory, exit status or date.
• See a command’s details: when and where it ran, how it ended, how long it took, and every other run of it.
• Explore how you work on the Statistics page: activity over time, success rate, exit codes and what they mean, your busiest hours and days, the slowest and most used commands, and your streak.
• Keep the commands you need in notebooks, with placeholders like {{version}} filled in before you copy.
• Have Apple Intelligence explain a command, on your Mac (macOS 26 or later).
• Find passwords, tokens and keys in your history and delete them on all your devices, and leave them out of new commands.
• Search from the menu bar, Spotlight, Shortcuts and Siri, or press Control-G in your shell to search the directory you’re in.
• Follow your day in a widget.
• Import your existing shell history.

The iPhone and iPad app, included with the App Store purchase, shows the history your Macs sync, with the same search, details, Statistics and notebooks. It doesn’t record commands itself.

ShellHistory needs macOS Sonoma 14.5 or later on the Mac, and iOS or iPadOS 17.5 or later on iPhone and iPad. It is available in English, German, French, Spanish, Italian, Portuguese (Brazil), Ukrainian, Russian, Japanese, Korean and Chinese (Simplified and Traditional); the translations were made with AI.

Release History

3.2.0

• A new shell integration records each command exactly as you typed it, with its exit code, duration and directory, including repeats and multi-line commands. Open Settings › Setup and replace the ShellHistory lines in your shell’s configuration file to use it.
• New commands reach iCloud right after they run.
• A details pane (Command-I) with when and where a command ran, all its runs and your recent runs of it.
• Filters for shell, machine, session, directory, exit status and date, right in the search field.
• Double-click a command to copy it; drag commands into notebooks or other apps; delete one run of a command or every run of it.
• A new Statistics page: activity, success rate, exit codes, busiest hours and days, the slowest and most used commands, mistyped commands and their fixes, and your streak.
• Placeholders in notebooks are filled in when you copy a command.
• Explain Command, with Apple Intelligence on your Mac (macOS 26 or later).
• Find Secrets in History, and leaving secrets out of new commands.
• A widget, Shortcuts, Spotlight and Siri, a menu bar search, and Control-G in your shell.
• On iPhone and iPad: Settings, Sync Now, and layouts for iPad and the iPhone Duo.
• German, French, Spanish, Italian, Portuguese (Brazil), Ukrainian, Russian, Japanese, Korean and Chinese, translated with AI.
• iCloud sync fixes: deleted commands stay deleted on all your devices, and when you sign in with another Apple Account, ShellHistory asks before uploading your history to it.

3.1.0

• Usability and visual updates.

3.0.0

• Statistic view. Allows you to see the top commands you used and the most active dates.
• Redesigned notebooks with more native look for platforms.
• Placeholders in Notebooks.
• Improved iCloud synchronization for notebooks and history.
• Improved security for iCloud containers, storing everything encrypted.
• Compact form for showing history.
• Ability to copy command to clipboard from history with keyboard.
• Support only for macOS Sonoma and up
• (MAS only) iOS and iPadOS build available for viewing history and working with notebooks.

Search Syntax

ShellHistory uses SQLite as storage, and leverages the FTS5 engine for search. You can read more about FTS5 syntax at SQLite FTS5 Extension

There are 4 columns that ShellHistory is using for search:

• cmd - the shell command
• pwd - the working directory
• user - the username
• host - the host (useful if you are syncing history between multiple Macs)

Examples:

• git - searching term git in all the columns
• ^git - searching term git in the beginning of the column values
• gi* - searching terms that start with gi in all the columns
• "rm fr" - searching two terms that are NEAR, search matches rm fr and rm -fR, but not rm --recursive -fR
• git AND commit - search for two terms in the columns, both terms should be present
• git OR svn - search for two terms in the columns, at least one of the terms should be present
• git NOT commit - search for term git but without term commit
• svn OR (git NOT commit) - use parentheses to combine boolean operators
• cmd:git pwd:src - specify columns where you want to search for terms
• -pwd: src AND docker - exclude column “pwd” from search

FAQ

How does it work?

ShellHistory includes a tiny command-line tool, shhist, and a few lines for your shell’s configuration file (Settings › Setup shows them for zsh, bash or fish). They use the shell’s own hooks to hand each command to shhist after it runs, exactly as you typed it, with its exit code, duration and directory, and shhist writes it to the database. They don’t change your prompt.

If you set ShellHistory up before 3.2, replace the ShellHistory lines in your configuration file with the ones Setup shows now: the older lines read the shell’s history list, which leaves out repeated commands and changes some multi-line ones.

Do I need to run ShellHistory in foreground to synchronize via iCloud?

After you enable synchronization with iCloud, ShellHistory starts a tiny background application that backs up and synchronizes history and notebooks in the background. You don’t need to run ShellHistory all the time.

I configured everything, but I don’t see any history in the app?

Please double-check that you picked the shell you use in Setup (echo $SHELL tells you which), that the lines are at the end of the right file, and that you opened a new terminal window afterwards. A framework that replaces the shell’s hooks (preexec and precmd in zsh, PROMPT_COMMAND and the DEBUG trap in bash) can remove ShellHistory’s: try a plain configuration with only the ShellHistory lines, then add the rest back. If you still use the lines from before 3.2, replace them with the ones Setup shows now.

Can I search from terminal?

Absolutely! You can use shhist search in the terminal to find a command you are looking for. That would also allow you to integrate with Alfred and similar tools if you need it.

If you want to open ShellHistory from the terminal just use shhist search-ui. Setup also shows optional lines that bind Control-G to open ShellHistory searching the directory you’re in.

I see a sudo command in your shell integration. Is it safe?

The reason why we run shhist with sudo is to lower the user back to a regular user, if you are in a sudo session. The reason is simple: if you are running commands with the root user we don’t want to break permissions on the ShellHistory database.

How large my history can be?

At the time when I created ShellHistory, I already had close to 100,000 commands in my history.

Is my information safe?

By default, every shell writes history to a text file under your home directory. ShellHistory does something similar, only it writes it to a SQLite database. ShellHistory and the shhist utility are both sandboxed applications, and only have access to a small number of data folders that are available to them.

If you typed a password or a token on the command line, Find Secrets in History (in Settings) finds the commands that look like they hold one, and deletes them on all your devices. With Redact secrets on, ShellHistory replaces recognizable secrets in new commands before they are stored or synced. You can also configure a regular expression that tells ShellHistory which commands to ignore.

If you enabled iCloud synchronization, ShellHistory uses your private iCloud database, in encrypted fields, so only people with access to your Apple Account will be able to access it.

Does ShellHistory capture remote sessions (ssh)?

Not at this moment. It only captures the ssh command itself, but nothing you enter on the remote session. You can always use the import command to do it manually, but there is no automatic support for that. I am not yet planning to implement support for it.

Please take a look at the list of alternatives below if this is important for you.

Is the trial available?

Yes, you can download the trial version from the website using the link above. The trial version is fully functional with alerts and notifications embedded. You can purchase the full version from the App Store or directly from the Loshadki Store.

Difference between App Store and Web version

Purchase of the App Store version includes the iPhone and iPad app. Otherwise, they are identical in functionality.

Can I transfer the license from the App Store to the Web version?

Unfortunately, no. The App Store and Direct versions are separate applications, and there is no way to transfer the license.

Not sure about ShellHistory, could you recommend alternatives?

• dbhist - a shell script that I wrote in 2017 and used since then before I switched to ShellHistory.
• Atuin - open source, cli tool.
• iTerm2 - iTerm2 has shell integration with history

How to troubleshoot the error shhist could not parse inserted string?

This error comes from the lines used before 3.2 (shhist insert). Replacing them with the ones Setup shows now (shhist record) fixes it. If you keep the older lines: shhist tries to autodetect the shell based on the SHELL variable. Sometimes it might not be set correctly if your login shell is different and you launched a shell session from the terminal. You can run shhist insert --help and see what is set by default for the --shell.

One way to fix it is to use chsh to actually change your login shell. Another way is to force and tell shhist which shell you are using with the switch --shell ....

One more issue could be with the history built-in command. If that is an alias, it might not behave as expected. You can check it with type history - it should say history is a shell builtin. If it is something different, please use \ in front of the history command in your configuration like \history that will call the built-in command instead of your alias.

Privacy Policy

We believe very strongly in our customers right to privacy. Our customer records are not for sale or trade, and we will not disclose our customer data to any third party except as may be required by law.

Any information that you provide to us in the course of interacting with our sales or technical support departments is held in strict confidence. This includes your contact information (including, but not limited to your email address and phone number), as well as any data that you supply to us in the course of a technical support interaction.

Support

Please email us any suggestions, ideas, questions or discovered bugs to support@loshadki.app