RFC: prompt-cli - Cobra-based Admin CLI

[Mtze]

Motivation

Administrators currently interact with PROMPT 2.0 exclusively through the web UI. A CLI tool (prompt-cli) would enable scripting, bulk operations, and CI/CD workflows for managing courses, phases, students, and other resources.

This discussion proposes the design of prompt-cli, a standalone Go CLI built with Cobra.

---

Architecture

prompt-cli lives in a new cli/ directory at the repo root as a standalone Go module (github.com/prompt-edu/prompt/cli). It does not import any server packages - it only speaks JSON over HTTP to the existing REST APIs. This keeps it decoupled from internal database types (pgtype, sqlc, etc.).

cli/
  go.mod                        # standalone module, go 1.26
  main.go
  cmd/                          # one file per command group
    root.go                     # --output, --config, --server flags
    login.go / logout.go / whoami.go
    course.go / phase.go / student.go
    application.go / interview.go
    team.go / assessment.go
  internal/
    auth/                       # Keycloak ROPC token fetch + refresh + storage
    config/                     # config file + env var management (viper)
    client/                     # typed HTTP clients per service
    output/                     # table + JSON formatters
    types/                      # plain Go types matching JSON wire format

---

Command Hierarchy

prompt-cli
  login                         # authenticate with Keycloak, store token
  logout                        # delete stored token
  whoami                        # print username + roles from JWT

  course
    list / get / create / update / delete / archive

  phase
    list <course-id> / get / create / update / delete / participations

  student
    list / get / search / enrollments / create / update

  application
    list <phase-id> / get / score / form

  interview
    slots list/create/delete
    assignments list

  team
    list/get/create/update/delete
    skills list/create

  assessment
    schema list/create
    category list
    evaluation list
    grade list

Global flags: --output table|json, --config <path>, --server <url>

---

Authentication

The CLI uses the Resource Owner Password Credentials (ROPC) grant against Keycloak. prompt-client has directAccessGrantsEnabled: true, making this the right choice for a trusted admin CLI without a browser redirect.

Flow:

1. prompt-cli login prompts for username + password (masked input)
2. POST to {KEYCLOAK_URL}/realms/prompt/protocol/openid-connect/token with grant_type=password
3. Tokens stored at ~/.config/prompt-cli/tokens.json (mode 0600)
4. Access token is auto-refreshed transparently before expiry; if refresh fails, user is prompted to re-login

Config (~/.config/prompt-cli/config.yaml) stores service URLs, Keycloak URL, realm, and client ID. Priority order: CLI flags > env vars (PROMPT_CORE_URL, etc.) > config file > compiled-in defaults (localhost ports).

---

Dependencies

Package	Purpose
github.com/spf13/cobra	CLI framework
github.com/spf13/viper	Config + env vars
github.com/olekukonko/tablewriter	ASCII table output
github.com/google/uuid	UUID parsing
golang.org/x/term	Masked password input

No server packages, no pgx, no sqlc, no Gin.

---

Required Backend Changes

Most CLI commands map to existing endpoints. Three GET endpoints are missing and need to be added:

1. GET /api/course_phases/course/{courseID} (core service)

List all phases belonging to a course. Currently only POST exists on this path. The data is already available (the GET /api/courses/{uuid} endpoint embeds phases), so this is a matter of exposing a dedicated list handler.

2. GET /api/applications/{coursePhaseID} (core service)

List all applications for a course phase. Currently only POST (create) and DELETE exist. The underlying query almost certainly exists - it just needs a GET route wired up.

Note: As a short-term workaround, GET /api/applications/{coursePhaseID}/participations could substitute if participation data is sufficient.

3. GET /interview/api/course_phase/{coursePhaseID}/interview-assignments (interview service)

List all interview assignments for a phase. Currently only POST exists for creating assignments.

---

Phased Implementation

Phase	Scope
1 - Foundation	Module setup, config, Keycloak auth, HTTP base client, login/logout/whoami, Makefile targets
2 - Core	Course, phase, student commands
3 - Applications	Application commands
4 - Microservices	Interview, team, assessment commands
5 - Polish	Shell completion, config set/get, dynamic UUID tab-completion

---

Makefile Integration

cli-build:   ## Build prompt-cli to bin/prompt-cli
cli-install: ## Install to $GOPATH/bin
cli-lint:    ## go vet
cli-test:    ## go test

lint and test targets will be updated to include the CLI module.

---

Open Questions

• Should prompt-cli be distributed as a pre-built binary (GitHub Releases) or only built from source?
• Are there endpoints where the ROPC grant would be insufficient (e.g., admin-only routes that check for specific Keycloak roles not accessible to regular user accounts)?
• Should the three missing GET endpoints be added as part of this feature branch or as separate PRs against main?