# Deep Breath CLI
**Deep Breath CLI** is a command-line tool designed to help you relax, regain focus, and boost your energy—right from your terminal.
## 🌬️ What is Deep Breath CLI?
Whether you're coding, studying, or just need a quick break, Deep Breath CLI offers guided breathing exercises with visual progress bars and calming colors. With simple commands, you can access different breathing patterns to help you reset and recharge.
## 🚀 Features
- Multiple breathing patterns (4-7-8, Box breathing)
- Visual progress bars with calming colors
- Customizable session lengths and cycles
- **Track your progress with detailed statistics**
- **Create, modify, and delete custom breathing patterns**
- Clear, distraction-free interface
- Easy preset management
## 🛠️ Installation
Install from PyPI:
```bash
pip install deep-breath-cli
```
## ⚡️ Usage
### Start a breathing session
```bash
# Default session (4 cycles of 4-7-8 pattern)
breath start
# Custom number of cycles
breath start --cycle 8
# Different breathing pattern
breath start --pattern "4-4-4-4"
# Use a custom pattern
breath start --pattern "my-custom"
# Combined options
breath start --cycle 6 --pattern "4-4-4-4"
```
### View available patterns (including custom ones)
```bash
breath presets
```
Output:
```plaintext
Available breathing patterns:
4-7-8: 4s Breathe in..., 7s Hold..., 8s Breathe out... (built-in)
4-4-4-4: 4s Breathe in..., 4s Hold..., 4s Breathe out..., 4s Hold... (built-in)
my-custom: 3s Breathe in..., 5s Hold..., 4s Breathe out... (custom)
You can use these patterns with the --pattern option.
```
## Track your progress
Monitor your breathing journey with detailed statistics:
```bash
# Basic stats overview
breath stats
```
Example output:
```plaintext
Your Breathing Stats
Total sessions: 7
Total time: 2 minutes
Favorite pattern: 4-4-4-4 (2 sessions)
Current streak: 2 days
Use 'breath stats --detailed' for charts and advanced analytics.
```
## Advanced statistics
The `--detailed` flag shows beautiful ASCII charts including:
- **Sessions over last 7 days**: Visual timeline of your daily practice
- **Pattern usage distribution**: See which breathing techniques you use most
```bash
# Detailed view with beautiful ASCII charts
breath stats --detailed
```
## Export your statistics
Export your breathing data for external analysis or backup:
```bash
# Export complete data as JSON
breath export-stats --format json
# Export session data as CSV
breath export-stats --format csv
# Custom output file
breath export-stats --format json --output my_backup.json
```
**CSV Export includes:** Date, Pattern, Cycles, Duration (seconds)
**JSON Export includes:** Complete statistics with all session details
## Custom patterns
Create your own breathing patterns tailored to your needs:
### Create a new pattern
```bash
breath create-pattern "my-custom"
```
This will guide you through an interactive process to define each phase of your breathing pattern.
### Modify an existing pattern
```bash
breath modify-pattern "my-custom"
```
### Delete a pattern
```bash
breath delete-pattern "my-custom"
```
### Get help
```bash
breath --help
breath start --help
```
## 🌟 Breathing Patterns
- **4-7-8**: Relaxation pattern (inhale 4s, hold 7s, exhale 8s)
- **4-4-4-4**: Box breathing for focus (inhale 4s, hold 4s, exhale 4s, hold 4s)
- **Custom patterns**: Create your own with any number of phases and durations
## 🤔 Why use Deep Breath CLI?
- **Quick:** Take a break without leaving your terminal
- **Effective:** Scientifically-backed breathing techniques
- **Customizable:** Choose the pattern and duration that fits your needs
- **Progress tracking:** Monitor your breathing journey with detailed statistics
- **Distraction-free:** Clear your mind with simple, focused interface
## 🛠️ Development
### Setup (with uv, which I used to develop this package)
```bash
git clone https://github.com/weart99/deep-breath-cli
cd deep-breath-cli
uv sync --extra dev
```
### Running tests
```bash
uv run pytest tests/ --cov=src
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and ensure they pass
5. Submit a pull request
## 📄 License
[MIT Licence](https://choosealicense.com/licenses/mit/)
[](https://choosealicense.com/licenses/mit/)
## Authors
[@weart99](https://www.github.com/weart99)
---
Take a deep breath, and let's get started! 🌬️
Raw data
{
"_id": null,
"home_page": null,
"name": "deep-breath-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "breathing, cli, meditation, relaxation, stress, terminal, wellness",
"author": null,
"author_email": "Arthur Parmentier <arthurparmentier99@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5d/4b/cc153e5277e0041e622cd3d1a90e99e42101b2b8df67824fd0f58795398f/deep_breath_cli-1.1.3.tar.gz",
"platform": null,
"description": "# Deep Breath CLI\n\n\n\n\n\n\n\n**Deep Breath CLI** is a command-line tool designed to help you relax, regain focus, and boost your energy\u2014right from your terminal.\n\n## \ud83c\udf2c\ufe0f What is Deep Breath CLI?\n\nWhether you're coding, studying, or just need a quick break, Deep Breath CLI offers guided breathing exercises with visual progress bars and calming colors. With simple commands, you can access different breathing patterns to help you reset and recharge.\n\n## \ud83d\ude80 Features\n\n- Multiple breathing patterns (4-7-8, Box breathing)\n- Visual progress bars with calming colors\n- Customizable session lengths and cycles\n- **Track your progress with detailed statistics**\n- **Create, modify, and delete custom breathing patterns**\n- Clear, distraction-free interface\n- Easy preset management\n\n## \ud83d\udee0\ufe0f Installation\n\nInstall from PyPI:\n\n```bash\npip install deep-breath-cli\n```\n\n## \u26a1\ufe0f Usage\n\n### Start a breathing session\n\n```bash\n# Default session (4 cycles of 4-7-8 pattern)\nbreath start\n\n# Custom number of cycles\nbreath start --cycle 8\n\n# Different breathing pattern\nbreath start --pattern \"4-4-4-4\"\n\n# Use a custom pattern\nbreath start --pattern \"my-custom\"\n\n# Combined options\nbreath start --cycle 6 --pattern \"4-4-4-4\"\n```\n\n### View available patterns (including custom ones)\n\n```bash\nbreath presets\n```\n\nOutput:\n\n```plaintext\nAvailable breathing patterns:\n 4-7-8: 4s Breathe in..., 7s Hold..., 8s Breathe out... (built-in)\n 4-4-4-4: 4s Breathe in..., 4s Hold..., 4s Breathe out..., 4s Hold... (built-in)\n my-custom: 3s Breathe in..., 5s Hold..., 4s Breathe out... (custom)\n\nYou can use these patterns with the --pattern option.\n```\n\n## Track your progress\n\nMonitor your breathing journey with detailed statistics:\n\n```bash\n# Basic stats overview\nbreath stats\n```\n\nExample output:\n\n```plaintext\nYour Breathing Stats\n Total sessions: 7\n Total time: 2 minutes\n Favorite pattern: 4-4-4-4 (2 sessions)\n Current streak: 2 days\n\nUse 'breath stats --detailed' for charts and advanced analytics.\n```\n\n## Advanced statistics\n\nThe `--detailed` flag shows beautiful ASCII charts including:\n\n- **Sessions over last 7 days**: Visual timeline of your daily practice\n- **Pattern usage distribution**: See which breathing techniques you use most\n\n```bash\n# Detailed view with beautiful ASCII charts\nbreath stats --detailed\n```\n\n## Export your statistics\n\nExport your breathing data for external analysis or backup:\n\n```bash\n# Export complete data as JSON\nbreath export-stats --format json\n\n# Export session data as CSV\nbreath export-stats --format csv\n\n# Custom output file\nbreath export-stats --format json --output my_backup.json\n```\n\n**CSV Export includes:** Date, Pattern, Cycles, Duration (seconds) \n**JSON Export includes:** Complete statistics with all session details\n\n## Custom patterns\n\nCreate your own breathing patterns tailored to your needs:\n\n### Create a new pattern\n\n```bash\nbreath create-pattern \"my-custom\"\n```\n\nThis will guide you through an interactive process to define each phase of your breathing pattern.\n\n### Modify an existing pattern\n\n```bash\nbreath modify-pattern \"my-custom\"\n```\n\n### Delete a pattern\n\n```bash\nbreath delete-pattern \"my-custom\"\n```\n\n### Get help\n\n```bash\nbreath --help\nbreath start --help\n```\n\n## \ud83c\udf1f Breathing Patterns\n\n- **4-7-8**: Relaxation pattern (inhale 4s, hold 7s, exhale 8s)\n- **4-4-4-4**: Box breathing for focus (inhale 4s, hold 4s, exhale 4s, hold 4s)\n- **Custom patterns**: Create your own with any number of phases and durations\n\n## \ud83e\udd14 Why use Deep Breath CLI?\n\n- **Quick:** Take a break without leaving your terminal\n- **Effective:** Scientifically-backed breathing techniques\n- **Customizable:** Choose the pattern and duration that fits your needs\n- **Progress tracking:** Monitor your breathing journey with detailed statistics\n- **Distraction-free:** Clear your mind with simple, focused interface\n\n## \ud83d\udee0\ufe0f Development\n\n### Setup (with uv, which I used to develop this package)\n\n```bash\ngit clone https://github.com/weart99/deep-breath-cli\ncd deep-breath-cli\nuv sync --extra dev\n```\n\n### Running tests\n\n```bash\nuv run pytest tests/ --cov=src\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and ensure they pass\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\n[MIT Licence](https://choosealicense.com/licenses/mit/)\n[](https://choosealicense.com/licenses/mit/)\n\n## Authors\n\n[@weart99](https://www.github.com/weart99)\n\n---\n\nTake a deep breath, and let's get started! \ud83c\udf2c\ufe0f\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A command-line tool designed to help you relax from your terminal.",
"version": "1.1.3",
"project_urls": {
"Homepage": "https://github.com/weart99/deep-breath-cli",
"Issues": "https://github.com/weart99/deep-breath-cli/issues",
"Repository": "https://github.com/weart99/deep-breath-cli"
},
"split_keywords": [
"breathing",
" cli",
" meditation",
" relaxation",
" stress",
" terminal",
" wellness"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "278f95e47ea01c4c74959836790d043d48056d63467e26ae83e361cba8521e47",
"md5": "98acf2d3a59112d5686c4f1545957fa9",
"sha256": "d15de03544a0d624dc629bd446cda8b4f0f59b70c7983ccc5637ab403d2fef32"
},
"downloads": -1,
"filename": "deep_breath_cli-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "98acf2d3a59112d5686c4f1545957fa9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10839,
"upload_time": "2025-08-17T16:40:54",
"upload_time_iso_8601": "2025-08-17T16:40:54.230865Z",
"url": "https://files.pythonhosted.org/packages/27/8f/95e47ea01c4c74959836790d043d48056d63467e26ae83e361cba8521e47/deep_breath_cli-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5d4bcc153e5277e0041e622cd3d1a90e99e42101b2b8df67824fd0f58795398f",
"md5": "5c6b4c1b6b14675c790310c6a6287512",
"sha256": "85028cee24c00a7822f98b2c50843183a88b6edd984192a089bb4b09e405eb4a"
},
"downloads": -1,
"filename": "deep_breath_cli-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "5c6b4c1b6b14675c790310c6a6287512",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 25927,
"upload_time": "2025-08-17T16:40:55",
"upload_time_iso_8601": "2025-08-17T16:40:55.324214Z",
"url": "https://files.pythonhosted.org/packages/5d/4b/cc153e5277e0041e622cd3d1a90e99e42101b2b8df67824fd0f58795398f/deep_breath_cli-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 16:40:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "weart99",
"github_project": "deep-breath-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "deep-breath-cli"
}
JSON
