@mm-pm/empire-auth

gcloud-style login CLI for the Empire platform. Log in through the browser once, then let your scripts and tools fetch a valid Auth0 ID token on demand — instead of copying a token out of browser devtools and pasting it around.

Install

npm install -g @mm-pm/[email protected]

Or run it without installing anything:

npx @mm-pm/[email protected] login

Requires Node 20 or newer.

Pin the version rather than letting npx float to whatever is newest. npx @mm-pm/empire-auth without a version re-resolves on every run, so anything published to this name later would execute on your machine automatically — and this tool holds live credentials. Bump the pin deliberately when a new version is announced.

Usage

empire-auth login                # browser login (production)
empire-auth login --env qa       # staging
empire-auth token                # print a valid ID token (refreshes silently)
empire-auth whoami               # show your email + roles, as the platform sees them
empire-auth logout               # revoke the refresh token and delete local credentials

login opens your browser. Once you've signed in, the terminal picks it up automatically and you're done — you won't need to log in again for weeks, and token renews itself in the background.

Credentials are stored per environment in ~/.empire/credentials-<env>.json, readable only by you (0600).

Using it from a script or an AI coding tool

token prints the token to stdout and nothing else, so it composes with anything:

TOKEN=$(empire-auth token)
curl -H "Authorization: Bearer $TOKEN" "$API_URL/some/endpoint"

import { execFileSync } from 'child_process';
const token = execFileSync('empire-auth', ['token'], { encoding: 'utf8' }).trim();

Fetch the token at the moment you need it rather than storing it in a file or pasting it into a prompt. Tokens are short-lived, so a copied one stops working within hours — calling token each run avoids that entirely, and keeps credentials out of your shell history and chat logs.

Troubleshooting

Not logged in to prod — run empire-auth login. This also appears when your session has finally expired; the fix is the same.

The browser didn't open — login prints the URL it wanted to open. Paste it into a browser on the same machine.

All callback ports are busy — the CLI listens on ports 8765–8767 to receive the login. Close whatever is using them, or finish any other empire-auth login still waiting in another terminal.

Token rejected — your login worked but the platform doesn't recognise the account. Check empire-auth whoami; if your email looks wrong, empire-auth logout and log in again with the right account.

Remote / SSH machines are not supported — the browser has to be able to reach localhost on the same machine the CLI runs on.

How it works

• Standard OAuth 2.0 authorization code flow with PKCE, against Empire's own Auth0 client — a public client with no secret — so the platform accepts these tokens with no backend change.
• The browser redirect comes back to a short-lived local listener on 127.0.0.1 (ports 8765–8767) that shuts down as soon as login completes, times out after 5 minutes, and is never reachable from another machine.
• Your refresh token is rotated on every use, so a leaked copy stops working the next time you run token. logout revokes it centrally rather than only deleting the local file.