countdown-cli 2.1.0
Terminal program to display countdown timer
License: MIT
Requires Python: >=3.10

countdown-cli
=============

|PyPI| |Status| |Python Version| |License|

|Tests| |Codecov|

.. |PyPI| image:: https://img.shields.io/pypi/v/countdown-cli.svg
   :target: https://pypi.org/project/countdown-cli/
   :alt: PyPI
.. |Status| image:: https://img.shields.io/pypi/status/countdown-cli.svg
   :target: https://pypi.org/project/countdown-cli/
   :alt: Status
.. |Python Version| image:: https://img.shields.io/pypi/pyversions/countdown-cli
   :target: https://pypi.org/project/countdown-cli
   :alt: Python Version
.. |License| image:: https://img.shields.io/pypi/l/countdown-cli
   :target: https://opensource.org/licenses/MIT
   :alt: License
.. |Tests| image:: https://github.com/treyhunner/countdown-cli/workflows/Tests/badge.svg
   :target: https://github.com/treyhunner/countdown-cli/actions?workflow=Tests
   :alt: Tests
.. |Codecov| image:: https://codecov.io/gh/treyhunner/countdown-cli/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/treyhunner/countdown-cli
   :alt: Codecov

This project is based on a `Python Morsels`_ exercise for a command-line countdown timer.
If you're working on that exercise right now, please **don't look at the source code** for this. 😉

|Logo|

.. |Logo| image:: https://raw.githubusercontent.com/treyhunner/countdown-cli/main/images/python-morsels-logo.png
   :target: https://www.pythonmorsels.com
   :width: 400
   :alt: an adorable snake taking a bite out of a cookie with the words Python Morsels next to it (Python Morsels logo)

Wondering how this package works?
**Don't look at the source code just yet!**
Instead, try implementing this package with the `Python Morsels "countdown" exercise <https://www.pythonmorsels.com/exercises/fc3be8467c634f978eae0c315f5677d1/>`_!


Features
--------

- Full-screen countdown timer, centered in the terminal window
- Responsive timer size based on terminal window width/height
- Command-line interface for Linux/Mac/Windows
- Pause/resume with ``p``, ``k``, ``Space``, or ``Enter``
- Add / remove time with ``+`` or ``-``

To start a timer:

.. code:: console

    countdown 6m30s

|32:53|

|14:57|

.. |32:53| image:: https://raw.githubusercontent.com/treyhunner/countdown-cli/main/images/3253.png
   :width: 500
   :alt: 32:53 shown in large letters in center of an xterm window (black background with white text)

.. |14:57| image:: https://raw.githubusercontent.com/treyhunner/countdown-cli/main/images/1457.png
   :width: 500
   :alt: 14:57 shown in large letters in center of terminal window (light background with darker text)


Requirements
------------

- Python 3.10+


Installation
------------

You can install **countdown-cli** via uv_ from PyPI_:

.. code:: console

   uv tool install countdown-cli


Contributing
------------

Contributions are very welcome.
To learn more, see the `Contributor Guide`_.


License
-------

Distributed under the terms of the `MIT license`_,
**countdown-cli** is free and open source software.


Issues
------

If you encounter any problems,
please `file an issue`_ along with a detailed description.


.. _Python Morsels: https://www.pythonmorsels.com
.. _MIT license: https://opensource.org/licenses/MIT
.. _PyPI: https://pypi.org/project/countdown-cli/
.. _file an issue: https://github.com/treyhunner/countdown-cli/issues
.. _uv: https://docs.astral.sh/uv/concepts/tools/
.. github-only
.. _Contributor Guide: CONTRIBUTING.rst