API Reference

This section documents the Python API of QuickUp!.

cli.main

Main CLI entry point for QuickUp! using cyclopts.

quickup.cli.main.list_tasks(team: Annotated[str | None, Parameter(name='--team', help='Team ID')] = None, space: Annotated[str | None, Parameter(name='--space', help='Space ID')] = None, project: Annotated[str | None, Parameter(name='--project', help='Project ID')] = None, list_id: Annotated[str | None, Parameter(name='--list', help='List ID')] = None, assignee: Annotated[str | None, Parameter(name='--assignee', help='Filter by assignee username')] = None, priority: Annotated[str | None, Parameter(name='--priority', help='Filter by priority (low, normal, high, urgent)')] = None, due_before: Annotated[str | None, Parameter(name='--due-before', help='Filter tasks due before date (YYYY-MM-DD)')] = None, group_by: Annotated[str, Parameter(name='--group-by', help='Group by: status (default), assignee, priority')] = 'status', closed: Annotated[bool, Parameter(name='--closed', help='Include closed/done tasks')] = False, no_cache: Annotated[bool, Parameter(name='--no-cache', help='Bypass cache')] = False, interactive: Annotated[bool, Parameter(name='-i', help='Enable interactive mode')] = False) → None[source]

List tasks from a ClickUp list.

Navigates through Team -> Space -> Project -> List hierarchy and displays all tasks grouped by status.

Filters:

--assignee: Filter by assignee username (case-insensitive) --priority: Filter by priority level (low, normal, high, urgent) --due-before: Filter tasks due before date (YYYY-MM-DD)

Grouping:

--group-by: Group by status (default), assignee, or priority

Interactive Mode:

-i, --interactive: Prompt for Team/Space/Project/List selection

quickup.cli.main.run_app()[source]

Run the QuickUp! CLI application.

quickup.cli.main.sprint(team: Annotated[str | None, Parameter(name='--team', help='Team ID')] = None, space: Annotated[str | None, Parameter(name='--space', help='Space ID')] = None, project: Annotated[str | None, Parameter(name='--project', help='Project ID')] = None, assignee: Annotated[str | None, Parameter(name='--assignee', help='Filter by assignee username')] = None, priority: Annotated[str | None, Parameter(name='--priority', help='Filter by priority (low, normal, high, urgent)')] = None, due_before: Annotated[str | None, Parameter(name='--due-before', help='Filter tasks due before date (YYYY-MM-DD)')] = None, group_by: Annotated[str, Parameter(name='--group-by', help='Group by: status (default), assignee, priority')] = 'status', closed: Annotated[bool, Parameter(name='--closed', help='Include closed/done tasks')] = False, no_cache: Annotated[bool, Parameter(name='--no-cache', help='Bypass cache')] = False, interactive: Annotated[bool, Parameter(name='-i', help='Enable interactive mode')] = False) → None[source]

List tasks from the current sprint.

Auto-detects the current sprint list by searching for lists containing "sprint" or "iteration" in the name.

Filters:

--assignee: Filter by assignee username (case-insensitive) --priority: Filter by priority level (low, normal, high, urgent) --due-before: Filter tasks due before date (YYYY-MM-DD)

Grouping:

--group-by: Group by status (default), assignee, or priority

Interactive Mode:

-i, --interactive: Prompt for Team/Space/Project selection

quickup.cli.main.show_task(task_id: Annotated[str, Parameter(name='task_id', help='Task ID')], team: Annotated[str | None, Parameter(name='--team', help='Team ID')] = None, interactive: Annotated[bool, Parameter(name='-i', help='Enable interactive mode')] = False, comments: Annotated[bool, Parameter(name='--comments', help='Show task comments')] = False) → None[source]

Show detailed information about a specific task.

Displays all task metadata including ID, name, status, URL, assignees, priority, due date, description, and subtasks.

Parameters:

  • task_id -- ClickUp task ID.

  • team -- Optional team ID (required if multiple teams exist).

  • interactive -- Enable interactive team selection.

  • comments -- If True, also fetch and display task comments.

quickup.cli.main.update_task(task_id: Annotated[str, Parameter(name='task_id', help='Task ID')], status: Annotated[str, Parameter(name='--status', help='New status name')], team: Annotated[str | None, Parameter(name='--team', help='Team ID')] = None, interactive: Annotated[bool, Parameter(name='-i', help='Enable interactive mode')] = False) → None[source]

Update the status of a specific task.

Changes the task status to the specified value. Shows confirmation with old -> new status transition.

Parameters:

  • task_id -- ClickUp task ID.

  • status -- New status name (e.g., "To Do", "In Progress", "Done").

  • team -- Optional team ID (required if multiple teams exist).

  • interactive -- Enable interactive team selection.

quickup.cli.main.comment_task(task_id: Annotated[str, Parameter(name='task_id', help='Task ID')], text: Annotated[str | None, Parameter(name='--text', help='Comment text to post')] = None, notify_all: Annotated[bool, Parameter(name='--notify-all', help='Notify all task watchers')] = False) → None[source]

