Installation
============

Prerequisites
-------------

- **Python 3.13+** (not tested on earlier versions)
- **uv** — the fast Python package manager
  (`install uv <https://docs.astral.sh/uv/getting-started/installation/>`_)
- **gh** — the GitHub CLI, only needed if you use the ``--github`` flag
  (`install gh <https://cli.github.com/>`_)

Install
-------

Install as a global tool with uv (recommended):

.. code-block:: bash

   uv tool install uv-start

Or with pip:

.. code-block:: bash

   pip install uv-start

Author configuration
--------------------

Configure your author details so they are injected into every project
you generate. Run this once after installing:

.. code-block:: bash

   uv-start --config "Jane Doe" "jane@example.com"

This saves your name and email to ``~/.config/uv-start/config.toml``.

If you skip this step, uv-start falls back to your ``git config``
(``user.name`` / ``user.email``). If neither is set, placeholder
values are used.

GitHub authentication
---------------------

If you plan to use the ``--github`` flag, authenticate the ``gh`` CLI
first using OAuth:

.. code-block:: bash

   gh auth login

Follow the interactive prompts to authenticate via your browser. This
stores credentials securely in the ``gh`` keychain — no tokens need to
be stored in any file.

.. note::

   If ``GH_TOKEN`` or ``GITHUB_TOKEN`` is already exported in your shell,
   ``gh`` will use it automatically. However, OAuth via ``gh auth login``
   is the recommended approach.

Running uv-start
----------------

After installing, ``uv-start`` is available directly on your PATH.
Run it from any directory that will become the **parent** of your new
project (it must not itself be a git repository):

.. code-block:: bash

   cd ~/projects
   uv-start my-new-project -t package -g