# ð Shelldog - Your Faithful Command Companion
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
> *Your loyal companion for tracking shell commands - because every good developer needs a faithful friend who remembers everything!*
```
/\_/\
( o.o )
> ^ < "Woof! I'm watching... silently."
```
**Shelldog** is a silent, intelligent command tracker for your terminal. Think of it as your development diary that writes itself - tracking every command you run, so you never have to remember "what did I do yesterday?" ever again!
## ðŊ Why Shelldog?
Ever found yourself thinking:
- "What was that curl command I ran last week?"
- "How did I set up this environment again?"
- "I need to write documentation... if only I could remember what I did!"
- "What commands did I run before that bug appeared?"
**Shelldog sits quietly in the background and remembers EVERYTHING for you!** ð§
### âĻ Features
- ðĪŦ **Silent Tracking** - Works invisibly without cluttering your terminal
- ð **Privacy First** - Automatically masks passwords, tokens, and API keys
- ðŊ **Smart Detection** - Knows when you're in a virtual environment
- ð **Project-Level Logs** - Each venv gets its own history file at the project root
- ð **Personality** - Because who says CLI tools have to be boring?
- ð **Zero Performance Impact** - Logs asynchronously in the background
- ð **Both Bash & Zsh** - Works with your favorite shell
## ðĶ Installation
### Quick Install
```bash
pip install shelldog
```
### From Source
```bash
git clone https://github.com/Ansumanbhujabal/shelldog.git
cd shelldog
pip install -e .
```
## ð Quick Start
### 1. Start Tracking
```bash
# Wake up the dog!
shelldog follow
# Activate tracking in your current shell
eval "$(shelldog follow -q)"
```
That's it! Shelldog is now silently logging all your commands. ð
### 2. View Your History
```bash
# See everything
shelldog log
# Just today's commands
shelldog log --today
# Last 20 commands
shelldog log -n 20
```
### 3. Check Status
```bash
shelldog status
```
## ðŪ Commands
### Core Commands
| Command | Description |
|---------|-------------|
| `shelldog follow` | Start tracking commands (activates the good boy!) |
| `shelldog stop` | Stop tracking (sends doggo to sleep) |
| `shelldog log` | View command history |
| `shelldog status` | Check if Shelldog is watching |
| `shelldog clear` | Clear command history |
| `shelldog stats` | See cool statistics about your commands |
### Fun Commands (Because Why Not?)
| Command | Description |
|---------|-------------|
| `shelldog bark` | Make Shelldog bark! ð |
| `shelldog treat` | Give Shelldog a treat! ðĶī |
| `shelldog goodboy` | Tell Shelldog he's a good boy! ð |
## ð§ How It Works
### The Magic Behind the Scenes
1. **Shell Hook**: Shelldog installs a tiny hook in your shell (via `DEBUG` trap in Bash or `preexec` in Zsh)
2. **Silent Logger**: Every command gets logged asynchronously - zero impact on your workflow
3. **Smart Masking**: Sensitive data (passwords, tokens, API keys) are automatically masked
4. **Venv Detection**: Automatically detects if you're in a virtual environment
### Virtual Environment Awareness
When you're in a virtual environment:
- Shelldog creates `shelldog_history.txt` at your **project root** (next to your venv folder)
- Each project gets its own command history
- No more mixing up commands from different projects!
```
my-project/
âââ venv/
â âââ .shelldog/ # Hidden config folder
âââ shelldog_history.txt # Your project's command history! ð
âââ src/
âââ README.md
```
### Privacy & Security
Shelldog automatically masks sensitive information:
```bash
# What you type:
export API_KEY=super_secret_key_123
# What gets logged:
export API_KEY=****
```
Protected patterns:
- `export VARNAME=value` â `export VARNAME=****`
- `--password`, `--token`, `--api-key`, `--secret`
- Authorization headers in curl commands
- And more!
## ðĄ Usage Examples
### Example 1: Track Your Development Session
```bash
# Start your day
cd my-project
source venv/bin/activate
eval "$(shelldog follow -q)"
# Do your work
git pull origin main
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
# Later, review what you did
shelldog log --today
```
### Example 2: Debug Like a Pro
```bash
# Something broke! What did you do?
shelldog log -n 50
# Find that specific command
shelldog log | grep docker
# See statistics
shelldog stats
```
### Example 3: Document Your Setup
```bash
# After setting up a new environment
shelldog log > SETUP.md
# Now you have automatic documentation! ð
```
## ðĻ Example Output
### Starting Shelldog
```bash
$ shelldog follow
ð Woof! I'm watching you.
Never forget what you did.
Always know where you've been.
I've got your back.
â Shelldog is now following your commands!
ð Commands will be logged to:
/path/to/project/shelldog_history.txt
ðŊ Project root level logging!
ð Stay pawsitive! ðū
============================================================
â Initialization complete!
============================================================
ð Activate the hook by running:
eval "$(shelldog follow -q)"
```
### Viewing History
```bash
$ shelldog log -n 5
ð Shelldog History:
================================================================================
[2025-10-08 14:23:45] pip install requests
[2025-10-08 14:24:12] python app.py
[2025-10-08 14:25:33] git add .
[2025-10-08 14:25:40] git commit -m "Add new feature"
[2025-10-08 14:25:55] git push origin main
================================================================================
ð Total entries: 5
ð *proud tail wag* I remembered everything!
```
### Status Check
```bash
$ shelldog status
ð Shelldog Status:
==================================================
Tracking enabled: â Yes
Shell hook active: â Yes
Virtual env: â Yes (venv-specific logging)
Venv path: /opt/CodeRepo/SideProjects/shelldog/venv
Log file: /opt/CodeRepo/SideProjects/shelldog/shelldog_history.txt
Log file exists: â Yes
Logged commands: 247
==================================================
â Shelldog is actively tracking your commands! ð
Every great developer was once a beginner! ð
```
## âïļ Configuration
### Log File Locations
- **In a venv**: `<project_root>/shelldog_history.txt`
- **Global**: `~/.shelldog/shelldog_history.txt`
### State Files
Shelldog keeps its configuration in:
- **In a venv**: `<venv>/.shelldog/`
- **Global**: `~/.shelldog/`
## ðĪ Shell Integration
### Manual Activation
If you want to manually control when Shelldog watches:
```bash
# Start tracking
source ~/.shelldog/shelldog_hook.sh
# Stop tracking
source ~/.shelldog/shelldog_unhook.sh
```
### Add to Shell Profile (Optional)
Want Shelldog to start automatically? Add to your `~/.bashrc` or `~/.zshrc`:
```bash
# Auto-start Shelldog in virtual environments
if [[ -n "$VIRTUAL_ENV" ]]; then
eval "$(shelldog follow -q)" 2>/dev/null
fi
```
## ð Troubleshooting
### "Shelldog is enabled but not logging!"
Make sure the hook is active:
```bash
shelldog status
# If hook is not active, run:
eval "$(shelldog follow -q)"
```
### "Commands are logged twice!"
This can happen if you source the hook multiple times. Run:
```bash
shelldog stop
eval "$(shelldog follow -q)"
```
### "Shelldog logs its own commands!"
It shouldn't! Shelldog filters itself out. If you see this, please file a bug report! ð
## ð What Gets Logged?
### â
Logged
- All shell commands
- Script executions
- Git commands
- Package installations
- Database migrations
- Server starts/stops
- Basically everything you type!
### â Not Logged
- `shelldog` commands themselves
- Internal shell functions
- Empty commands
- Shell initialization stuff
## ð Pro Tips
1. **Review Daily**: `shelldog log --today` at the end of the day
2. **Document Projects**: `shelldog log > COMMANDS.md` for documentation
3. **Debug Sessions**: `shelldog log -n 50` to see recent commands
4. **Find Patterns**: `shelldog stats` to see your most-used commands
5. **Clean Slate**: `shelldog clear` when starting fresh
## ðĪ FAQ
**Q: Does Shelldog slow down my terminal?**
A: Nope! Logging happens asynchronously in the background. Zero performance impact.
**Q: Is my sensitive data safe?**
A: Yes! Shelldog automatically masks passwords, tokens, and API keys.
**Q: Can I use this in production?**
A: Shelldog is designed for development environments. Use caution in production!
**Q: Does it work with tmux/screen?**
A: Yes! Each session tracks independently.
**Q: What shells are supported?**
A: Bash and Zsh are fully supported.
## ðĻ Why the Dog Theme?
Because:
1. Dogs are loyal (like your command history should be)
2. Dogs remember everything (especially treats)
3. Dogs are always happy to help
4. CLI tools deserve more personality! ð
## ð License
MIT License - See LICENSE file for details
## ðĪ Contributing
Contributions are welcome! Feel free to:
- ð Report bugs
- ðĄ Suggest features
- ð§ Submit pull requests
- ðĻ Improve documentation
## ð Acknowledgments
Built with âĪïļ by developers who got tired of asking "wait, what command did I just run?"
---
<div align="center">
**Made with ð and â by Ansuman Bhujabala**
If Shelldog helps you, give him a treat! â this repo
```
ð *tail wagging intensifies*
```
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/Ansumanbhujabal/shelldog",
"name": "shelldog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "shell, terminal, command, history, tracking, logger, development, cli, bash, zsh",
"author": "Ansuman Bhujabala",
"author_email": "Ansuman Bhujabala <ansumanbhujabala@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/16/12/389d0cad0722a4e53d39707653015d0f184d6bbb086ab837dabbc85113b7/shelldog-0.1.0.tar.gz",
"platform": null,
"description": "# \ud83d\udc15 Shelldog - Your Faithful Command Companion\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/psf/black)\n\n> *Your loyal companion for tracking shell commands - because every good developer needs a faithful friend who remembers everything!*\n\n```\n /\\_/\\ \n ( o.o ) \n > ^ < \"Woof! I'm watching... silently.\"\n```\n\n**Shelldog** is a silent, intelligent command tracker for your terminal. Think of it as your development diary that writes itself - tracking every command you run, so you never have to remember \"what did I do yesterday?\" ever again!\n\n## \ud83c\udfaf Why Shelldog?\n\nEver found yourself thinking:\n- \"What was that curl command I ran last week?\"\n- \"How did I set up this environment again?\"\n- \"I need to write documentation... if only I could remember what I did!\"\n- \"What commands did I run before that bug appeared?\"\n\n**Shelldog sits quietly in the background and remembers EVERYTHING for you!** \ud83e\udde0\n\n### \u2728 Features\n\n- \ud83e\udd2b **Silent Tracking** - Works invisibly without cluttering your terminal\n- \ud83d\udd12 **Privacy First** - Automatically masks passwords, tokens, and API keys\n- \ud83c\udfaf **Smart Detection** - Knows when you're in a virtual environment\n- \ud83d\udcc1 **Project-Level Logs** - Each venv gets its own history file at the project root\n- \ud83c\udfad **Personality** - Because who says CLI tools have to be boring?\n- \ud83d\ude80 **Zero Performance Impact** - Logs asynchronously in the background\n- \ud83c\udf08 **Both Bash & Zsh** - Works with your favorite shell\n\n## \ud83d\udce6 Installation\n\n### Quick Install\n\n```bash\npip install shelldog\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/Ansumanbhujabal/shelldog.git\ncd shelldog\npip install -e .\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Start Tracking\n\n```bash\n# Wake up the dog!\nshelldog follow\n\n# Activate tracking in your current shell\neval \"$(shelldog follow -q)\"\n```\n\nThat's it! Shelldog is now silently logging all your commands. \ud83c\udf89\n\n### 2. View Your History\n\n```bash\n# See everything\nshelldog log\n\n# Just today's commands\nshelldog log --today\n\n# Last 20 commands\nshelldog log -n 20\n```\n\n### 3. Check Status\n\n```bash\nshelldog status\n```\n\n## \ud83c\udfae Commands\n\n### Core Commands\n\n| Command | Description |\n|---------|-------------|\n| `shelldog follow` | Start tracking commands (activates the good boy!) |\n| `shelldog stop` | Stop tracking (sends doggo to sleep) |\n| `shelldog log` | View command history |\n| `shelldog status` | Check if Shelldog is watching |\n| `shelldog clear` | Clear command history |\n| `shelldog stats` | See cool statistics about your commands |\n\n### Fun Commands (Because Why Not?)\n\n| Command | Description |\n|---------|-------------|\n| `shelldog bark` | Make Shelldog bark! \ud83d\udc15 |\n| `shelldog treat` | Give Shelldog a treat! \ud83e\uddb4 |\n| `shelldog goodboy` | Tell Shelldog he's a good boy! \ud83c\udfc6 |\n\n## \ud83d\udd27 How It Works\n\n### The Magic Behind the Scenes\n\n1. **Shell Hook**: Shelldog installs a tiny hook in your shell (via `DEBUG` trap in Bash or `preexec` in Zsh)\n2. **Silent Logger**: Every command gets logged asynchronously - zero impact on your workflow\n3. **Smart Masking**: Sensitive data (passwords, tokens, API keys) are automatically masked\n4. **Venv Detection**: Automatically detects if you're in a virtual environment\n\n### Virtual Environment Awareness\n\nWhen you're in a virtual environment:\n- Shelldog creates `shelldog_history.txt` at your **project root** (next to your venv folder)\n- Each project gets its own command history\n- No more mixing up commands from different projects!\n\n```\nmy-project/\n\u251c\u2500\u2500 venv/\n\u2502 \u2514\u2500\u2500 .shelldog/ # Hidden config folder\n\u251c\u2500\u2500 shelldog_history.txt # Your project's command history! \ud83d\udcdd\n\u251c\u2500\u2500 src/\n\u2514\u2500\u2500 README.md\n```\n\n### Privacy & Security\n\nShelldog automatically masks sensitive information:\n\n```bash\n# What you type:\nexport API_KEY=super_secret_key_123\n\n# What gets logged:\nexport API_KEY=****\n```\n\nProtected patterns:\n- `export VARNAME=value` \u2192 `export VARNAME=****`\n- `--password`, `--token`, `--api-key`, `--secret`\n- Authorization headers in curl commands\n- And more!\n\n## \ud83d\udca1 Usage Examples\n\n### Example 1: Track Your Development Session\n\n```bash\n# Start your day\ncd my-project\nsource venv/bin/activate\neval \"$(shelldog follow -q)\"\n\n# Do your work\ngit pull origin main\npip install -r requirements.txt\npython manage.py migrate\npython manage.py runserver\n\n# Later, review what you did\nshelldog log --today\n```\n\n### Example 2: Debug Like a Pro\n\n```bash\n# Something broke! What did you do?\nshelldog log -n 50\n\n# Find that specific command\nshelldog log | grep docker\n\n# See statistics\nshelldog stats\n```\n\n### Example 3: Document Your Setup\n\n```bash\n# After setting up a new environment\nshelldog log > SETUP.md\n\n# Now you have automatic documentation! \ud83d\udcda\n```\n\n## \ud83c\udfa8 Example Output\n\n### Starting Shelldog\n\n```bash\n$ shelldog follow\n\n\ud83d\udc15 Woof! I'm watching you.\n\n Never forget what you did.\n Always know where you've been.\n I've got your back.\n\n\u2713 Shelldog is now following your commands!\n\n\ud83d\udcdd Commands will be logged to:\n /path/to/project/shelldog_history.txt\n \ud83c\udfaf Project root level logging!\n\n\ud83c\udf89 Stay pawsitive! \ud83d\udc3e\n============================================================\n\n\u2713 Initialization complete!\n============================================================\n\n\ud83d\udc15 Activate the hook by running:\n eval \"$(shelldog follow -q)\"\n```\n\n### Viewing History\n\n```bash\n$ shelldog log -n 5\n\n\ud83d\udc15 Shelldog History:\n\n================================================================================\n[2025-10-08 14:23:45] pip install requests\n[2025-10-08 14:24:12] python app.py\n[2025-10-08 14:25:33] git add .\n[2025-10-08 14:25:40] git commit -m \"Add new feature\"\n[2025-10-08 14:25:55] git push origin main\n================================================================================\n\n\ud83d\udcca Total entries: 5\n\ud83d\udc15 *proud tail wag* I remembered everything!\n```\n\n### Status Check\n\n```bash\n$ shelldog status\n\n\ud83d\udc15 Shelldog Status:\n\n==================================================\nTracking enabled: \u2713 Yes\nShell hook active: \u2713 Yes\nVirtual env: \u2713 Yes (venv-specific logging)\nVenv path: /opt/CodeRepo/SideProjects/shelldog/venv\nLog file: /opt/CodeRepo/SideProjects/shelldog/shelldog_history.txt\nLog file exists: \u2713 Yes\nLogged commands: 247\n==================================================\n\n\u2713 Shelldog is actively tracking your commands! \ud83d\udc15\n Every great developer was once a beginner! \ud83c\udf1f\n```\n\n## \u2699\ufe0f Configuration\n\n### Log File Locations\n\n- **In a venv**: `<project_root>/shelldog_history.txt`\n- **Global**: `~/.shelldog/shelldog_history.txt`\n\n### State Files\n\nShelldog keeps its configuration in:\n- **In a venv**: `<venv>/.shelldog/`\n- **Global**: `~/.shelldog/`\n\n## \ud83e\udd1d Shell Integration\n\n### Manual Activation\n\nIf you want to manually control when Shelldog watches:\n\n```bash\n# Start tracking\nsource ~/.shelldog/shelldog_hook.sh\n\n# Stop tracking\nsource ~/.shelldog/shelldog_unhook.sh\n```\n\n### Add to Shell Profile (Optional)\n\nWant Shelldog to start automatically? Add to your `~/.bashrc` or `~/.zshrc`:\n\n```bash\n# Auto-start Shelldog in virtual environments\nif [[ -n \"$VIRTUAL_ENV\" ]]; then\n eval \"$(shelldog follow -q)\" 2>/dev/null\nfi\n```\n\n## \ud83d\udc1b Troubleshooting\n\n### \"Shelldog is enabled but not logging!\"\n\nMake sure the hook is active:\n\n```bash\nshelldog status\n\n# If hook is not active, run:\neval \"$(shelldog follow -q)\"\n```\n\n### \"Commands are logged twice!\"\n\nThis can happen if you source the hook multiple times. Run:\n\n```bash\nshelldog stop\neval \"$(shelldog follow -q)\"\n```\n\n### \"Shelldog logs its own commands!\"\n\nIt shouldn't! Shelldog filters itself out. If you see this, please file a bug report! \ud83d\udc1b\n\n## \ud83d\udcdd What Gets Logged?\n\n### \u2705 Logged\n- All shell commands\n- Script executions\n- Git commands\n- Package installations\n- Database migrations\n- Server starts/stops\n- Basically everything you type!\n\n### \u274c Not Logged\n- `shelldog` commands themselves\n- Internal shell functions\n- Empty commands\n- Shell initialization stuff\n\n## \ud83c\udf93 Pro Tips\n\n1. **Review Daily**: `shelldog log --today` at the end of the day\n2. **Document Projects**: `shelldog log > COMMANDS.md` for documentation\n3. **Debug Sessions**: `shelldog log -n 50` to see recent commands\n4. **Find Patterns**: `shelldog stats` to see your most-used commands\n5. **Clean Slate**: `shelldog clear` when starting fresh\n\n## \ud83e\udd14 FAQ\n\n**Q: Does Shelldog slow down my terminal?** \nA: Nope! Logging happens asynchronously in the background. Zero performance impact.\n\n**Q: Is my sensitive data safe?** \nA: Yes! Shelldog automatically masks passwords, tokens, and API keys.\n\n**Q: Can I use this in production?** \nA: Shelldog is designed for development environments. Use caution in production!\n\n**Q: Does it work with tmux/screen?** \nA: Yes! Each session tracks independently.\n\n**Q: What shells are supported?** \nA: Bash and Zsh are fully supported.\n\n## \ud83c\udfa8 Why the Dog Theme?\n\nBecause:\n1. Dogs are loyal (like your command history should be)\n2. Dogs remember everything (especially treats)\n3. Dogs are always happy to help\n4. CLI tools deserve more personality! \ud83c\udf89\n\n## \ud83d\udcc4 License\n\nMIT License - See LICENSE file for details\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Feel free to:\n- \ud83d\udc1b Report bugs\n- \ud83d\udca1 Suggest features\n- \ud83d\udd27 Submit pull requests\n- \ud83c\udfa8 Improve documentation\n\n## \ud83d\ude4f Acknowledgments\n\nBuilt with \u2764\ufe0f by developers who got tired of asking \"wait, what command did I just run?\"\n\n---\n\n<div align=\"center\">\n\n**Made with \ud83d\udc15 and \u2615 by Ansuman Bhujabala**\n\nIf Shelldog helps you, give him a treat! \u2b50 this repo\n\n```\n\ud83d\udc15 *tail wagging intensifies*\n```\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "\ud83d\udc15 Your loyal companion for tracking shell commands - silent, smart, and adorable!",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Ansumanbhujabal/shelldog/issues",
"Documentation": "https://github.com/Ansumanbhujabal/shelldog/blob/main/README.md",
"Homepage": "https://github.com/Ansumanbhujabal/shelldog",
"Source Code": "https://github.com/Ansumanbhujabal/shelldog"
},
"split_keywords": [
"shell",
" terminal",
" command",
" history",
" tracking",
" logger",
" development",
" cli",
" bash",
" zsh"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "10ac38e91ce4433e15c23422745159666f4ea934c01165cf20b306279dda0068",
"md5": "fb1b6d4bf7eecb7e4312326978ebb520",
"sha256": "f57726bd226888007729dc6ab478f62b02e44307c32aab860ace7b040b2b76f9"
},
"downloads": -1,
"filename": "shelldog-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb1b6d4bf7eecb7e4312326978ebb520",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13672,
"upload_time": "2025-10-08T19:37:35",
"upload_time_iso_8601": "2025-10-08T19:37:35.867414Z",
"url": "https://files.pythonhosted.org/packages/10/ac/38e91ce4433e15c23422745159666f4ea934c01165cf20b306279dda0068/shelldog-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1612389d0cad0722a4e53d39707653015d0f184d6bbb086ab837dabbc85113b7",
"md5": "42fa013c07b65c69ed3ebae06408d7df",
"sha256": "5a84ed13b836ac7f4806670e7d7a28ed1b873d1e23dae8977c52d0da1959fd3e"
},
"downloads": -1,
"filename": "shelldog-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "42fa013c07b65c69ed3ebae06408d7df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19368,
"upload_time": "2025-10-08T19:37:37",
"upload_time_iso_8601": "2025-10-08T19:37:37.936765Z",
"url": "https://files.pythonhosted.org/packages/16/12/389d0cad0722a4e53d39707653015d0f184d6bbb086ab837dabbc85113b7/shelldog-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 19:37:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ansumanbhujabal",
"github_project": "shelldog",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
}
],
"lcname": "shelldog"
}
JSON
