blackboard-cli

Accede a UPC Aula Virtual desde la terminal — sin abrir el navegador.

CLI no oficial para estudiantes de la UPC. Consulta cursos, descarga materiales, revisa tareas y entregas directamente desde la línea de comandos. También expone un servidor MCP para que Claude lo use como herramientas nativas.

npx blackboard-upc login

Instalación

# Opción 1 — usar directamente con npx (sin instalar)
npx blackboard-upc login

# Opción 2 — instalar globalmente
npm install -g blackboard-upc
blackboard login

# Opción 3 — clonar el repo
git clone https://github.com/alejooroncoy/blackboard-cli
cd blackboard-cli
npm install
npx playwright install chromium
node run.js login

Primeros pasos

1. Login

blackboard login

Se abre una ventana del navegador con el login de Microsoft UPC. Inicia sesión con tu cuenta [email protected] (incluye MFA si lo tienes). La ventana se cierra sola y la sesión queda guardada 8 horas.

Importante: durante el login, Microsoft mostrará el mensaje "Stay signed in?" con un checkbox "Don't show this again". Activa ese checkbox y haz clic en Yes — esto le indica a Microsoft que mantenga la sesión activa y es necesario para que el CLI pueda guardar las cookies correctamente.

  ██████  ██       █████   ██████ ██   ██ ██████   ██████   █████  ██████  ██████
  ...
  CLI no oficial para UPC Aula Virtual · Blackboard Learn

  ✓ Sesión guardada — expira en 8 horas
    Usuario: Juan Pérez García

  ¿Qué puedo hacer ahora?

  blackboard courses list                ver tus cursos del ciclo
  blackboard assignments list <id>       ver tareas pendientes y notas
  blackboard courses contents <id>       explorar materiales
  blackboard download-folder <id> <fid>  descargar toda una carpeta

2. Ver cursos y tareas

blackboard courses list

  _100001_1  Cálculo Diferencial e Integral [Ultra]
  _100002_1  Programación Orientada a Objetos [Ultra]
  _100003_1  Bases de Datos [Ultra]
  _100004_1  Algoritmos y Estructuras de Datos [Ultra]

blackboard assignments list _100004_1

  _200001_1  Tarea 1  [manual]
    Nota: sin entregar · Máx: 5 pts · Entrega: 15/04/2026 (vence en 17d)

Comandos

Sesión

blackboard login              # autenticación Microsoft SSO
blackboard logout             # borrar sesión
blackboard whoami             # usuario activo y tiempo restante
blackboard status             # versión del servidor Blackboard

Cursos

blackboard courses list
blackboard courses get <courseId>
blackboard courses contents <courseId>
blackboard courses contents <courseId> --parent <folderId>   # navegar subcarpetas
blackboard courses contents <courseId> --type file|folder|assignment
blackboard courses announcements <courseId>
blackboard courses grades <courseId>

Tareas

blackboard assignments list <courseId>              # tareas con nota y fecha
blackboard assignments list <courseId> --pending    # solo pendientes
blackboard assignments attempts <courseId> <id>     # historial de entregas
blackboard assignments submit <courseId> <id> -f tarea.pdf
blackboard assignments submit <courseId> <id> -t "Mi respuesta" -c "Comentario"
blackboard assignments submit <courseId> <id> -f borrador.pdf --draft

Descargas

blackboard download <courseId> <contentId>                    # archivo individual
blackboard download-folder <courseId> <folderId> -o ./dir/    # carpeta completa
blackboard download-folder <courseId> <folderId> --filter "parcial"

API raw / scripting

blackboard api GET /learn/api/public/v1/users/me
blackboard api GET /learn/api/public/v1/courses -q "limit=10"
blackboard endpoints          # catálogo de todos los endpoints conocidos
blackboard endpoints --json   # para pipelines

Todos los comandos aceptan --json. Los spinners van a stderr, por lo que --json 2>/dev/null es JSON limpio.

Uso con Claude (MCP)

blackboard-cli incluye un servidor MCP que Claude puede usar como herramientas nativas.

Claude Code

Añade a .mcp.json en tu proyecto:

{
  "mcpServers": {
    "blackboard": {
      "command": "npx",
      "args": ["blackboard-upc", "mcp"]
    }
  }
}

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "blackboard": {
      "command": "npx",
      "args": ["blackboard-upc", "mcp"]
    }
  }
}

Nota: Si usas instalación global, reemplaza npx blackboard-upc por la ruta absoluta del binario (which blackboard).

Herramientas MCP disponibles

| Herramienta | Descripción | |---|---| | whoami | Info del estudiante autenticado | | list_courses | Cursos inscritos | | get_course | Detalle de un curso | | list_contents | Árbol de materiales | | list_announcements | Anuncios del curso | | list_assignments | Tareas con fechas y notas | | list_attempts | Historial de entregas | | get_grades | Notas del ciclo | | list_attachments | Archivos de un contenido | | download_attachment | Descargar archivo (base64) | | submit_attempt | Entregar tarea (pide confirmación) | | raw_api | Cualquier endpoint de Blackboard |

Con Claude puedes hacer cosas como:

"¿Qué tareas tengo pendientes esta semana?" "Descárgame todos los exámenes del curso de Finanzas" "¿Cuál es mi nota actual en Arquitectura de Software?"

Cómo funciona la autenticación

UPC usa SAML SSO → Microsoft Azure AD. El CLI:

1. Abre Chromium (Playwright) en la URL SAML de UPC
2. Te muestra el login de Microsoft — tú ingresas tus credenciales
3. Captura las cookies de sesión automáticamente al redirigir a /ultra
4. Guarda todo en ~/.blackboard-cli/session.json (permisos 600)

La sesión dura 8 horas. Después necesitas volver a hacer login.

Stack

• TypeScript + tsx — sin build step
• Playwright — maneja el flujo SAML/SSO
• Axios — llamadas a la REST API con cookies de sesión
• Commander.js — framework CLI
• MCP SDK — servidor para Claude
• Chalk + Ora — output en la terminal

Notas

• Probado con Blackboard Learn v4000.10.0 (UPC, 2026).
• CLI no oficial — sin afiliación con UPC ni Blackboard Inc.
• Úsalo solo con tu propia cuenta. Respeta los TOS de UPC.
• Las cookies se guardan localmente. No se envían a servidores externos.

Licencia

MIT