Skip to content

feat: List command for browsing and filtering user uploads

Bhaskar Battula requested to merge listing-commands into develop

📌 What is this MR?

This MR introduces a new list command to the CLI, enabling users to browse and manage their uploaded corpus records directly from the terminal.

Previously, users had to rely on the web frontend to view records. This change brings feature parity to the CLI and supports a fully terminal-based workflow.

⚙️ What does it do?

The corpus-client list command:

  • Fetches records via GET /api/v1/users/{user_identifier}/contributions and GET /api/v1/users/{user_identifier}/contributions/{media_type}
  • Displays results in a formatted terminal table using Rich
  • Supports:
    • Pagination (--page, --size)
    • Filtering (--type, --language, --from, --to)
    • Sorting (--sort)
  • Provides clear error handling for:
    • Unauthenticated users
    • Expired tokens (401)
    • API/connection failures
  • Follows existing CLI architecture:
    • Thin Typer command in cli.py
    • Business logic in records.py

✅ Acceptance Criteria

  • Running corpus-client list displays a paginated table of records (default: page 1, 20 per page)
  • Table includes columns: #, ID, Title, Type, Language, Created
  • Pagination info is shown (Showing page X of N)
  • Filtering works for:
    • Media type (--type)
    • Language (--language)
    • Date range (--from, --to)
  • Sorting works with --sort
  • Pagination works with --page and --size
  • Combined filters work correctly
  • Empty results display "No records found."

🧪 Testing

  • Unit tests added for:
    • fetch_records() (API calls, headers, error handling)
    • display_records() (table rendering, pagination, empty states)
    • run_list_records() (error routing)
    • CLI command auth guard and parameter passthrough
  • Manual testing completed against dev API

🧩 Implementation Details

  • Added new module: src/corpus_client_cli/records.py
  • Updated CLI entrypoint: cli.py to include list command
  • Added rich as a dependency for terminal formatting
  • Defensive handling of API response formats (results, items, list)

🔚 Closes

Closes: #5 (closed) (Related to ROADMAP Priority 2 – Fetch/Retrieve Features)

Merge request reports