historikeeper

A ZSH plugin that captures history in a database
Explore the docs »

Report Bug · Request Feature

Table of Contents

• Table of Contents
• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements

About The Project

Built With

• Zsh
• PostgreSQL
• SQLite
• Docker
• Python

---

Getting Started

Prerequisites

• Docker
• PostgreSQL client (optional, for manual access to the database)
• SQLite (optional, for local file-based logging)
• Python 3.6+
• pip (Python package installer)

Installation

1. Clone the repo

   git clone https://github.com/stiliajohny/historikeeper.git \$ZSH_CUSTOM/plugins/historikeeper

2. Deploy PostgreSQL with Docker (optional if using PostgreSQL)

   docker pull postgres
   docker run --name postgres-db -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword -e POSTGRES_DB=historykeeper -p 5432:5432 -d postgres

3. Install Python dependencies

   pip install -r \$ZSH_CUSTOM/plugins/historikeeper/requirements.txt

4. Add the plugin to your .zshrc configuration

   plugins=(... historikeeper)

5. Set variables in your .zshrc

   HISTORIKEEPER_PRINT_DETAILS=true
   HISTORIKEEPER_LOG_METHOD="postgres" # Options: "postgres" or "sqlite"
   # if postgress is used then set the following variables
   PG_HOST=localhost
   PG_PORT=5432
   PG_USER=postgres
   PG_DB=historykeeper
   PG_PASSWORD=mysecretpassword
   # if sqlite is used then set the following variables
   SQLITE_DB_PATH=~/.zsh_history.db

6. Source your .zshrc to apply the changes

   source ~/.zshrc

---

Usage

Import existing history

1. CD in the plugin folder

   cd \$ZSH_CUSTOM/plugins/historikeeper/

2. Run the import command

   python3 ./parse_zsh_history.py -vvvv --input-file ~/.zsh_history --pg-host localhost --pg-port 5432 --pg-user postgres --pg-password mysecretpassword --pg-db historykeeper

Normal Plugin Usage

The plugin captures each command run in your terminal and logs it to the specified database method (PostgreSQL or SQLite) based on the value of HISTORIKEEPER_LOG_METHOD.

You can view the details of the last command executed directly in your terminal if HISTORIKEEPER_PRINT_DETAILS is set to true.

Example of what is captured:

johnstilia in ~/.config/oh-my-zsh/custom/plugins/historikeeper on master ● ● λ ls
HistoriKeeper.plugin.zsh LICENSE.txt              README.md                _config.yml
>--------------------------------------------------
Last Command Details:
Epoch Timestamp: 1721927239
Timestamp: 2024-07-25T18:07:19+0100
Command: ls
Command Arguments:
Exit Code: 0
Execution Time (milliseconds): 12
Hostname: Johns-MacBook-Pro.local
Username: johnstilia
Output:
HistoriKeeper.plugin.zsh
LICENSE.txt
README.md
_config.yml
IP Address: Johns-MacBook-Pro.local
PPID: 58531
TTY: /dev/ttys055
Working Directory: /Users/johnstilia/.config/oh-my-zsh/custom/plugins/historikeeper
Shell Type: /bin/zsh
Session Start Time: 2024-07-25T18:07:17+0100
Public IP Address: 152.37.89.249
Public Hostname: 89.37.152.249.bcube.co.uk
>--------------------------------------------------
Toggling Variables:
HISTORIKEEPER_PRINT_DETAILS: true
HISTORIKEEPER_LOG_METHOD: postgres
>--------------------------------------------------

---

Roadmap

See the open issues for a list of proposed features (and known issues).

---

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

License

Distributed under the GPLv3 License. See LICENSE for more information.

Contact

John Stilia - stilia.johny@gmail.com

---

Acknowledgements

• GitHub Emoji Cheat Sheet
• Img Shields
• Choose an Open Source License
• GitHub Pages