From ba50ddc0c7c9119530e667388ac8f254edf7c108 Mon Sep 17 00:00:00 2001
From: erseco <info@ernesto.es>
Date: Wed, 8 Jul 2026 06:40:09 +0100
Subject: [PATCH] Add python-moodle CLI alias; fix install docs to the real
 package name

The distribution is 'python-moodle' but the CLI command was only
'py-moodle', and the install docs said 'pip install py-moodle' /
'cd py-moodle' (wrong package + directory names).

- pyproject.toml: register 'python-moodle' as a second console-script
  entry point aliasing 'py_moodle.cli:app', so both 'py-moodle' and
  'python-moodle' invoke the CLI. Verified: pip install -e . creates both
  .venv/bin/py-moodle and .venv/bin/python-moodle, and 'python-moodle
  --help' runs.
- docs/getting-started/installation.md: fix 'pip install py-moodle' ->
  'python-moodle', 'cd py-moodle' -> 'cd python-moodle', 'Python 3.8+' ->
  '3.9+' (matches requires-python), and add a note explaining the
  package/command/import names and that both commands are equivalent.
- docs/getting-started/quickstart.md: fix 'pip install py-moodle' ->
  'python-moodle' and note both commands work.
---
 docs/getting-started/installation.md | 20 ++++++++++++++------
 docs/getting-started/quickstart.md   |  6 ++++--
 pyproject.toml                       |  2 ++
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index dc1c0e8..71c3eaf 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -1,11 +1,17 @@
 # Installation
 
-py-moodle requires Python 3.8+ and can be installed in several ways.
+`python-moodle` requires Python 3.9+ and can be installed in several ways.
+
+!!! note "Package name vs. command name"
+    The package is published as **`python-moodle`** (that's what you `pip install`
+    and `import py_moodle`), and the CLI is available under **two equivalent
+    command names**: **`py-moodle`** and **`python-moodle`**. Use whichever you
+    prefer — every example in these docs uses `py-moodle`.
 
 ## Method 1: PyPI (Recommended)
 
 ```bash
-pip install py-moodle
+pip install python-moodle
 ```
 
 ## Method 2: From Source
@@ -14,11 +20,11 @@ Clone the repository and install:
 
 ```bash
 git clone https://github.com/erseco/python-moodle.git
-cd py-moodle
+cd python-moodle
 pip install .
 ```
 
-This makes the `py-moodle` command available system-wide.
+This makes the `py-moodle` (and `python-moodle`) command available system-wide.
 
 ## Method 3: Development Installation
 
@@ -26,7 +32,7 @@ For development or to get the latest features:
 
 ```bash
 git clone https://github.com/erseco/python-moodle.git
-cd py-moodle
+cd python-moodle
 pip install -e .
 ```
 
@@ -34,10 +40,12 @@ The `-e` flag installs in "editable" mode, so changes to the source code are imm
 
 ## Verify Installation
 
-Test that py-moodle is properly installed:
+Test that the CLI is properly installed (either command works):
 
 ```bash
 py-moodle --help
+# or, equivalently:
+python-moodle --help
 ```
 
 You should see the main help screen with available commands.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 3c0423c..5608e50 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -8,12 +8,14 @@ Get up and running with py-moodle in minutes!
 - Access to a Moodle instance
 - Valid Moodle credentials
 
-## 1. Install py-moodle
+## 1. Install python-moodle
 
 ```bash
-pip install py-moodle
+pip install python-moodle
 ```
 
+The CLI is then available as either `py-moodle` or `python-moodle` (the examples use `py-moodle`).
+
 ## 2. Configure Credentials
 
 Create a `.env` file with your Moodle credentials:
diff --git a/pyproject.toml b/pyproject.toml
index 7e93342..72fd35d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,6 +65,8 @@ Changelog = "https://github.com/erseco/python-moodle/releases"
 
 [project.scripts]
 py-moodle = "py_moodle.cli:app"
+# Alias so the command matches the distribution name; both are equivalent.
+python-moodle = "py_moodle.cli:app"
 
 [tool.setuptools.packages.find]
 where = ["src"]