Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
#!/usr/bin/env node
// Writes docs/CLI.md from `bin/mso --help`. The help text lives in ONE place (the
// comment header of bin/mso, which the CLI prints verbatim), so the doc cannot
// drift from the tool. Run after changing the header:
//
// node scripts/gen-cli-docs.mjs # write
// node scripts/gen-cli-docs.mjs --check # exit 1 if stale (used by a test)
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
const root = join(dirname(fileURLToPath(import.meta.url)), "..");
const out = join(root, "docs/CLI.md");
// MSO_ENV=/dev/null: the help must never depend on a machine's secrets file.
const help = execFileSync(join(root, "bin/mso"), ["--help"], {
encoding: "utf8",
env: { ...process.env, MSO_ENV: "/dev/null" },
}).trimEnd();
const doc = `<!-- GENERATED by scripts/gen-cli-docs.mjs — edit the header of bin/mso, not this file. -->
# MSO CLI
The browser UI at your instance's domain is one frontend, not the product. \`mso\`
reaches the same \`/api\` surface from a shell, so every feature is scriptable.
\`scripts/install.sh\` verifies and launches \`scripts/install-core.sh\`, which symlinks \`bin/mso\` to \`~/.local/bin/mso\`. To install it by
hand from a checkout:
\`\`\`bash
ln -s "$PWD/bin/mso" ~/.local/bin/mso
eval "$(mso completion bash)" # optional: tab completion
\`\`\`
## First run
\`\`\`bash
mso doctor # deps, HTTPS/login origin, service, session, device — names what broke
mso doctor --fix # safe local repairs; never changes DNS/TLS/firewall/credentials
mso device pending # after a browser tries to log in, approve it from here
\`\`\`
The CLI signs in with \`OS_LOGIN_PASSWORD\` from your \`.env.local\` and its own
device id (\`~/.mso/cli.device.id\`), which you approve once:
\`\`\`bash
mso device approve "$(cat ~/.mso/cli.device.id)" "mso cli"
\`\`\`
Browser sign-in must use **HTTPS**, except for loopback development/access such as
\`http://localhost:4005\`. Plain \`http://<server-ip>:4005\` may answer health/API requests,
but the browser cannot retain MSO's \`Secure\` session cookie there. Pair the device on its final
HTTPS/localhost origin; \`mso doctor\` reports this explicitly.
Device and service commands work even while the service is down — that is on
purpose, because those are exactly the commands you need when it is.
## Reference
\`\`\`
${help}
\`\`\`
## Notes
- **Every non-browser caller must send \`Origin: <base>\`.** \`proxy.ts\` blocks
mutating \`/api\` requests that cannot prove same-origin; a browser proves it with
\`Sec-Fetch-Site\`, and the documented fallback is an \`Origin\` whose host matches
\`Host\`. \`mso\` does this for you. Without it, login itself returns 403
\`cross_origin_blocked\` — before any device check — which looks like an approval
problem and is not.
- \`--base\` targets another instance; the cookie jar is keyed by base, so switching
never reuses a session minted for a different origin.
- \`raw\`, \`zip\` and \`term stream\` stream to stdout — redirect them to a file.
`;
if (process.argv.includes("--check")) {
const current = (() => {
try {
return readFileSync(out, "utf8");
} catch {
return "";
}
})();
if (current !== doc) {
console.error("docs/CLI.md is stale — run: node scripts/gen-cli-docs.mjs");
process.exit(1);
}
console.log("docs/CLI.md is current");
} else {
writeFileSync(out, doc);
console.log(`wrote ${out}`);
}