# Sage
Sage is an easy-to-use command line timer that looks good and adheres
to your human inclinations about the language of time. Use natural
language like "25m" or "1 hour 30 minutes" when running timers, or
create preset timers that can be called with names like "pomodoro".
*Sage integrated into a development workflow.*
## Quick Start
1. Install Sage globally with [pipx](https://github.com/pypa/pipx).
```bash
pipx install sage-timer
```
2. Start a timer or stopwatch.
```bash
sage timer 35m # Start a 35 minute timer
sage stopwatch # Start a stopwatch
```
## Installation
Sage requires Python 3.10+. Installation with [pipx](https://github.com/pypa/pipx)
is recommended:
```bash
pipx install sage-timer
```
pipx is designed for installing command-line tools like Sage. It
creates an isolated environment for each tool, preventing dependency
conflicts while making the `sage` command globally available.
Alternatively, you can use pip or other PyPI-based package managers:
```bash
pip install sage-timer
```
## Usage
### Timer
*A running Sage timer.*
#### Run A Timer
Sage recognizes flexible, human-readable time formats across multiple
styles that match however you naturally express time.
```bash
sage timer 25m # Start a 25 minute timer
sage timer "10 minutes 30 seconds" # Start a 10 minute 30 second timer
sage timer 3min25s # Start a 3 minute 25 second
```
It also accepts custom timer names. A list of built-in timers can be
found with `sage list`.
```bash
sage timer pomodoro # Start a 25 minute timer
```
#### Let A Timer Complete Quietly
Use the `--quiet` flag to let the timer complete without a sound.
```bash
sage timer 7m --quiet
```
#### Custom Timers
Create custom timers and run them with `sage timer`.
```bash
sage create workout 1hr # Create 1 hour workout timer
sage timer workout # Start workout timer
```
#### Managing Custom Timers
Custom timers are managed with the following commands:
```bash
sage list # List all available timers
sage create <name> <duration> # Create a new timer
sage update <name> <duration> # Update existing timer
sage rename <name> <new_name> # Rename a timer
sage delete <name> # Delete a timer
```
To better illustrate their use, a comprehensive workflow with Sage's
management commands would look something like this.
```bash
sage create workout 45m # Create 45 minute workout timer
sage update workout 1hr # Update workout timer to 1 hour
sage rename workout yoga # Rename workout timer name to yoga
sage timer yoga # Start 1 hour yoga timer
sage delete yoga # Delete yoga timer
```
### Stopwatch
*A running Sage stopwatch, with centisecond precision.*
#### Run A Stopwatch
Sage provides precise time tracking with centisecond accuracy for
activities with unknown duration.
```bash
sage stopwatch # Start a stopwatch immediately
```
### Clock Controls
Once running, both the timer and stopwatch can be controlled with the
following simple keystrokes:
- **Space** - Pause and resume
- **Enter** - Increment counter
- **Q** - Quit
### The Counter
The Sage timer and stopwatch include a counter which can be used to track
laps, counts, reps, etc. Just press `Enter` to increment while in the
clock interface.
### Load A Clock Without Starting
*Built-in potato timer, loaded in a paused state.*
The `timer` and `stopwatch` commands accept a `--paused` flag that will
load the clock in a paused state. Once the clock is loaded, a "Paused"
message will appear beneath the clock time and the clock will wait for
the `Space` key to start.
```bash
sage timer 25m --paused # Load timer in paused state
sage stopwatch --paused # Load stopwatch in paused state
```
## Philosophy
Most CLI tools prioritize technical precision over human usability,
making them inaccessible to casual users. Sage was built out of a
desire to prove that command line applications can be both powerful
and intuitive, using natural language processing and a simple UX
design.
## License
MIT License - see [LICENSE](https://github.com/nmsalvatore/sage/blob/main/LICENSE) file for details.
## Contributing
Contributions welcome! Please feel free to submit issues and pull requests.
Raw data
{
"_id": null,
"home_page": null,
"name": "sage-timer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cli, curses, pomodoro, productivity, stopwatch, terminal, timer",
"author": null,
"author_email": "Nicholas Salvatore <nmsalvatore@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/0b/352a17168113c1afd0a5f6bb332abc7488c7c7e07a8bbde7bdef33684b9f/sage_timer-0.1.2.tar.gz",
"platform": null,
"description": "# Sage\n\n\n\nSage is an easy-to-use command line timer that looks good and adheres\nto your human inclinations about the language of time. Use natural\nlanguage like \"25m\" or \"1 hour 30 minutes\" when running timers, or\ncreate preset timers that can be called with names like \"pomodoro\".\n\n*Sage integrated into a development workflow.*\n\n\n\n## Quick Start\n\n1. Install Sage globally with [pipx](https://github.com/pypa/pipx).\n\n```bash\npipx install sage-timer\n```\n\n2. Start a timer or stopwatch.\n\n```bash\nsage timer 35m # Start a 35 minute timer\nsage stopwatch # Start a stopwatch\n```\n\n## Installation\n\nSage requires Python 3.10+. Installation with [pipx](https://github.com/pypa/pipx)\nis recommended:\n\n```bash\npipx install sage-timer\n```\n\npipx is designed for installing command-line tools like Sage. It\ncreates an isolated environment for each tool, preventing dependency\nconflicts while making the `sage` command globally available.\n\nAlternatively, you can use pip or other PyPI-based package managers:\n\n```bash\npip install sage-timer\n```\n\n## Usage\n\n### Timer\n\n*A running Sage timer.*\n\n\n\n#### Run A Timer\n\nSage recognizes flexible, human-readable time formats across multiple\nstyles that match however you naturally express time.\n\n```bash\nsage timer 25m # Start a 25 minute timer\nsage timer \"10 minutes 30 seconds\" # Start a 10 minute 30 second timer\nsage timer 3min25s # Start a 3 minute 25 second\n```\n\nIt also accepts custom timer names. A list of built-in timers can be\nfound with `sage list`.\n\n```bash\nsage timer pomodoro # Start a 25 minute timer\n```\n\n#### Let A Timer Complete Quietly\n\nUse the `--quiet` flag to let the timer complete without a sound.\n\n```bash\nsage timer 7m --quiet\n```\n\n#### Custom Timers\n\nCreate custom timers and run them with `sage timer`.\n\n```bash\nsage create workout 1hr # Create 1 hour workout timer\nsage timer workout # Start workout timer\n```\n\n#### Managing Custom Timers\n\nCustom timers are managed with the following commands:\n\n```bash\nsage list # List all available timers\nsage create <name> <duration> # Create a new timer\nsage update <name> <duration> # Update existing timer\nsage rename <name> <new_name> # Rename a timer\nsage delete <name> # Delete a timer\n```\n\nTo better illustrate their use, a comprehensive workflow with Sage's\nmanagement commands would look something like this.\n\n```bash\nsage create workout 45m # Create 45 minute workout timer\nsage update workout 1hr # Update workout timer to 1 hour\nsage rename workout yoga # Rename workout timer name to yoga\nsage timer yoga # Start 1 hour yoga timer\nsage delete yoga # Delete yoga timer\n```\n\n### Stopwatch\n\n*A running Sage stopwatch, with centisecond precision.*\n\n\n\n#### Run A Stopwatch\n\nSage provides precise time tracking with centisecond accuracy for\nactivities with unknown duration.\n\n```bash\nsage stopwatch # Start a stopwatch immediately\n```\n\n### Clock Controls\n\nOnce running, both the timer and stopwatch can be controlled with the\nfollowing simple keystrokes:\n\n- **Space** - Pause and resume\n- **Enter** - Increment counter\n- **Q** - Quit\n\n### The Counter\n\nThe Sage timer and stopwatch include a counter which can be used to track\nlaps, counts, reps, etc. Just press `Enter` to increment while in the\nclock interface.\n\n### Load A Clock Without Starting\n\n*Built-in potato timer, loaded in a paused state.*\n\n\n\nThe `timer` and `stopwatch` commands accept a `--paused` flag that will\nload the clock in a paused state. Once the clock is loaded, a \"Paused\"\nmessage will appear beneath the clock time and the clock will wait for\nthe `Space` key to start.\n\n```bash\nsage timer 25m --paused # Load timer in paused state\nsage stopwatch --paused # Load stopwatch in paused state\n```\n\n## Philosophy\n\nMost CLI tools prioritize technical precision over human usability,\nmaking them inaccessible to casual users. Sage was built out of a\ndesire to prove that command line applications can be both powerful\nand intuitive, using natural language processing and a simple UX\ndesign.\n\n## License\n\nMIT License - see [LICENSE](https://github.com/nmsalvatore/sage/blob/main/LICENSE) file for details.\n\n## Contributing\n\nContributions welcome! Please feel free to submit issues and pull requests.\n",
"bugtrack_url": null,
"license": null,
"summary": "Sage is an easy-to-use command line timer that looks good and accepts natural language time formats.",
"version": "0.1.2",
"project_urls": {
"Issues": "https://github.com/nmsalvatore/sage/issues",
"Repository": "https://github.com/nmsalvatore/sage"
},
"split_keywords": [
"cli",
" curses",
" pomodoro",
" productivity",
" stopwatch",
" terminal",
" timer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7a2ab4831fbbd4c0a2a7a205891c5901d5bd8be0bf53f8a58c1c27f9303c7a8f",
"md5": "d8d6092e27802fe1082e548fdbd81daf",
"sha256": "c9d38000f852fd1d33e3421a2b7dd531e22f7f291977d8d19549a5502e7c93c1"
},
"downloads": -1,
"filename": "sage_timer-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8d6092e27802fe1082e548fdbd81daf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 73009,
"upload_time": "2025-07-25T23:21:00",
"upload_time_iso_8601": "2025-07-25T23:21:00.885710Z",
"url": "https://files.pythonhosted.org/packages/7a/2a/b4831fbbd4c0a2a7a205891c5901d5bd8be0bf53f8a58c1c27f9303c7a8f/sage_timer-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a0b352a17168113c1afd0a5f6bb332abc7488c7c7e07a8bbde7bdef33684b9f",
"md5": "31cfc8a907c9f388feeeb50c2f06e2e7",
"sha256": "7d32e3512de11813f8ad134aaee864219f807e2b5f18073a7d6de1eed9a2fd72"
},
"downloads": -1,
"filename": "sage_timer-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "31cfc8a907c9f388feeeb50c2f06e2e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1804509,
"upload_time": "2025-07-25T23:21:02",
"upload_time_iso_8601": "2025-07-25T23:21:02.549943Z",
"url": "https://files.pythonhosted.org/packages/4a/0b/352a17168113c1afd0a5f6bb332abc7488c7c7e07a8bbde7bdef33684b9f/sage_timer-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 23:21:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nmsalvatore",
"github_project": "sage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sage-timer"
}
JSON
