Badgie CLI

Opera tu escuela, club o academia deportiva desde la terminal. Para humanos y para agentes.

Badgie CLI es el harness oficial de línea de comandos de Badgie, la plataforma de gestión deportiva. Es un cliente del Badgie MCP (el servidor MCP oficial de Badgie), así que reutiliza todo lo que ya conoces: tu cuenta, tu rol y el catálogo completo de acciones — alumnos, insignias, clases, finanzas, reservas, torneos, comunicaciones, golf y mucho más.

Un binario, dos modos:

• Modo interactivo (REPL) — escribe badgie y opera tu escuela conversando con la terminal.
• Modo comando — badgie run <accion> --json para scripts, CI y agentes IA.

Instalación

npm i -g @badgie/cli

Y arranca:

badgie

Requiere Node.js ≥ 18.

Quickstart

1. Inicia sesión (abre el navegador — OAuth 2.1 con tu cuenta Badgie):

badgie login

2. Comprueba quién eres (rol + escuela):

badgie whoami

3. Mira qué puedes hacer (el catálogo se filtra por tu rol):

badgie tools

4. Ejecuta acciones:

# Consulta genérica de datos de tu escuela (~346 tablas bajo tu RLS)
badgie run query_data table=badge limit=5

# Argumentos como pares key=value (con dot-notation para anidar)…
badgie run get_top_debtors limit=10

# …o el payload completo en JSON con --args (ideal para acciones anidadas)
badgie run students.set_avatar --args '{"action_type":"students.set_avatar","payload":{"student_id":"…","avatar":"adventurer"}}'

5. O simplemente entra al REPL y trabaja en conversación:

badgie

  ★ Badgie — tu escuela desde la terminal
  Escuela Ejemplo · owner · [email protected]

badgie> tools
badgie> run query_data table=student limit=10
badgie> run propose_action --args '{"action_type":"communications.send","payload":{…},"summary":"Recordatorio cuota julio"}'

Las escrituras sensibles no se ejecutan directamente: el CLI las propone y el humano las aprueba en el dashboard de Badgie (/dashboard/agent). Human-in-the-loop de serie.

Comandos

| Comando | Qué hace | |---------|----------| | badgie | REPL interactivo (banner + sesión conversacional) | | badgie login | Autoriza el CLI con tu cuenta Badgie (navegador, OAuth 2.1 + PKCE) | | badgie logout | Cierra la sesión local | | badgie whoami | Tu identidad: rol, escuela, email | | badgie tools | Lista las acciones disponibles para tu rol | | badgie run <accion> [k=v…] [--args '<json>'] [--json] | Ejecuta o propone una acción |

Argumentos de run:

• Pares key=value — se coercionan a number/boolean/null automáticamente y admiten dot-notation (payload.student_id=…).
• --args '<json>' — payload base completo en JSON; los pares key=value se aplican encima.
• --json — salida JSON pura (sin colores ni banner), pensada para máquinas.

Por rol

El rol no se elige: se deriva de tu cuenta Badgie en el servidor. Cada rol ve un catálogo distinto.

🏫 Owner (cuenta de escuela)

Lectura universal del negocio + propuestas de acción:

badgie run get_school_profile
badgie run query_data table=fin_invoices limit=20
badgie run get_top_debtors
badgie run list_action_catalog          # ~24 tipos de acción proponibles
badgie run list_my_proposals            # estado de tus propuestas

~51 tools: asistencia, riesgo de abandono, MRR, deuda, ocupación de reservas, progreso de colecciones, nutrición, drills… cada una gated por el módulo correspondiente de tu escuela.

🧑‍🏫 Teacher (profesor)

Tu día a día, scoped a tus clases y alumnos:

badgie run my_classes_today
badgie run my_students
badgie run award_badge --args '{"student_id":"…","badge_id":"…"}'
badgie run record_attendance --args '{"event_id":"…","records":[…]}'

🎽 Student / familia

Tus datos y solo los tuyos:

badgie run my_badges
badgie run my_schedule
badgie run my_payments
badgie run my_golf_stats

Para agentes y scripts

El CLI está diseñado para que un agente (OpenClaw, Claude, ChatGPT, un cron de CI…) opere Badgie sin fricción:

• --json en cualquier comando → salida JSON estable, sin decoración.
• Exit codes limpios: 0 éxito, distinto de cero en error (con el error legible en stderr).
• Mismo backend que un cliente MCP: es el Badgie MCP oficial, así que un agente que ya hable MCP puede conectarse directo a https://www.badgie.com/api/mcp/mcp; el CLI es la vía cómoda cuando el agente vive en una shell.
• Sin estado sorpresa: la sesión vive en ~/.badgie, portable entre invocaciones.

# Ejemplo: informe diario en un script
badgie run my_classes_today --json | jq '.classes[] | {name, start, students}'

Seguridad

• OAuth 2.1 + PKCE: badgie login abre el navegador y autorizas con tu cuenta Badgie. El CLI nunca ve tu contraseña.
• Scoping por rol, en el servidor: owner / teacher / student se derivan de la base de datos, nunca del cliente. La RLS de Badgie aplica en cada llamada.
• Nunca cross-tenant: jamás verás datos de otra escuela ni de otro alumno.
• Human-in-the-loop: las escrituras sensibles se registran como propuestas que un humano aprueba en el dashboard. Los datos de menores siempre pasan por aprobación humana.
• Tokens en local con permisos estrictos: ~/.badgie/auth.json se guarda con modo 0600.

Configuración

| Qué | Dónde | |-----|-------| | Sesión y tokens | ~/.badgie/auth.json | | Preferencias | ~/.badgie/config.json | | BADGIE_MCP_URL | Override del endpoint MCP (dev/staging). Default: https://www.badgie.com/api/mcp/mcp | | BADGIE_ORIGIN | Override del origen OAuth. Default: https://www.badgie.com |

# Apuntar el CLI a un entorno de desarrollo
BADGIE_MCP_URL=http://localhost:3000/api/mcp/mcp badgie whoami

Enlaces

• 🌐 www.badgie.com/cli — página del CLI
• 📚 Documentación del Badgie MCP — arquitectura, roles y catálogo de acciones
• 🏅 Badgie — la plataforma
• ✉️ [email protected]

Hecho con ⭐ por Badgie Sports App, S.L. · MIT