MicroGemLabs

Overview

mgl is the MicroGemLabs command-line interface — list monitors, work incidents, trigger runbooks, run skills, tail logs, send cron pings, and read the audit log, all from your shell. It talks to the same REST API as the dashboard, authenticates with a team API key, and supports --json on every read command so it drops straight into scripts and CI.

Package: @microgemlabs/cli · binary: mgl · Node 18+ · zero runtime dependencies.

Install

npm (the install path at launch):

npm install -g @microgemlabs/cli
mgl version

> Pre-launch note: the package isn't published to npm yet, so the line above won't resolve until launch. Until then, run it from source (below).

From source (works today):

git clone https://github.com/jasonm99coxnet/mgllabs
cd mgllabs/cli
npm install        # dev deps only (tsx, typescript) — no runtime deps
npm run build      # compiles src/ → bin/ via tsc
npm link           # puts mgl on your PATH
# …or skip npm link and run it directly:
node bin/mgl.js status

For quick hacking without a build, npm run dev -- <command> runs the TypeScript directly via tsx.

Authenticate

Most commands need a team API key (mgl_team_…). Create one in the dashboard under Account → API Keys, then:

mgl login

It prompts for the key and stores it at ~/.mgl/config.json (mode 0600).

Per-invocation override (handy in CI, where you'd inject the key as a secret):

MGL_API_KEY=mgl_team_xxx mgl status

The CLI acts with that key's team scope and permissions — the same rules as the UI apply (e.g. a key on a member-level context can run operational commands but is refused destructive ones).

> CronKeeper ping is the exception — it authenticates with the check's own slug/UUID, so mgl ping <slug> needs no API key.

Pointing at staging or local

By default mgl talks to production. Override the base URL per login or per call:

mgl login --api-url https://staging.microgemlabs.cloud
# or, one-off:
MGL_API_URL=https://staging.microgemlabs.cloud mgl status
MGL_API_URL=http://localhost:3000 mgl monitor list

Output & scripting

Every read command prints a human table by default and machine JSON with --json:

mgl incident list --json | jq '.incidents | length'
mgl monitor list --json | jq -r '.monitors[] | .name'

Exit codes (so you can branch in scripts/CI):

Code	Meaning
`0`	Success
`1`	Generic error (validation, parse, not found, unexpected)
`2`	Auth / permission error (401 / 403)

Command reference

CronKeeper — `ping`

mgl ping <slug>                      Send a success ping (no API key needed)
mgl ping <slug> --start              Mark a job started
mgl ping <slug> --complete           Mark a job completed (success)
mgl ping <slug> --fail               Mark a job failed
mgl ping <slug> --pause | --resume   Toggle monitoring for the check
mgl ping run <slug> -- <cmd>...      Wrap a command with start/complete/fail
                                     pings; the command's exit code passes through

The ping run wrapper is the most useful one — it sends a *start* before your command, then *complete* or *fail* based on the exit code:

mgl ping run db-backup -- pg_dump -Fc mydb -f backup.dump

LogVault — `tail`

mgl tail <stream-id> [--level=...] [--q=...]   Stream new log entries to stdout

mgl tail api-production --level=error
mgl tail api-production --q="timeout" --json

PulseGuardPlus — `monitor`

mgl monitor list
mgl monitor get <id>
mgl monitor create --name <n> --type <http|...> --target <url> [--interval <min>]
mgl monitor pause <id> | resume <id>
mgl monitor delete <id>

mgl monitor create --name api-health --type http --target https://api.example.com/health --interval 1

Incidents — `incident`

mgl incident list [--status=open|resolved|all]   open is the default
mgl incident ack <id>
mgl incident resolve <id>

Runbooks & Skills — `runbook`, `skill`

mgl runbook list
mgl runbook run <id> [--var k=v ...]

mgl skill list [--type=knowledge|executable|runbook] [--trustLevel=...]
mgl skill get <id> [--include=script]
mgl skill run <id> [--input k=v ...]

mgl runbook run restart-api --var region=us-east-1
mgl skill run abcd1234 --input env=prod --input region=us-east-1

> Runbooks/skills run through the same approval, cooldown, and circuit-breaker gates as the dashboard. A destructive action still requires approval — the CLI won't bypass it. See the Agent Skills Guide for what each runbook action type does.

Ops — `status`, `oncall`, `audit`, `webhook`

mgl status                          Platform health summary
mgl oncall                          Current on-call schedules + active alerts
mgl audit [--limit=N] [--action=...]   Recent audit-log entries

mgl webhook list
mgl webhook create --name <n> --url <url> [--secret <s>] [--events=*|t1,t2]
mgl webhook test <id>
mgl webhook delete <id>

mgl audit --action=proposal.approved --limit=5

Account & meta

mgl login           Authenticate (prompts for an mgl_team_… key)
mgl help            Full usage
mgl version         Print the version

Recipes

# Fail a CI step if anything is on fire
mgl incident list --json | jq -e '.incidents | length == 0'

# Restart the API as a post-deploy step
mgl runbook run restart-api --var region=us-east-1

# Wrap a cron job so CronKeeper tracks start / success / failure automatically
mgl ping run nightly-etl -- ./run-etl.sh

# Watch on-call while debugging
watch -n 30 mgl oncall

# Who approved the last few agent fixes?
mgl audit --action=proposal.approved --limit=10 --json | jq '.entries[] | {actor, createdAt}'

Notes

Global flags work on any command: --json (machine output) and --api-url <url> (override the base URL; same as MGL_API_URL).
Config lives at ~/.mgl/config.json (0600). Delete it to "log out".
The CLI is a thin client over the public REST v1 API — anything it does, you can do with a raw Authorization: Bearer mgl_team_… request. The endpoint reference is in the MicroGemAgent guide.

Command-Line Interface (mgl)