Post a comment on a task.

Provide text via --text or pipe from stdin.

Parameters:

  • task_id -- ClickUp task ID.

  • text -- Comment text to post.

  • notify_all -- If True, notify all task watchers.

quickup.cli.main.login() → None[source]

Authenticate with ClickUp via OAuth2 browser login.

quickup.cli.main.logout() → None[source]

Remove stored ClickUp OAuth credentials.

cli.api_client

API client wrapper for ClickUp API interactions.

quickup.cli.api_client.get_team(clickup, argv, interactive=False)[source]

Get team from CLI args or interactive selection.

Parameters:

  • clickup -- ClickUp client instance.

  • argv -- Command line arguments.

  • interactive -- If True, prompt user to select team when multiple exist.

Returns:

Team object.

Raises:
quickup.cli.api_client.get_space_for(team, argv, interactive=False)[source]

Get space from CLI args or interactive selection.

Parameters:

  • team -- Team object.

  • argv -- Command line arguments.

  • interactive -- If True, prompt user to select space when multiple exist.

Returns:

Space object.

Raises:

SpaceNotFoundError -- If space is not found.

quickup.cli.api_client.get_project_for(space, argv, interactive=False)[source]

Get project from CLI args or interactive selection.

Parameters:

  • space -- Space object.

  • argv -- Command line arguments.

  • interactive -- If True, prompt user to select project when multiple exist.

Returns:

Project object.

Raises:

ProjectNotFoundError -- If project is not found.

quickup.cli.api_client.get_list_for(space_obj, argv, interactive=False)[source]

Get list from CLI args or interactive selection.

Parameters:

  • space_obj -- Space object.

  • argv -- Command line arguments.

  • interactive -- If True, prompt user to select list when multiple exist.

Returns:

List object.

Raises:

ListNotFoundError -- If list is not found.

quickup.cli.api_client.get_current_sprint_list(team, space)[source]

Auto-detect current sprint list from team's lists.

Searches for lists containing "sprint" or "iteration" in the name (case-insensitive). Prefers the sprint explicitly marked as "started" (active). Falls back to sorting by ID descending (most recent first) if no started sprint is found.

Parameters:

  • team -- Team object.

  • space -- Space object (used to filter lists by space).

Returns:

List object for the current sprint.

Raises:

ListNotFoundError -- If no sprint lists are found.

cli.renderer

Terminal output rendering for QuickUp! CLI.

quickup.cli.renderer.render_list(list_obj, team_obj, no_cache: bool = False, assignee=None, priority=None, due_before=None, group_by='status', include_closed: bool = False, team=None, space=None, project=None, list_id=None)[source]

Render tasks from a list grouped by status, assignee, or priority.

Parameters:

  • list_obj -- List object from ClickUp.

  • team_obj -- Team object from ClickUp.

  • no_cache -- If True, bypass cache and fetch from API.

  • assignee -- Filter by assignee username (case-insensitive).

  • priority -- Filter by priority level (low, normal, high, urgent).

  • due_before -- Filter tasks due before date (YYYY-MM-DD).

  • group_by -- Group by "status" (default), "assignee", or "priority".

  • include_closed -- If True, include closed/done tasks.

  • team -- Team ID from command line.

  • space -- Space ID from command line.

  • project -- Project ID from command line.

  • list_id -- List ID from command line.

quickup.cli.renderer.render_task_detail(task)[source]

Render detailed task information.

Parameters:

task -- Task object from ClickUp.

quickup.cli.renderer.render_task_update(task_id, old_status, new_status)[source]

Render task status update confirmation.

Parameters:

  • task_id -- ClickUp task ID.

  • old_status -- Previous status name.

  • new_status -- New status name.

quickup.cli.renderer.render_task_comments(comments)[source]

Render list of comments for a task.

Parameters:

comments -- List of comment dicts from the ClickUp API.

quickup.cli.renderer.render_comment_posted(task_id, comment_text)[source]

Render comment posted confirmation.

Parameters:

  • task_id -- ClickUp task ID.

  • comment_text -- The comment text that was posted.

cli.config

Configuration and environment loading for QuickUp! CLI.

quickup.cli.config.init_environ()[source]

Load environment variables and resolve authentication token.

Token resolution order: 1. TOKEN from .env file (personal API token, backward compatible) 2. OAuth token from ~/.quickup/auth.json

Returns:

Environment variables as a dictionary.

Return type:

dict

cli.cache

Caching layer for QuickUp! CLI using sqlite3.

Provides TTL-based caching for ClickUp API responses to reduce API calls.

class quickup.cli.cache.SQLiteCache(db_path: str)[source]

SQLite-backed cache with TTL support using pickle serialization.

get(key: str)[source]
set(key: str, value, expire: int) → None[source]
delete(key: str) → None[source]
get_all_by_prefix(prefix: str) → list[source]

Return all non-expired values whose keys start with prefix.

get_stale_keys(prefix: str) → list[str][source]

Return keys matching prefix that have expired but not yet been deleted.

clear() → None[source]
quickup.cli.cache.get_cache() → SQLiteCache[source]

