• API Analysis
  • 1. Authentication Mechanism
  • 2. API Design Patterns
  • 3. Endpoint Reference
    • List & Group Actions
    • Sublist Actions
    • Item (Task) Actions
    • Notification & Access Actions
• Python API Client
• Quick Start for Advanced Users
• 1.1. System Dependencies
• 1.2. Creating a Python Virtual Environment (Best Practice)
• 1.3. Installing Script Dependencies
• 2.1. Saving the Script
• 2.2. Making the Script Globally Executable
• 3.1. Finding Your PHPSESSID and rkey
• 3.2. Storing Your Credentials Securely
• 3.3. Security Considerations
• 4.1. Global Options
• 4.2. List Commands
• 4.3. Sublist Commands
• 4.4. Task Commands
• 4.5. Interactive REPL Mode
  • Command-Line Interface (CLI) and User Experience (UX)
  • 4. Security Enhancements

#API Analysis

#1. Authentication Mechanism

The API does not use a visible token in an Authorization header. Authentication is managed via session cookies that must be included with every API request to the /api/ endpoints.

• Mechanism: Cookie-based session.
• Required Cookies:
  • PHPSESSID: The primary PHP session identifier.
  • rkey: A custom, long-lived key that appears to be essential for maintaining the authenticated session.
• Required Headers: All API calls observed in the HAR file include the X-Requested-With: XMLHttpRequest header, indicating they are intended to be called via AJAX.
• Note on Login Flow: The provided HAR data does not include the initial login request. Therefore, to use the generated Python client, you must first log in through a web browser, extract the PHPSESSID and rkey cookie values, and provide them to the client.

#2. API Design Patterns

• Request Chaining: The API is designed hierarchically. Creating a child object (like a task) requires the ID of its parent (a sublist), which in turn requires the ID of its parent (a list). A typical workflow is a chain of add requests, where the ID from one response is used in the payload of the next.
• Response on Creation: When a new object is created (e.g., adding a task), the API’s response body contains the full, updated data of the parent object. For example, adding a task to a sublist returns the entire sublist object, now including the newly created task in its items array. The client code must parse this parent object to find the ID of the newly created child.

#3. Endpoint Reference

The following endpoints were identified from the HAR data. All endpoints use the POST method and are relative to https://prioritylist.app.

#List & Group Actions

Endpoint	Method	Description
POST /api/groups/pull	POST	Fetches all list groups and the lists they contain.
POST /api/list/add	POST	Creates a new list.
POST /api/list/update	POST	Updates the name of an existing list.
POST /api/list/star	POST	Toggles the “starred” status of a list.
POST /api/list/pull	POST	Fetches the detailed contents of a specific list.
POST /api/list/notes	POST	Saves or updates the notes for a list.
POST /api/list/focus	POST	Sets a list to “focus” mode.
POST /api/list/unfocus	POST	Removes a list from “focus” mode.

Payload for POST /api/list/add | Parameter | Type | Required | Description | | :— | :— | :— | :— | | name | string | Yes | The name of the new list. | | group_id| string | No | The ID of the group to add the list to. |

#Sublist Actions

Endpoint	Method	Description
POST /api/sublist/add	POST	Adds a new sublist to a parent list.
POST /api/sublist/update	POST	Updates the name of an existing sublist.
POST /api/sublist/show	POST	Toggles the visibility of a sublist in the UI.
POST /api/sublist/reorder	POST	Changes the display order of sublists.

Payload for POST /api/sublist/add | Parameter | Type | Required | Description | | :— | :— | :— | :— | | list_id | integer | Yes | The ID of the parent list. | | name | string | Yes | The name of the new sublist. |

#Item (Task) Actions

Endpoint	Method	Description
POST /api/item/add	POST	Creates a new task (item) within a sublist.
POST /api/item/update	POST	Updates an existing task.
POST /api/item/update-name	POST	Updates only the name of a task.
POST /api/subitems/pull	POST	Fetches the sub-items for a given parent item.

