matagus · matagus · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
@@ -14,7 +14,7 @@ body:
   attributes:
     label: Package Version
     description: Which version of this package were you using? If not the latest version, please check this issue has not since been resolved.
-    placeholder: 0.3.0
+    placeholder: 0.4.0
   validations:
     required: false
 - type: input

diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ auto-detect your current sprint. It features interactive mode for easy navigatio
 - **Grouping**: Group tasks by status, assignee, or priority
 - **Task Details**: View detailed information about a specific task
 - **Task Updates**: Update task status with confirmation display
+- **Task Comments**: Post comments on tasks from the CLI or via piped input
 - **Sprint Detection**: Auto-detect current sprint/iteration lists
 - **Interactive Mode**: Navigate through Team → Space → Project → List hierarchy with prompts
 - **Caching**: Disk-based caching for improved performance (24h for teams/lists, 5min for tasks)
@@ -32,7 +33,15 @@ pip install quickup
 
 ## Quick Start
 
-Set your ClickUp API token:
+Authenticate with ClickUp (recommended):
+
+```bash
+quickup login
+```
+
+This opens your browser for OAuth authentication and saves your credentials to `~/.quickup/auth.json`.
+
+Alternatively, set your ClickUp API token directly (useful for CI/automation):
 
 ```bash
 export CLICKUP_TOKEN=your_token_here
@@ -52,6 +61,26 @@ quickup --team <team_id> --list <list_id>
 
 ## Commands
 
+### `quickup login` - Authenticate
+
+Authenticate with ClickUp via OAuth. Opens your default browser and waits for the callback (up to 120 seconds).
+
+```bash
+quickup login
+```
+
+Credentials are saved to `~/.quickup/auth.json` (permissions: `0o600`).
+
+### `quickup logout` - Remove Stored Credentials
+
+Remove the stored OAuth token.
+
+```bash
+quickup logout
+```
+
+This only removes the OAuth token — it does not affect tokens set via `CLICKUP_TOKEN` or `.env`.
+
 ### `quickup` (default) - List Tasks
 
 List all tasks from a ClickUp list, grouped by status.
@@ -120,11 +149,15 @@ quickup task <task_id>
 
 # With team specification
 quickup task <task_id> --team <team_id>
+
+# Include task comments
+quickup task <task_id> --comments
 ```
 
 **Options:**
 - `task_id`: ClickUp task ID
 - `--team`: Team ID (required if multiple teams exist)
+- `--comments`: Fetch and display task comments
 - `-i, --interactive`: Enable interactive mode
 
 ### `quickup update <task_id>` - Update Task Status
@@ -145,6 +178,26 @@ quickup update <task_id> --status "Done" --team <team_id>
 - `--team`: Team ID (required if multiple teams exist)
 - `-i, --interactive`: Enable interactive mode
 
+### `quickup comment <task_id>` - Post a Comment
+
+Post a comment on a specific task.
+
+```bash
+# Post a comment
+quickup comment <task_id> --text "This is my comment"
+
+# Notify all task watchers
+quickup comment <task_id> --text "Attention everyone" --notify-all
+
+# Pipe comment from stdin
+echo "Piped comment" | quickup comment <task_id>
+```
+
+**Options:**
+- `task_id`: ClickUp task ID
+- `--text`: Comment text to post (reads from stdin if omitted)
+- `--notify-all`: Notify all task watchers
+
 ## Interactive Mode
 
 When multiple teams, spaces, projects, or lists exist, use `-i` flag to enable interactive selection:

diff --git a/__about__.py b/__about__.py
@@ -1 +1 @@
-__version__ = "0.3.0"
+__version__ = "0.4.0"
diff --git a/docs/source/Installation.rst b/docs/source/Installation.rst
@@ -32,12 +32,31 @@ Installation Steps
 Configuration
 -------------
 
-After installation, you need to configure your ClickUp API token.
+After installation, authenticate with ClickUp using one of the methods below.
 
-Option 1: Environment Variable
+Option 1: OAuth Login (Recommended)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run the login command to authenticate via your browser:
+
+.. code-block:: bash
+
+   quickup login
+
+This opens ClickUp in your default browser. After approving access, your credentials are
+saved automatically to ``~/.quickup/auth.json`` (permissions: ``0o600``). No manual token
+management needed.
+
+To sign out:
+
+.. code-block:: bash
+
+   quickup logout
+
+Option 2: Environment Variable
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Export the token in your shell:
+For automation or CI environments, export the token in your shell:
 
 .. code-block:: bash
 
