Badgie CLI: run your club from the terminal
Badgie's official command-line tool: npm install, sign-in, chat with the club agent, slash commands, command mode with --json for scripts and agents, and updates.
6 min readAdvancedUpdated October 2, 2026
Quick answer
Badgie CLI (@badgie/cli) is Badgie's official command-line tool: «sport, in your terminal». Install it with npm i -g @badgie/cli (or try it with npx @badgie/cli), authorise it with badgie login, and talk to your club's agent or run tools from the terminal, always with your role. Every command accepts --json for scripts and AI agents. It needs Node.js 20 or later.
In this guide
Where to find it
- npm package:
@badgie/cli(version 1.5.5 in October 2026). Command:badgie. - Runs on any system with Node.js 20 or later (macOS, Linux and Windows).
- It is a client of the Badgie MCP server: same tools, same sign-in with your account and the same Delegation.
- The CLI's own messages are in Spanish.
Commands
badgieorbadgie chat: talk to your club's agent.badgie login: sign in with your Badgie account (opens the browser).badgie logout: sign out and delete local tokens.badgie whoami [--json]: show your role and school.badgie tools [filter] [--json]: list what you can do (your role's tools).badgie run <tool> [key=value…] [--args '<json>'] [--json]: run a tool. Reads return data; writes follow your club's Delegation.badgie update [--check] [--json] [--channel <dist-tag>]: update the CLI to the latest published version.badgie repl: the classic tool REPL, without the agent.
Step by step
- Install the CLI:
npm i -g @badgie/cli(or usenpx @badgie/cliwithout installing). - Sign in:
badgie login. The browser opens, you log in with your Badgie account and approve access. - Check who you are:
badgie whoami. - See what you can do:
badgie tools. The catalogue depends on your role. - Run a tool, for example
badgie run get_top_debtors limit=10. For nested arguments use dot notation (payload.student_id=…) or pass the full JSON with--args. - Or just type
badgieand chat with your club's agent.
Without a session, commands that need your account say so: «No has iniciado sesión. Ejecuta badgie login.» (you are not signed in; run badgie login).
Inside the chat
Type / and press Tab or → to complete. Each role sees its own commands.
- Club:
/hoy(today: classes, roll calls not taken, alerts),/semana(the week in figures),/pendientes(proposals waiting for your OK),/deudores(who owes money),/alumno <name>,/insignias,/asistencia [group],/leads,/mensaje <to whom> <what>(drafts and proposes a send),/cantera(football teams, fixtures and results),/swing [student],/informe <topic>,/recuerda <fact>and/memoria. - Session:
/model [level](fast, balanced or maximum),/bienand/mal [what failed]to rate the last answer,/nuevo,/creditos,/whoami,/tools [filter],/run <tool> k=v…(without the agent),/limpiar,/ayuda,/logoutand/salir.
It is the same agent you have in the dashboard and the app, with the same club credits.
For scripts and AI agents
- Add
--jsontowhoami,tools,runorupdateto get JSON output designed for agents and scripts. - To keep the CLI up to date unattended:
badgie update --check --json | jq -e '.updateAvailable' >/dev/null && badgie update --json. - Environment variables:
BADGIE_NO_UPDATE_NOTIFIER=1(silences the new-version notice),BADGIE_DISABLE_UPDATES=1(blocks updates),BADGIE_UPDATE_CHANNEL(channel, latest by default) andBADGIE_REGISTRY(alternative npm registry). badgie updateuses the package manager you installed it with.
Examples by role
You do not choose the role: it comes from your Badgie account.
- School account:
badgie run get_top_debtors,badgie run list_action_catalog(actions you can propose) andbadgie run list_my_proposals(status of your proposals). - Coach:
badgie run my_classes_today,badgie run my_students,award_badgeto award badges andrecord_attendanceto take the roll. - Student or family:
badgie run my_badges,badgie run my_schedule,badgie run my_paymentsandbadgie run my_golf_stats.
Frequently asked questions
Is it safe?
Yes. You authorise with your account in the browser (OAuth 2.1) and the CLI never sees your password. It acts with your role, never sees another school's data, and anything sent to families or published waits for your approval. badgie logout deletes the local tokens.
Is it suitable for AI agents and scripts?
Yes. --json gives stable output for agents such as OpenClaw or Claude Code, CI pipelines and scheduled jobs.
Do I need to know how to code?
Not for the chat: just type badgie and talk. run and --json are for those who want to automate.
Is there a public REST API instead of the CLI?
No. Badgie does not offer a public REST API with keys or outgoing webhooks. The developer route is the MCP server and Badgie CLI.
Does it use credits?
Chatting with the agent uses club credits, just like in the dashboard (/creditos shows the balance). run and repl run tools without going through the agent.