Payload for POST /api/item/add | Parameter | Type | Required | Description | | :— | :— | :— | :— | | sublist_id | integer | Yes | The ID of the parent sublist. | | name | string | Yes | The name of the task. | | score_i | integer | Yes | Importance score (e.g., 1-10). | | score_t | integer | Yes | Urgency/Time score (e.g., 1-10). | | d_date | string | No | Due date in YYYY-MM-DD format. | | d_time | string | No | Due time in HH:MM format. | | d_zone | string | No | Timezone offset (e.g., -0300). | | dependency_id| integer | No | The ID of a prerequisite task. |

#Notification & Access Actions

Endpoint	Method	Description
POST /api/notifications/all	POST	Fetches all notifications.
POST /api/notifications/count	POST	Gets the count of unread notifications.
POST /api/access/pull	POST	Retrieves sharing information for a list.
POST /api/access/public	POST	Toggles the public visibility of a list.

#Python API Client

The following Python script provides a reusable PriorityListApiClient class to interact with the API. It is designed to be used with session cookies extracted from a browser.

#Quick Start for Advanced Users

For experienced users familiar with Python and Linux environments:

1. Save the script: Save the code as prioritylist-cli.py.
2. Create venv & install:
   python3 -m venv .venv source .venv/bin/activate pip install requests ptpython
3. Configure credentials: Create ~/.config/prioritylist/config.ini with your phpsessid and rkey.
   [auth] phpsessid = YOUR_PHPSESSID_VALUE rkey = YOUR_RKEY_VALUE
4. Make executable & move to PATH:
   chmod +x prioritylist-cli.py mkdir -p ~/.local/bin mv prioritylist-cli.py ~/.local/bin/ # Ensure ~/.local/bin is in your PATH
5. Run: prioritylist-cli.py list pull-all

---

#Table of Contents

1. Part 1: Environment Setup (The Right Way)
   • 1.1. System Dependencies
   • 1.2. Creating a Python Virtual Environment (Best Practice)
   • 1.3. Installing Script Dependencies
2. Part 2: Script Installation & Configuration
   • 2.1. Saving the Script
   • 2.2. Making the Script Globally Executable
3. Part 3: Authentication - The Critical Step
   • 3.1. Finding Your PHPSESSID and rkey
   • 3.2. Storing Your Credentials Securely
   • 3.3. Security Considerations
4. Part 4: Command Cheatsheet & Usage
   • 4.1. Global Options
   • 4.2. List Commands
   • 4.3. Sublist Commands
   • 4.4. Task Commands
   • 4.5. Interactive REPL Mode
5. Part 5: Troubleshooting

---

#Part 1: Environment Setup (The Right Way)

We will use a Python virtual environment to keep your system clean and avoid dependency conflicts.

#1.1. System Dependencies

Ensure Python 3, pip, and the venv module are installed on your openSUSE Tumbleweed system.

#1.2. Creating a Python Virtual Environment (Best Practice)

A virtual environment is an isolated space for your Python project’s dependencies.

1. Create a Project Directory: First, make a directory for your script and its environment.
   mkdir ~/prioritylist-project cd ~/prioritylist-project
2. Create the Virtual Environment: Use Python’s built-in venv module to create an environment named .venv.
   python3 -m venv .venv
3. Activate the Environment: You must “activate” the environment to use it. Your shell prompt will change to indicate it’s active.
   source .venv/bin/activate

   Note: To leave the environment, simply type deactivate. You must activate the environment in any new terminal session where you want to run the script or install packages for it.

#1.3. Installing Script Dependencies

With your environment active, install the required Python libraries. They will be installed inside the .venv directory, not system-wide.

#Part 2: Script Installation & Configuration

Now we’ll save the script and make it easy to run from anywhere.

#2.1. Saving the Script

Save the Python code you were given into a file named prioritylist-cli.py inside your ~/prioritylist-project directory.

#2.2. Making the Script Globally Executable

To run prioritylist-cli.py from any directory without typing the full path, we’ll make it executable and move it to a location in your system’s PATH.