Get or create disk cache instance.

quickup.cli.cache.get_teams_data(clickup) → list[source]

Get teams data from cache or fetch from API.

Parameters:

clickup -- ClickUp client instance.

Returns:

List of team objects.

quickup.cli.cache.get_spaces_data(team) → list[source]

Get spaces data for a team from cache or fetch from API.

Parameters:

team -- Team object.

Returns:

List of space objects.

quickup.cli.cache.get_projects_data(space) → list[source]

Get projects data for a space from cache or fetch from API.

Parameters:

space -- Space object.

Returns:

List of project objects.

quickup.cli.cache.get_lists_data(project) → list[source]

Get lists data for a project from cache or fetch from API.

Parameters:

project -- Project object.

Returns:

List of list objects.

quickup.cli.cache.get_tasks_data(team, list_id: str, include_closed: bool = False) → list[source]

Get tasks data for a list from cache or fetch from API.

Parameters:

  • team -- Team object.

  • list_id -- ClickUp list ID.

  • include_closed -- If True, include closed/done tasks.

Returns:

List of task objects.

quickup.cli.cache.find_task_in_cache(task_id: str)[source]

Search all cached task lists for a task by ID.

Parameters:

task_id -- ClickUp task ID.

Returns:

Task object if found in cache, None otherwise.

quickup.cli.cache.get_task_data(clickup, team_id: str, task_id: str)[source]

Get a single task from cache or fetch from API.

Checks the per-task cache key first, then searches cached list entries, then falls back to fetching the task directly via the single-task endpoint (which includes subtasks). Always caches the result under 'task:{task_id}'.

Parameters:

  • clickup -- ClickUp client instance.

  • team_id -- Team ID to scope the API call.

  • task_id -- ClickUp task ID.

Returns:

Task object, or None if not found.

quickup.cli.cache.force_refresh_tasks(team, list_id: str) → list[source]

Fetch tasks unconditionally from API and overwrite cache.

quickup.cli.cache.maybe_warmup(token: str) → None[source]

Refresh any expired task cache entries before the command runs.

quickup.cli.cache.invalidate_tasks_cache(list_id: str) → None[source]

Invalidate cache for a specific list.

Parameters:

list_id -- ClickUp list ID.

quickup.cli.cache.clear_cache() → None[source]

Clear all cached data.

cli.auth

OAuth2 authentication flow for QuickUp! CLI.

quickup.cli.auth.get_oauth_config() → tuple[str, str][source]

Return (client_id, client_secret) from env vars or defaults.

quickup.cli.auth.load_oauth_token() → str | None[source]

Load the OAuth access token from ~/.quickup/auth.json.

quickup.cli.auth.save_oauth_token(token: str, user_info: dict | None = None) → None[source]

Save the OAuth access token to ~/.quickup/auth.json with restricted permissions.

quickup.cli.auth.delete_oauth_token() → bool[source]

Delete the stored OAuth token. Returns True if a token was removed.

quickup.cli.auth.perform_oauth_login() → tuple[str, dict][source]

Run the full OAuth2 login flow.

Opens the browser for authorization, starts a local server for the callback, exchanges the code for an access token, and fetches user info.

Returns:

Tuple of (access_token, user_info dict).

Raises:

RuntimeError -- If the OAuth flow fails at any step.

cli.exceptions

Custom exceptions for QuickUp! CLI with exit codes.

exception quickup.cli.exceptions.ClickupyError(message: str, hint: str | None = None)[source]

Base exception for QuickUp! CLI.

exit_code = 1
exception quickup.cli.exceptions.TokenError[source]

Raised when API token is invalid or missing.

exit_code = 1
exception quickup.cli.exceptions.TeamNotFoundError(team_id: str | None = None)[source]

Raised when team ID is invalid or no teams exist.

exit_code = 2
exception quickup.cli.exceptions.TeamAmbiguousError(team_names: list[str])[source]

Raised when multiple teams exist but no team ID is specified.

exit_code = 2
exception quickup.cli.exceptions.SpaceNotFoundError(space_id: str | None = None)[source]

Raised when space is not found.

exit_code = 2
exception quickup.cli.exceptions.ProjectNotFoundError(project_id: str | None = None)[source]

Raised when project is not found.

exit_code = 2
exception quickup.cli.exceptions.ListNotFoundError(list_id: str | None = None, hint: str | None = None)[source]

Raised when list is not found.

exit_code = 3
exception quickup.cli.exceptions.OAuthError(message: str = 'OAuth authentication failed.')[source]

Raised when OAuth authentication fails.

exit_code = 6
exception quickup.cli.exceptions.NetworkError(message: str = 'Network error occurred.')[source]

Raised for HTTP/connection failures.

exit_code = 4
exception quickup.cli.exceptions.APIError(message: str = 'ClickUp API error.', status_code: int | None = None)[source]

Raised for ClickUp API errors.

exit_code = 5
quickup.cli.exceptions.handle_exception(exc: ClickupyError) → None[source]

Print exception message and exit with appropriate code.