@@ -49,7 +68,7 @@ To make this permanent, add it to your shell configuration file (e.g., ``~/.bash
 
    echo 'export CLICKUP_TOKEN=your_token_here' >> ~/.zshrc
 
-Option 2: .env File
+Option 3: .env File
 ~~~~~~~~~~~~~~~~~~~
 
 Create a ``.env`` file in your project directory:
@@ -60,8 +79,13 @@ Create a ``.env`` file in your project directory:
 
 QuickUp! will automatically load the token from this file.
 
-Getting Your ClickUp API Token
-------------------------------
+.. note::
+
+   When both an environment/``.env`` token and an OAuth token exist, the environment token
+   takes precedence.
+
+Getting Your ClickUp API Token (for manual setup)
+--------------------------------------------------
 
 1. Log in to your ClickUp account
 2. Go to Settings → Apps → ClickUp API

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -38,6 +38,13 @@ cli.cache
    :members:
    :undoc-members:
 
+cli.auth
+--------
+
+.. automodule:: quickup.cli.auth
+   :members:
+   :undoc-members:
+
 cli.exceptions
 --------------
 

diff --git a/docs/source/commands.rst b/docs/source/commands.rst
@@ -3,6 +3,63 @@ Commands Reference
 
 This page documents all available QuickUp! CLI commands and their options.
 
+``quickup login`` - Authenticate
+---------------------------------
+
+Authenticate with ClickUp via OAuth. Opens your default browser and waits for the callback.
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: bash
+
+   quickup login
+
+Description
+~~~~~~~~~~~
+
+Opens the ClickUp authorization page in your browser and starts a local HTTP server on
+``localhost:4242`` to receive the OAuth callback. After you approve access in the browser,
+the token is exchanged and saved securely to ``~/.quickup/auth.json`` (permissions:
+``0o600``). The callback times out after 120 seconds if not completed.
+
+To use a custom OAuth application, set ``QUICKUP_CLIENT_ID`` and ``QUICKUP_CLIENT_SECRET``
+environment variables before running ``quickup login``.
+
+Examples
+~~~~~~~~
+
+Log in with the default QuickUp! OAuth application:
+
+.. code-block:: bash
+
+   quickup login
+
+``quickup logout`` - Remove Stored Credentials
+-----------------------------------------------
+
+Remove the stored OAuth token from disk.
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: bash
+
+   quickup logout
+
+Description
+~~~~~~~~~~~
+
+Deletes ``~/.quickup/auth.json``. This only removes the OAuth token — tokens set via the
+``CLICKUP_TOKEN`` environment variable or a ``.env`` file are not affected.
+
+Examples
+~~~~~~~~
+
+.. code-block:: bash
+
+   quickup logout
+
 ``quickup`` (default) - List Tasks
 ----------------------------------
 
@@ -155,6 +212,10 @@ Options
 
    Team ID (required if multiple teams exist)
 
+.. option:: --comments
+
+   Fetch and display task comments
+
 .. option:: -i, --interactive
 
    Enable interactive mode
@@ -174,6 +235,12 @@ With team specification:
 
    quickup task 123456 --team 12345
 
+Include comments:
+
+.. code-block:: bash
+
+   quickup task 123456 --comments
+
 ``quickup update`` - Update Task Status
 ---------------------------------------
 
@@ -222,3 +289,54 @@ With team specification:
 .. code-block:: bash
 
    quickup update 123456 --status "Done" --team 12345
+
+``quickup comment`` - Post a Comment
+-------------------------------------
+
+Post a comment on a specific task. Provide text via ``--text`` or pipe from stdin.
+
+Synopsis
+~~~~~~~~
+
+.. code-block:: bash
+
+   quickup comment <task_id> [OPTIONS]
+
+Arguments
+~~~~~~~~~
+
+.. option:: task_id
+
+   ClickUp task ID
+
+Options
+~~~~~~~
+
+.. option:: --text
+
+   Comment text to post. If omitted, reads from stdin.
+
+.. option:: --notify-all
+
+   Notify all task watchers (default: false)
+
+Examples
+~~~~~~~~
+
+Post a comment:
+
+.. code-block:: bash
+
+   quickup comment 123456 --text "This looks good, merging now"
+
+Notify all watchers:
+
+.. code-block:: bash
+
+   quickup comment 123456 --text "Attention everyone" --notify-all
+
+Pipe comment from stdin:
+
+.. code-block:: bash
+
+   echo "Comment from a script" | quickup comment 123456
diff --git a/docs/source/features.rst b/docs/source/features.rst
@@ -3,6 +3,32 @@ Features
 
 This page describes the key features of QuickUp!.
 
+Authentication
+--------------
+
+QuickUp! supports two authentication modes:
+
+**OAuth (recommended)** — authenticate once via your browser:
+
+.. code-block:: bash
+
+   quickup login   # opens browser, saves token to ~/.quickup/auth.json
+   quickup logout  # removes the stored token
+
+**API Token** — set a personal token via environment variable or ``.env`` file:
+
+.. code-block:: bash
+
+   export CLICKUP_TOKEN=your_token_here
+
+Token resolution order:
+
+1. ``CLICKUP_TOKEN`` environment variable or ``.env`` file (takes precedence)
+2. OAuth token stored in ``~/.quickup/auth.json``
+
+The OAuth token is stored with restrictive file permissions (``0o600``) so only the
+current user can read it.
+
 Task Listing
 ------------
 
@@ -64,6 +90,32 @@ Group tasks by different criteria:
    # Group by priority
    quickup --team 123 --list 456 --group-by priority
 
+Task Comments
+-------------
+
+Post comments on tasks directly from the CLI or by piping text from stdin:
+
+.. code-block:: bash
+
+   # Post a comment with --text
+   quickup comment 123456 --text "Looks good!"
+
+   # Pipe from another command
+   echo "Automated comment" | quickup comment 123456
+
+   # Notify all task watchers
+   quickup comment 123456 --text "Please review" --notify-all
+
+Long comments are truncated in the confirmation output for readability.
+
+View all comments on a task with the ``--comments`` flag on the ``task`` command:
+
+.. code-block:: bash
+
+   quickup task 123456 --comments
+
+Each comment shows the author's username, timestamp, and full comment text.
+
 Sprint Detection
 ----------------