1. Grant Execute Permissions:
   chmod +x prioritylist-cli.py
2. Move to Local Bin Directory: The standard location for user-specific executables is ~/.local/bin.
   mkdir -p ~/.local/bin mv prioritylist-cli.py ~/.local/bin/
3. Verify your PATH: On most modern Linux systems, ~/.local/bin is automatically added to your PATH when you log in. You can verify this:
   echo $PATH

   If you see /home/your_username/.local/bin in the output, you are all set. If not, add the following line to your ~/.profile or ~/.bashrc file and restart your shell session:

   # Add this line to ~/.profile export PATH="$HOME/.local/bin:$PATH"

#Part 3: Authentication - The Critical Step

The script requires your account’s session cookies to work.

#3.1. Finding Your PHPSESSID and rkey

1. Log In: In Firefox or a Chromium-based browser, log in to https://prioritylist.app.
2. Open Developer Tools: Press F12 or right-click the page and select “Inspect”.
3. Go to Storage/Application:
   • In Firefox, go to the Storage tab.
   • In Chrome/Edge, go to the Application tab.
4. Find Cookies: In the sidebar, expand “Cookies” and select https://prioritylist.app.
5. Copy Values: Find the rows for PHPSESSID and rkey. Carefully copy the long string from the “Value” column for each.

Important Note on Credentials These cookies can and will expire (e.g., after a few days, or when you log out). If the script suddenly stops working with an “API Error” or “HTTP 401/403” error, the most likely cause is an expired cookie. You will need to repeat this step to get new, valid cookie values.

#3.2. Storing Your Credentials Securely

The script checks for credentials in three places. The configuration file is the most convenient and recommended method.

1. Create the Directory:
   mkdir -p ~/.config/prioritylist
2. Create the Config File:
   nano ~/.config/prioritylist/config.ini
3. Add Your Credentials: Paste the following into the file, replacing the placeholders with your actual values.
   [auth] phpsessid = YOUR_PHPSESSID_VALUE_HERE rkey = YOUR_RKEY_VALUE_HERE

   Save and exit (Ctrl+O, then Ctrl+X in nano).

#3.3. Security Considerations

• Treat these credentials like passwords. Anyone with them can access your PriorityList account.
• The config.ini file is stored as plain text. On a multi-user system, ensure its permissions are secure (chmod 600 ~/.config/prioritylist/config.ini).
• Avoid passing credentials as command-line arguments (--phpsessid ...), as they will be stored in your shell’s history file (.bash_history).

#Part 4: Command Cheatsheet & Usage

Remember to have your virtual environment active (source ~/prioritylist-project/.venv/bin/activate) before running commands.

#4.1. Global Options

Option	Description
--json	Output machine-readable JSON instead of human-friendly text.

#4.2. List Commands

Action	Description	Example Command
pull-all	Fetch and display all your lists and groups.	prioritylist-cli.py list pull-all
show	Show full JSON details for a single list.	prioritylist-cli.py list show 12345
add	Add a new list.	prioritylist-cli.py list add --name "New Project"
update	Rename a list.	prioritylist-cli.py list update 12345 --name "Renamed Project"
delete	Permanently delete a list.	prioritylist-cli.py list delete 12345
star	Toggle the star status on a list.	prioritylist-cli.py list star 12345

#4.3. Sublist Commands

Action	Description	Example Command
add	Add a new sublist to a list.	prioritylist-cli.py sublist add --list-id 12345 --name "Design Phase"
update	Rename a sublist.	prioritylist-cli.py sublist update 56789 --name "Final Designs"
delete	Permanently delete a sublist.	prioritylist-cli.py sublist delete 56789

#4.4. Task Commands

Action	Description	Example Command
add	Add a new task to a sublist.	prioritylist-cli.py task add --sublist-id 56789 --name "Create logo" -i 8 -t 3
update	Update an existing task.	prioritylist-cli.py task update 98765 --name "Finalize logo" --due-date "2024-12-20"
delete	Permanently delete a task.	prioritylist-cli.py task delete 98765

#4.5. Interactive REPL Mode

Run the script with no arguments to enter a powerful interactive shell.

Inside the REPL, a pre-configured client object is available. You can explore the API directly.

#Part 5: Troubleshooting

Error Message / Symptom	Likely Cause & Solution
bash: prioritylist-cli.py: command not found	1. Your ~/.local/bin is not in your PATH. See step 2.2. 2. You have not restarted your shell since modifying your ~/.profile or ~/.bashrc. 3. You are trying to run it from a non-active venv.
ImportError: No module named 'requests'	The required Python libraries are not installed in your active virtual environment. Ensure you have run source .venv/bin/activate and then pip install requests ptpython.
❌ Error: Authentication credentials not found.	The script could not find your config.ini file. Ensure it is located at ~/.config/prioritylist/config.ini and the keys (phpsessid, rkey) are spelled correctly.
❌ API Error... or ❌ HTTP Error... 401/403	Your credentials have expired or are incorrect. This is the most common operational error. Repeat Part 3.1 to get new cookie values and update your config.ini file.
❌ Request failed... ConnectionError	You have a network problem. Check your internet connection and ensure you can access prioritylist.app in your browser.

#!/usr/bin/env python3 """ PriorityList CLI - The Optimized & Integrated Solution This script is the result of integrating the best features from multiple development approaches into a single, cohesive, and robust command-line interface. It combines: • Full CRUD (Create, Read, Update, Delete) operations for all resources. • A robust API client with detailed error handling and reliable response parsing. • A clean, nested command structure (e.g., `list add`, `task delete`). • An interactive REPL mode (via `ptpython`) for exploratory API calls. • Strict separation of human-readable and machine-readable (`--json`) output. • Secure credential management from args, environment, or config file. """ from __future__ import annotations import argparse import configparser import json import os import sys from pathlib import Path from typing import Any, Dict, List, Optional, Tuple import requests # ───────────────────────────────────────────────────────────── # Helper Functions # ───────────────────────────────────────────────────────────── def print_json(obj: Any) -> None: """Prints an object as a formatted JSON string to stdout.""" print(json.dumps(obj, indent=2, ensure_ascii=False)) def print_human(msg: str, *, is_json_mode: bool) -> None: """Prints a message to stdout only if not in JSON mode.""" if not is_json_mode: print(msg) # ───────────────────────────────────────────────────────────── # API Client # ───────────────────────────────────────────────────────────── class PriorityListApiClient: """A robust client for interacting with the prioritylist.app API.""" def __init__(self, phpsessid: str, rkey: str, base_url: str = "https://prioritylist.app") -> None: self.base_url = base_url.rstrip("/") self.session = requests.Session() self.session.headers.update({ "User-Agent": "Mozilla/5.0 (X11; Linux x86_64; rv:139.0) Gecko/20100101 Firefox/139.0", "Accept": "text/plain, */*; q=0.01", "X-Requested-With": "XMLHttpRequest", "Origin": self.base_url, }) self.session.cookies.set("PHPSESSID", phpsessid, domain="prioritylist.app") self.session.cookies.set("rkey", rkey, domain="prioritylist.app") def _post(self, endpoint: str, data: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]: """Makes a POST request, handles errors, and returns the 'data' field on success.""" url = f"{self.base_url}/api{endpoint}" try: response = self.session.post(url, data=data) response.raise_for_status() json_response = response.json() if json_response.get("result") == "success": return json_response.get("data") else: print(f"❌ API Error at {endpoint}: {json_response.get('result', 'Unknown error')}", file=sys.stderr) except requests.exceptions.HTTPError as e: print(f"❌ HTTP Error for {endpoint}: {e.response.status_code} {e.response.reason}", file=sys.stderr) print(f" Response body: {e.response.text}", file=sys.stderr) except requests.exceptions.RequestException as e: print(f"❌ Request failed for {endpoint}: {e}", file=sys.stderr) except json.JSONDecodeError: print(f"❌ Failed to decode JSON from response. URL: {url}", file=sys.stderr) return None # --- List Operations --- def get_all_lists(self) -> Optional[List[Dict[str, Any]]]: return self._post("/groups/pull") def get_list_details(self, list_id: int) -> Optional[Dict[str, Any]]: return self._post("/list/pull", {"id": list_id}) def create_list(self, name: str, group_id: str = "") -> Optional[Dict[str, Any]]: """Creates a new list and robustly finds and returns it from the response.""" response_data = self._post("/list/add", {"name": name, "group_id": group_id}) if response_data: try: for group in response_data: # Find the list by name to avoid relying on array order. # Note: This might not be perfect if duplicate names are allowed. for lst in group.get('lists', []): if lst['name'] == name: return lst except (IndexError, KeyError, TypeError) as e: print(f"❌ Could not parse created list from API response: {e}", file=sys.stderr) return None def update_list(self, list_id: int, name: str) -> bool: return self._post("/list/update", {"id": list_id, "name": name}) is not None def delete_list(self, list_id: int) -> bool: # Note: The delete endpoint was not in the HAR file, this is an educated guess. # If it fails, the actual endpoint might be different (e.g., /list/remove). return self._post("/list/delete", {"id": list_id}) is not None def star_list(self, list_id: int) -> bool: return self._post("/list/star", {"id": list_id}) is not None # --- Sublist Operations --- def create_sublist(self, list_id: int, name: str) -> Optional[Dict[str, Any]]: """Creates a new sublist and robustly finds and returns it.""" response_data = self._post("/sublist/add", {"list_id": list_id, "name": name}) if response_data: try: for sublist in response_data.get('sublists', []): if sublist['name'] == name: return sublist except (KeyError, TypeError) as e: print(f"❌ Could not parse created sublist from API response: {e}", file=sys.stderr) return None def update_sublist(self, sublist_id: int, name: str) -> bool: return self._post("/sublist/update", {"id": sublist_id, "name": name}) is not None def delete_sublist(self, sublist_id: int) -> bool: # Note: The delete endpoint was not in the HAR file, this is an educated guess. return self._post("/sublist/delete", {"id": sublist_id}) is not None # --- Task Operations --- def create_task(self, sublist_id: int, name: str, **kwargs) -> Optional[Dict[str, Any]]: """Creates a new task and robustly finds and returns it.""" payload = {"sublist_id": sublist_id, "name": name} # Map CLI-friendly names to API parameter names if 'importance' in kwargs: payload['score_i'] = kwargs.pop('importance') if 'time' in kwargs: payload['score_t'] = kwargs.pop('time') if 'due_date' in kwargs: payload['d_date'] = kwargs.pop('due_date') if 'dependency_id' in kwargs: payload['dependency_id'] = kwargs.pop('dependency_id') payload.update(kwargs) if payload.get('d_date'): payload.setdefault('d_zone', '-0300') response_data = self._post("/item/add", payload) if response_data: try: for item in response_data.get('items', []): if item['name'] == name: return item except (KeyError, TypeError) as e: print(f"❌ Could not parse created task from API response: {e}", file=sys.stderr) return None def update_task(self, task_id: int, updates: Dict[str, Any]) -> bool: """Updates an existing task with only the provided fields.""" payload = updates.copy() payload['id'] = task_id if 'd_date' in payload and payload['d_date']: payload.setdefault('d_zone', '-0300') return self._post("/item/update", data=payload) is not None def delete_task(self, task_id: int) -> bool: # Note: The delete endpoint was not in the HAR file, this is an educated guess. return self._post("/item/delete", {"id": task_id}) is not None # ───────────────────────────────────────────────────────────── # Credentials Helper # ───────────────────────────────────────────────────────────── def get_credentials(ns: argparse.Namespace) -> Tuple[str, str]: """Retrieves credentials from args, environment variables, or config file.""" if ns.phpsessid and ns.rkey: return ns.phpsessid, ns.rkey env_sess, env_rkey = os.getenv("PL_PHPSESSID"), os.getenv("PL_RKEY") if env_sess and env_rkey: return env_sess, env_rkey cfg_file = Path.home() / ".config" / "prioritylist" / "config.ini" if cfg_file.exists(): # FIX: Disable interpolation to handle '%' characters in cookie values cp = configparser.ConfigParser(interpolation=None) cp.read(cfg_file) if "auth" in cp and "phpsessid" in cp["auth"] and "rkey" in cp["auth"]: return cp["auth"]["phpsessid"], cp["auth"]["rkey"] print("❌ Error: Authentication credentials not found.", file=sys.stderr) print(" Please provide them via flags, environment variables, or a config file.", file=sys.stderr) sys.exit(1) # ───────────────────────────────────────────────────────────── # Command Handlers # ───────────────────────────────────────────────────────────── def handle_list_pull_all(client: PriorityListApiClient, ns: argparse.Namespace): data = client.get_all_lists() if data is None: print_human("❌ Could not fetch lists.", is_json_mode=ns.json) return if ns.json: print_json(data) else: for group in data: print_human(f"\n📁 {group.get('name') or 'Uncategorized'}", is_json_mode=ns.json) for lst in group.get("lists", []): star = "⭐" if lst.get("starred") else " " print_human(f" {star} ID: {lst['id']:<6} {lst['name']}", is_json_mode=ns.json) def handle_list_show(client: PriorityListApiClient, ns: argparse.Namespace): data = client.get_list_details(ns.list_id) if data is None: print_human(f"❌ List {ns.list_id} not found.", is_json_mode=ns.json) return print_json(data) def handle_list_add(client: PriorityListApiClient, ns: argparse.Namespace): new_list = client.create_list(ns.name) if new_list: print_human(f"✅ Created list '{new_list['name']}' (ID: {new_list['id']})", is_json_mode=ns.json) if ns.json: print_json(new_list) else: print_human(f"❌ Failed to create list '{ns.name}'.", is_json_mode=ns.json) def handle_list_update(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.update_list(ns.list_id, ns.name) msg = f"✅ Renamed list {ns.list_id} to '{ns.name}'." if ok else f"❌ Failed to rename list {ns.list_id}." print_human(msg, is_json_mode=ns.json) def handle_list_delete(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.delete_list(ns.list_id) msg = f"✅ Deleted list {ns.list_id}." if ok else f"❌ Failed to delete list {ns.list_id}." print_human(msg, is_json_mode=ns.json) def handle_list_star(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.star_list(ns.list_id) msg = f"✅ Toggled star on list {ns.list_id}." if ok else f"❌ Failed to toggle star on list {ns.list_id}." print_human(msg, is_json_mode=ns.json) def handle_sublist_add(client: PriorityListApiClient, ns: argparse.Namespace): new_sublist = client.create_sublist(ns.list_id, ns.name) if new_sublist: msg = f"✅ Created sublist '{new_sublist['name']}' (ID: {new_sublist['id']}) in list {ns.list_id}." print_human(msg, is_json_mode=ns.json) if ns.json: print_json(new_sublist) else: print_human(f"❌ Failed to create sublist '{ns.name}'.", is_json_mode=ns.json) def handle_sublist_update(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.update_sublist(ns.sublist_id, ns.name) msg = f"✅ Renamed sublist {ns.sublist_id} to '{ns.name}'." if ok else f"❌ Failed to rename sublist {ns.sublist_id}." print_human(msg, is_json_mode=ns.json) def handle_sublist_delete(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.delete_sublist(ns.sublist_id) msg = f"✅ Deleted sublist {ns.sublist_id}." if ok else f"❌ Failed to delete sublist {ns.sublist_id}." print_human(msg, is_json_mode=ns.json) def handle_task_add(client: PriorityListApiClient, ns: argparse.Namespace): params = { "importance": ns.importance, "time": ns.time, "d_date": ns.due_date or "", "dependency_id": ns.dependency_id or "", } new_task = client.create_task(ns.sublist_id, ns.name, **params) if new_task: msg = f"✅ Created task '{new_task['name']}' (ID: {new_task['id']}) in sublist {ns.sublist_id}." print_human(msg, is_json_mode=ns.json) if ns.json: print_json(new_task) else: print_human(f"❌ Failed to create task '{ns.name}'.", is_json_mode=ns.json) def handle_task_update(client: PriorityListApiClient, ns: argparse.Namespace): updates = {k: v for k, v in vars(ns).items() if k in [ 'name', 'sublist_id', 'importance', 'time', 'due_date', 'dependency_id' ] and v is not None} if not updates: print_human("❌ Error: At least one field to update must be provided.", is_json_mode=ns.json) sys.exit(1) # Remap arg names to API field names if 'importance' in updates: updates['score_i'] = updates.pop('importance') if 'time' in updates: updates['score_t'] = updates.pop('time') if 'due_date' in updates: updates['d_date'] = updates.pop('due_date') ok = client.update_task(ns.task_id, updates) msg = f"✅ Updated task {ns.task_id}." if ok else f"❌ Failed to update task {ns.task_id}." print_human(msg, is_json_mode=ns.json) def handle_task_delete(client: PriorityListApiClient, ns: argparse.Namespace): ok = client.delete_task(ns.task_id) msg = f"✅ Deleted task {ns.task_id}." if ok else f"❌ Failed to delete task {ns.task_id}." print_human(msg, is_json_mode=ns.json) # ───────────────────────────────────────────────────────────── # Argument Parser # ───────────────────────────────────────────────────────────── def build_parser() -> argparse.ArgumentParser: p = argparse.ArgumentParser(description="A robust CLI for prioritylist.app.", formatter_class=argparse.RawTextHelpFormatter) p.add_argument("--phpsessid", help="Your PHPSESSID cookie.") p.add_argument("--rkey", help="Your rkey cookie.") p.add_argument("--json", action="store_true", help="Output machine-readable JSON only.") sp = p.add_subparsers(dest="resource", required=True, help="The resource to manage.") # --- List Parser --- ls = sp.add_parser("list", help="Manage lists").add_subparsers(dest="action", required=True) ls.add_parser("pull-all", help="Fetch all lists and groups").set_defaults(func=handle_list_pull_all) ls_sh = ls.add_parser("show", help="Show full JSON details for one list") ls_sh.add_argument("list_id", type=int, help="ID of the list to show") ls_sh.set_defaults(func=handle_list_show) ls_add = ls.add_parser("add", help="Add a new list") ls_add.add_argument("--name", required=True, help="Name for the new list") ls_add.set_defaults(func=handle_list_add) ls_upd = ls.add_parser("update", help="Rename a list") ls_upd.add_argument("list_id", type=int, help="ID of the list to update") ls_upd.add_argument("--name", required=True, help="New name for the list") ls_upd.set_defaults(func=handle_list_update) ls_del = ls.add_parser("delete", help="Delete a list") ls_del.add_argument("list_id", type=int, help="ID of the list to delete") ls_del.set_defaults(func=handle_list_delete) ls_star = ls.add_parser("star", help="Toggle star status on a list") ls_star.add_argument("list_id", type=int, help="ID of the list to star/unstar") ls_star.set_defaults(func=handle_list_star) # --- Sublist Parser --- sb = sp.add_parser("sublist", help="Manage sublists").add_subparsers(dest="action", required=True) sb_add = sb.add_parser("add", help="Add a new sublist") sb_add.add_argument("--list-id", type=int, required=True, help="ID of the parent list") sb_add.add_argument("--name", required=True, help="Name for the new sublist") sb_add.set_defaults(func=handle_sublist_add) sb_upd = sb.add_parser("update", help="Rename a sublist") sb_upd.add_argument("sublist_id", type=int, help="ID of the sublist to update") sb_upd.add_argument("--name", required=True, help="New name for the sublist") sb_upd.set_defaults(func=handle_sublist_update) sb_del = sb.add_parser("delete", help="Delete a sublist") sb_del.add_argument("sublist_id", type=int, help="ID of the sublist to delete") sb_del.set_defaults(func=handle_sublist_delete) # --- Task Parser --- tk = sp.add_parser("task", help="Manage tasks").add_subparsers(dest="action", required=True) tk_add = tk.add_parser("add", help="Add a new task") tk_add.add_argument("--sublist-id", type=int, required=True, help="ID of the parent sublist") tk_add.add_argument("--name", required=True, help="Name for the new task") tk_add.add_argument("-i", "--importance", type=int, default=5, help="Importance score (1-10)") tk_add.add_argument("-t", "--time", type=int, default=5, help="Time/Effort score (1-10)") tk_add.add_argument("-d", "--due-date", help="Due date in YYYY-MM-DD format") tk_add.add_argument("--dependency-id", type=int, help="ID of a prerequisite task") tk_add.set_defaults(func=handle_task_add) tk_upd = tk.add_parser("update", help="Update an existing task") tk_upd.add_argument("task_id", type=int, help="ID of the task to update") tk_upd.add_argument("--sublist-id", type=int, help="Move task to a new parent sublist") tk_upd.add_argument("--name", help="New name for the task") tk_upd.add_argument("-i", "--importance", type=int, help="New importance score (1-10)") tk_upd.add_argument("-t", "--time", type=int, help="New time/Effort score (1-10)") tk_upd.add_argument("-d", "--due-date", help="New due date in YYYY-MM-DD format") tk_upd.add_argument("--dependency-id", type=int, help="New ID of a prerequisite task") tk_upd.set_defaults(func=handle_task_update) tk_del = tk.add_parser("delete", help="Delete a task") tk_del.add_argument("task_id", type=int, help="ID of the task to delete") tk_del.set_defaults(func=handle_task_delete) return p # ───────────────────────────────────────────────────────────── # Main Execution # ───────────────────────────────────────────────────────────── def main(): """Main entry point for the script.""" if len(sys.argv) == 1: try: from ptpython.repl import embed print("▶️ No command provided. Starting interactive REPL...") creds_ns = argparse.Namespace(phpsessid=None, rkey=None) phpsessid, rkey = get_credentials(creds_ns) client = PriorityListApiClient(phpsessid, rkey) namespace = {'client': client, 'print_json': print_json} print("✅ An API client is available as `client`.") embed(globals=namespace, locals=namespace) except ImportError: print("ℹ️ Optional dependency 'ptpython' not found.", file=sys.stderr) print(" Run 'pip install ptpython' for an enhanced interactive experience.", file=sys.stderr) print("\nDisplaying help instead:\n") build_parser().print_help() sys.exit(0) parser = build_parser() args = parser.parse_args() phpsessid, rkey = get_credentials(args) client = PriorityListApiClient(phpsessid, rkey) if hasattr(args, 'func'): args.func(client, args) else: parser.print_help() if __name__ == "__main__": main()

#Command-Line Interface (CLI) and User Experience (UX)

• Nested Command Structure: The CLI now uses a more intuitive resource action format (e.g., list add, task update). This is a standard practice for modern CLIs and a vast improvement over the original flat command list.
• Interactive REPL Mode: A major feature addition is the ptpython-based interactive REPL, which launches if the script is run without arguments. It provides an authenticated client object, allowing for powerful, exploratory API interactions without writing new scripts.
• Clear and Concise Output: The use of emojis (✅, ❌, 📁, ⭐) provides immediate visual feedback on the status of operations.
• Scripting-Friendly JSON Mode: The --json flag now guarantees that the only output to stdout is a clean JSON object, making it trivial to pipe the output of this tool to other programs like jq.

#4. Security Enhancements

• Secure Credential Sourcing: The get_credentials function continues to provide a secure and flexible way to manage API keys, preventing them from being hard-coded. It checks arguments, environment variables, and a dedicated config file in a safe order of precedence.
• Robust Input Handling: The API client’s improved error handling and response parsing make it less susceptible to crashes or unexpected behavior caused by malformed API responses.

#client-side code

#server-side pseudocode