javer-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javer Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# javer-cli
+
+Javer Webhost from the command line — apps, virtual machines, databases and
+domains, without opening the panel.
+
+No dependencies. Node 18 or newer.
+
+```bash
+npm install -g javer-cli
+```
+
+## Getting a key
+
+Create one at [panel.javer.pro/api-keys](https://panel.javer.pro/api-keys), then:
+
+```bash
+javer login
+```
+
+It saves to `~/.javer/config.json`, readable only by you.
+
+A key does not expire and is not scoped — it can do anything your account can.
+Revoke it from the panel when you are finished with it; `javer logout` only
+forgets the local copy.
+
+## The live dashboard
+
+```bash
+javer ui
+```
+
+Apps and virtual machines on one screen, with the resource budget they share
+across the top. Arrow keys select; `s` starts or stops, `r` restarts, `l` drops
+to logs, `q` quits. It refreshes every four seconds.
+
+Stopping or restarting asks first.
+
+## Apps
+
+```bash
+javer ls                          # everything you are running
+javer status <app>                # size, host, address
+javer logs <app>                  # recent output
+javer logs <app> -f               # keep watching
+javer env <app>                   # values hidden
+javer env <app> --show            # values in full
+javer domains <app>               # custom domains and whether they verified
+javer start|stop|restart <app>
+javer delete <app>                # asks you to type the name
+```
+
+`logs -f` polls every two seconds and prints what is new. The server returns the
+last 300 lines as a snapshot rather than a stream, so this is a poll, not a tail.
+
+## Deploying
+
+```bash
+javer deploy                              # this folder
+javer deploy --repo owner/name            # a connected GitHub repo
+javer deploy --repo owner/name --branch main --ram 512 --cpu 0.5
+```
+
+With no `--repo` it packs the directory you are standing in and uploads it. The
+folder name becomes the app name unless you pass `--name`.
+
+Left out of the upload automatically: `node_modules` (the server installs
+dependencies itself), `.git`, build output, logs, and `.env` — environment
+variables belong in the panel, not baked into a deployment.
+
+Uploads are capped at **2 MB** after compression. Past that, deploy from GitHub.
+
+Two things the platform requires, worth knowing before your first deploy:
+
+- **Read `process.env.PORT`.** Javer assigns the port. An app that hardcodes one
+  starts, looks healthy, and returns 502, because nothing is listening where the
+  traffic is being sent.
+- **The entry file must be `server.js`** at the root, or `index.html` for a
+  static site. A `start` script in `package.json` is not read.
+
+## Virtual machines
+
+```bash
+javer vms                         # list them
+javer vm <name>                   # details, including live memory and CPU
+javer vm start|stop|restart <name>
+```
+
+SSH from your own machine is not available — VMs sit on a private network with
+no route in. Use the browser terminal in the panel.
+
+## Databases
+
+```bash
+javer db                          # list them
+javer db create <name>            # PostgreSQL
+javer db create <name> --engine mysql
+```
+
+Credentials print once, on creation, and are not stored anywhere they can be
+read back. A database is reachable only from inside Javer, so you cannot connect
+from your laptop with `psql` or TablePlus.
+
+## Your plan
+
+```bash
+javer whoami
+```
+
+Shows the account's RAM, CPU and slot budget and what is left. The item count
+includes virtual machines as well as apps.
+
+## In a pipeline
+
+Set `JAVER_API_KEY` instead of logging in, so nothing is written to disk:
+
+```bash
+JAVER_API_KEY=<key> javer deploy --repo myorg/myapp --branch main
+```
+
+`javer deploy` follows the build and exits non-zero if it fails, so it works as
+a build step. `javer delete` refuses to run without a terminal to confirm in
+unless you pass `--yes`.
+
+## Pointing somewhere else
+
+```bash
+JAVER_API_URL=http://localhost:3000 javer ls
+```
+
+Both variables take precedence over the saved file.
+
+## Full command list
+
+```
+javer ui                                  live dashboard: apps + VMs
+javer login [--key <key>] [--url <url>]   save an API key
+javer logout                              forget the saved key locally
+javer whoami                              plan limits and what is left
+javer ls                                  list your apps
+javer status <app>                        details for one app
+javer logs <app> [-f]                     recent output; -f keeps watching
+javer env <app> [--show]                  environment variables
+javer domains <app>                       custom domains
+javer start|stop|restart <app>            lifecycle
+javer delete <app> [--yes]                remove an app, its data and its URL
+javer vms                                 list virtual machines
+javer vm <name>                           details for one VM
+javer vm start|stop|restart <name>        VM lifecycle
+javer db                                  list databases
+javer db create <name> [--engine mysql]   new Postgres or MySQL
+javer deploy                              deploy the folder you are in
+javer deploy --repo owner/name            deploy from a connected GitHub repo
+javer version | help
+```

package/index.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+// javer — command-line interface for Javer Webhost.
+//
+// Authenticates with an API key (created at panel.javer.pro/api-keys) rather
+// than email+password: the server's requireAuth accepts a `jvr_live_` bearer
+// token on every route the dashboard uses, so anything you can click you can
+// script.
+const config = require('./lib/config');
+const ui = require('./lib/ui');
+const { zipDir } = require('./lib/zip');
+const bird = require('./lib/bird');
+const api = require('./lib/api');
+const { version } = require('./package.json');
+
+// ── arg parsing ────────────────────────────────────────────────────────
+// Hand-rolled rather than a dependency: the grammar is `javer <cmd> [pos]
+// [--flag value]`, which is a dozen lines. A parser library would be most of
+// this package's install weight.
+const parseArgs = (argv) => {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('--')) {
+      const name = argv[i].slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) { flags[name] = true; }
+      else { flags[name] = next; i++; }
+    } else {
+      positional.push(argv[i]);
+    }
+  }
+  return { positional, flags };
+};
+
+const die = (msg, code = 1) => { console.error(`error: ${msg}`); process.exit(code); };
+
+// Both deploy paths — a GitHub repo and this folder — start a build and then
+// watch it the same way, so the watching lives here once.
+const followDeploy = async (started) => {
+  const deployId = started.deployment?.id;
+  if (!deployId) {
+    // The server answered with a shape we do not know. Show it rather than
+    // pretending it worked or crashing on undefined.
+    console.log(JSON.stringify(started, null, 2));
+    return;
+  }
+  let last = '';
+  for (;;) {
+    const { deployment } = await api.get(`/apps/deployments/${deployId}`);
+    if (deployment.step && deployment.step !== last) { console.log(deployment.step); last = deployment.step; }
+    if (deployment.status === 'ready') return console.log(`Live: ${deployment.url}`);
+    if (deployment.status === 'failed') die(deployment.error || 'Deploy failed.');
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+};
+
+// Resolve a human-typed app name to its id. Names are what people know; ids
+// are UUIDs nobody types. Ambiguity is reported rather than guessed at.
+const resolveApp = async (name) => {
+  if (!name) die('Missing app name. Try `javer ls` to see your apps.');
+  const { apps } = await api.get('/apps/');
+  const exact = apps.filter((c) => c.name === name);
+  if (exact.length === 1) return exact[0];
+  if (exact.length > 1) die(`"${name}" matches ${exact.length} apps — this shouldn't happen; use the dashboard.`);
+  const near = apps.filter((c) => c.name.includes(name)).map((c) => c.name);
+  die(near.length
+    ? `No app called "${name}". Did you mean: ${near.join(', ')}?`
+    : `No app called "${name}". Run \`javer ls\` to see your apps.`);
+};
+
+// VMs need the same name-to-id courtesy apps get. Kept separate rather than
+// generalised: the two endpoints return different shapes, and a shared helper
+// that guesses which one it is would be worse than two short ones.
+const resolveVm = async (name) => {
+  if (!name) die('Missing VM name. Try `javer vms` to see them.');
+  const res = await api.get('/vms/');
+  const vms = res.vms || res.machines || [];
+  const exact = vms.filter((v) => v.name === name);
+  if (exact.length === 1) return exact[0];
+  const near = vms.filter((v) => v.name.includes(name)).map((v) => v.name);
+  die(near.length
+    ? `No VM called "${name}". Did you mean: ${near.join(', ')}?`
+    : `No VM called "${name}". Run \`javer vms\` to see them.`);
+};
+
+const pad = (s, n) => String(s ?? '').padEnd(n);
+
+// ── commands ───────────────────────────────────────────────────────────
+const commands = {
+  async login(_pos, flags) {
+    let key = flags.key || process.env.JAVER_API_KEY;
+    if (!key) {
+      // Read from stdin so the key never lands in shell history the way a
+      // --key argument would.
+      process.stdout.write('Paste your API key (panel.javer.pro/api-keys): ');
+      key = await new Promise((resolve) => {
+        let buf = '';
+        process.stdin.setEncoding('utf-8');
+        // Resolve on the first NEWLINE, not on 'end'. In a terminal 'end' only
+        // fires on Ctrl-D, so pressing Enter after pasting did nothing at all —
+        // the prompt just sat there forever and the only way out was Ctrl-C.
+        // 'end' is still handled underneath so a piped key still works:
+        //   echo "$KEY" | javer login
+        const done = (value) => {
+          process.stdin.removeListener('data', onData);
+          process.stdin.pause();
+          resolve(value.trim());
+        };
+        const onData = (d) => {
+          buf += d;
+          const nl = buf.indexOf('\n');
+          if (nl !== -1) done(buf.slice(0, nl));
+        };
+        process.stdin.on('data', onData);
+        process.stdin.once('end', () => done(buf));
+      });
+      process.stdout.write('\n');
+    }
+    key = String(key).trim();
+    if (!key.startsWith('jvr_live_')) die('That does not look like a Javer API key (they start with jvr_live_).');
+
+    const url = flags.url || config.apiUrl();
+    // Validate before saving: writing a bad key and only discovering it on
+    // the next command is a worse first experience than failing here.
+    config.write({ apiUrl: url, key });
+    try {
+      const usage = await api.get('/account/usage');
+      console.log(`Logged in to ${url}`);
+      console.log(`Plan allows ${usage.budget.ramMB} MB RAM, ${usage.budget.cpu} CPU, ${usage.budget.maxItems} apps.`);
+      console.log(`Key saved to ${config.FILE} (readable only by you).`);
+    } catch (err) {
+      config.clear();
+      die(`Key rejected: ${err.message}`);
+    }
+  },
+
+  async logout() {
+    const had = config.clear();
+    // Say what actually happened. The key stays valid server-side — only the
+    // local copy is gone — and pretending otherwise is the same lie the
+    // GitHub disconnect used to tell.
+    console.log(had ? 'Local key removed.' : 'No saved key to remove.');
+    console.log('The key itself is still valid. Revoke it at panel.javer.pro/api-keys.');
+  },
+
+  async whoami() {
+    const u = await api.get('/account/usage');
+    console.log(`Server : ${config.apiUrl()}`);
+    console.log(`Using  : ${u.used.usedRamMB} MB RAM, ${u.used.usedCpu} CPU, ${u.used.usedItems} apps`);
+    console.log(`Limit  : ${u.budget.ramMB} MB RAM, ${u.budget.cpu} CPU, ${u.budget.maxItems} apps`);
+    console.log(`Left   : ${u.remaining.ramMB} MB RAM, ${u.remaining.cpu} CPU, ${u.remaining.items} apps`);
+  },
+
+  async ls() {
+    const { apps } = await api.get('/apps/');
+    if (!apps.length) return console.log('No apps yet. Deploy one with `javer deploy --repo owner/name`.');
+    console.log(`${pad('NAME', 24)}${pad('STATUS', 10)}${pad('RAM', 8)}URL`);
+    for (const c of apps) {
+      console.log(`${pad(c.name, 24)}${pad(c.status, 10)}${pad(c.ram_mb + 'MB', 8)}${c.hostname ? 'https://' + c.hostname : '-'}`);
+    }
+  },
+
+  async status(pos) {
+    const c = await resolveApp(pos[0]);
+    const full = await api.get(`/apps/${c.id}`);
+    const d = full.app || full;
+    console.log(`Name   : ${d.name}`);
+    console.log(`Status : ${d.status}`);
+    console.log(`Image  : ${d.image}`);
+    console.log(`Size   : ${d.ram_mb} MB RAM, ${d.cpu} CPU`);
+    console.log(`Host   : ${d.docker_host}`);
+    if (c.hostname) console.log(`URL    : https://${c.hostname}`);
+  },
+
+  async logs(pos, flags) {
+    const c = await resolveApp(pos[0]);
+    const fetchLogs = async () => (await api.get(`/apps/${c.id}/logs`)).logs || '';
+
+    if (!flags.f && !flags.follow) {
+      process.stdout.write(await fetchLogs() || '(no output)\n');
+      return;
+    }
+
+    // Honest about what this is: the endpoint returns the last 300 lines as
+    // JSON, there is no stream to attach to, so this polls and prints what is
+    // new. Calling it "streaming" would be a lie the first time somebody
+    // noticed the two-second granularity.
+    console.log(`Polling ${c.name} every 2s — Ctrl-C to stop.\n`);
+    let lastLine = null;
+    for (;;) {
+      let lines;
+      try {
+        lines = (await fetchLogs()).split('\n');
+      } catch (err) {
+        // A blip should not end the session — say so and keep watching.
+        console.error(`  (${err.message} — retrying)`);
+        await new Promise((r) => setTimeout(r, 2000));
+        continue;
+      }
+      if (lastLine === null) {
+        process.stdout.write(lines.join('\n'));
+      } else {
+        // Find where we left off. Lines carry timestamps so they are
+        // effectively unique; if the line has scrolled out of the 300-line
+        // window it is gone, and printing the whole window beats printing
+        // nothing and looking frozen.
+        const at = lines.lastIndexOf(lastLine);
+        const fresh = at === -1 ? lines : lines.slice(at + 1);
+        if (fresh.length && fresh.some((l) => l.trim())) process.stdout.write(fresh.join('\n'));
+      }
+      lastLine = lines.filter((l) => l.trim()).pop() ?? lastLine;
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  },
+
+  async env(pos, flags) {
+    const c = await resolveApp(pos[0]);
+    const { env } = await api.get(`/apps/${c.id}/env`);
+    const keys = Object.keys(env);
+    if (!keys.length) return console.log('(no environment variables set)');
+    // Masked unless asked. Environment variables are where API keys and
+    // database passwords live, and this command gets run in shared terminals,
+    // screen shares and CI logs where the output outlives the moment. Printing
+    // them by default makes leaking one the path of least resistance.
+    for (const k of keys) {
+      const v = String(env[k]);
+      console.log(`${k}=${flags.show ? v : (v.length > 6 ? v.slice(0, 3) + '\u2026' + v.slice(-2) : '\u2026')}`);
+    }
+    if (!flags.show) console.log('\n(values hidden \u2014 pass --show to print them in full)');
+  },
+
+  async start(pos) { await lifecycle(pos[0], 'start'); },
+  async stop(pos) { await lifecycle(pos[0], 'stop'); },
+  async restart(pos) { await lifecycle(pos[0], 'restart'); },
+
+  async deploy(_pos, flags) {
+    const repo = flags.repo;
+
+    // No --repo means "deploy the folder I am standing in". Previously the
+    // only way to ship code was a connected GitHub repo, so there was no path
+    // at all from a working directory to a running app without the panel.
+    if (!repo) {
+      const cwd = process.cwd();
+      const name = flags.name || require('path').basename(cwd).toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-').replace(/^-+|-+$/g, '').slice(0, 30);
+      if (!name) die('Could not make an app name from this folder — pass --name.');
+
+      process.stdout.write(`Packing ${cwd}… `);
+      let archive;
+      try { archive = zipDir(cwd); } catch (err) { console.log(''); die(err.message); }
+      const kb = Math.round(archive.buffer.length / 1024);
+      console.log(`${archive.fileCount} files, ${kb} KB`);
+
+      // The server caps uploads at 2 MB. Fail here with something actionable
+      // rather than letting it come back as a bare HTTP 413.
+      if (archive.buffer.length > 2 * 1024 * 1024) {
+        die(`That is ${kb} KB and the limit is 2048 KB. Remove large files, or deploy from GitHub with --repo owner/name.`);
+      }
+
+      const fields = { name, async: 'true' };
+      if (flags.ram) fields.ramMB = Number(flags.ram);
+      if (flags.cpu) fields.cpu = Number(flags.cpu);
+      const startedUpload = await api.upload('/apps/deployments', 'app.zip', archive.buffer, fields);
+      return await followDeploy(startedUpload);
+    }
+    if (typeof repo !== 'string') die('Usage: javer deploy --repo owner/name  (or no --repo to deploy this folder)');
+    // async:true asks the server to answer with the deployment and build it
+    // detached, so this can print progress. Without it the request blocked
+    // until the build finished and the id this polls for never came back —
+    // which is why `javer deploy` had been printing raw JSON.
+    const body = { source: 'github', repoFullName: repo, async: true };
+    if (flags.name) body.name = flags.name;
+    if (flags.branch) body.branch = flags.branch;
+    if (flags.ram) body.ramMB = Number(flags.ram);
+    if (flags.cpu) body.cpu = Number(flags.cpu);
+
+    return await followDeploy(await api.post('/apps/deployments', body));
+  },
+
+
+  // A live view of apps and VMs together. Its own module — a full-screen
+  // interface has nothing in common with a command that prints and exits.
+  async ui() { await ui.run(); },
+
+  async vms() {
+    const res = await api.get('/vms/');
+    const vms = res.vms || res.machines || [];
+    if (!vms.length) return console.log('No VMs yet. Create one at panel.javer.pro/vms.');
+    console.log(`${pad('NAME', 24)}${pad('STATUS', 12)}${pad('RAM', 9)}${pad('CPU', 5)}${pad('DISK', 8)}ADDRESS`);
+    for (const v of vms) {
+      console.log(`${pad(v.name, 24)}${pad(v.state || v.status, 12)}${pad((v.ram_mb || '?') + 'MB', 9)}` +
+        `${pad(v.cpu ?? '?', 5)}${pad((v.disk_gb || '?') + 'GB', 8)}${v.ip || '-'}`);
+    }
+  },
+
+  // `javer vm <name>` shows one; `javer vm start|stop|restart <name>` acts.
+  // Reads as English either way, and there is no separate verb to remember.
+  async vm(pos) {
+    const VERBS = ['start', 'stop', 'restart'];
+    if (VERBS.includes(pos[0])) {
+      const v = await resolveVm(pos[1]);
+      await api.post(`/vms/${v.id}/${pos[0]}`, {});
+      return console.log(`${pos[0]} sent to ${v.name}.`);
+    }
+    const v = await resolveVm(pos[0]);
+    const full = await api.get(`/vms/${v.id}`).catch(() => null);
+    const d = (full && (full.vm || full)) || v;
+    console.log(`Name   : ${d.name}`);
+    console.log(`Status : ${d.state || d.status}`);
+    console.log(`Size   : ${d.ram_mb} MB RAM, ${d.cpu} CPU, ${d.disk_gb} GB disk`);
+    console.log(`OS     : ${d.os_image || d.image || '-'}`);
+    console.log(`Address: ${d.ip || '-'}`);
+    if ((d.state || d.status) === 'running') {
+      const s = await api.get(`/vms/${d.id}/stats`).catch(() => null);
+      if (s) console.log(`Live   : ${Math.round((s.memUsage || 0) / 1048576)} MB of ${Math.round((s.memLimit || 0) / 1048576)} MB, CPU ${s.cpuPercent}%`);
+    }
+    console.log('\nSSH from your own machine is not available — open the terminal in the panel.');
+  },
+
+  async db(pos, flags) {
+    if (pos[0] === 'create') {
+      const engine = (flags.engine || 'postgres').toLowerCase();
+      const name = flags.name || pos[1];
+      if (!name) die('Usage: javer db create <name> [--engine postgres|mysql]');
+      const res = await api.post('/apps/database', { name, engine });
+      const c = res.credentials || res;
+      console.log('Database created. These credentials are shown ONCE:\n');
+      for (const k of ['host', 'port', 'user', 'password', 'database', 'url']) {
+        if (c[k]) console.log(`  ${pad(k, 10)}${c[k]}`);
+      }
+      console.log('\nIt is reachable only from inside Javer — not from this machine.');
+      return;
+    }
+    const { apps } = await api.get('/apps/');
+    const dbs = apps.filter((a) => a.kind === 'database');
+    if (!dbs.length) return console.log('No databases. Create one with `javer db create <name>`.');
+    console.log(`${pad('NAME', 24)}${pad('STATUS', 10)}ENGINE`);
+    for (const d of dbs) console.log(`${pad(d.name, 24)}${pad(d.status, 10)}${d.image || '-'}`);
+  },
+
+  async domains(pos) {
+    const c = await resolveApp(pos[0]);
+    const res = await api.get(`/apps/${c.id}/domains`);
+    const list = res.domains || [];
+    if (!list.length) return console.log(`No custom domains on ${c.name}. Add one in the panel.`);
+    for (const d of list) {
+      console.log(`${pad(d.hostname, 34)}${d.verified ? 'ownership verified' : 'NOT verified'}`);
+    }
+    console.log('\nNote: your domain\'s DNS must be on Cloudflare for routing to work.');
+  },
+
+  // Deleting takes the app, its volumes, its DNS record and its data, and
+  // there is no undo anywhere in the product. So it asks you to type the name
+  // — the same bar the panel sets — rather than accepting a y/n, which people
+  // answer reflexively. --yes exists for scripts that genuinely mean it.
+  async delete(pos, flags) {
+    const c = await resolveApp(pos[0]);
+    if (!flags.yes && !flags.y) {
+      if (!process.stdin.isTTY) {
+        die(`Refusing to delete ${c.name} without a terminal to confirm in. Pass --yes if you mean it.`);
+      }
+      console.log(`This permanently deletes ${c.name}, its data and its URL. There is no undo.`);
+      process.stdout.write(`Type the name to confirm: `);
+      const typed = await new Promise((resolve) => {
+        let buf = '';
+        process.stdin.setEncoding('utf-8');
+        const done = (v) => { process.stdin.removeListener('data', onData); process.stdin.pause(); resolve(v.trim()); };
+        const onData = (d) => { buf += d; const nl = buf.indexOf('\n'); if (nl !== -1) done(buf.slice(0, nl)); };
+        process.stdin.on('data', onData);
+        process.stdin.once('end', () => done(buf));
+      });
+      process.stdout.write('\n');
+      if (typed !== c.name) return console.log('Names did not match — nothing deleted.');
+    }
+    await api.del(`/apps/${c.id}`);
+    console.log(`${c.name} deleted.`);
+  },
+
+  async version() { console.log(`javer-cli ${version}`); },
+  async help() { usage(); }
+};
+
+const lifecycle = async (name, action) => {
+  const c = await resolveApp(name);
+  await api.post(`/apps/${c.id}/${action}`);
+  console.log(`${c.name}: ${action} requested.`);
+};
+
+const usage = () => console.log(`javer ${version} — Javer Webhost from the command line
+
+  javer ui                                  live dashboard: apps + VMs, one screen
+
+  javer login [--key <key>] [--url <url>]   save an API key (panel.javer.pro/api-keys)
+  javer logout                              forget the saved key locally
+  javer whoami                              plan limits and what is left
+
+  javer ls                                  list your apps
+  javer status <app>                        details for one app
+  javer logs <app> [-f]                     recent output; -f keeps watching
+  javer env <app> [--show]                  environment variables (hidden by default)
+  javer domains <app>                       custom domains and whether they verified
+
+  javer start|stop|restart <app>            lifecycle
+  javer delete <app> [--yes]                remove an app, its data and its URL
+
+  javer vms                                 list your virtual machines
+  javer vm <name>                           details for one VM
+  javer vm start|stop|restart <name>        VM lifecycle
+
+  javer db                                  list databases
+  javer db create <name> [--engine mysql]   new Postgres or MySQL
+
+  javer deploy                              deploy the folder you are in
+  javer deploy --repo owner/name            deploy from a connected GitHub repo
+         [--name app] [--branch main] [--ram 256] [--cpu 0.25]
+
+  javer bird                                the mascot, in both renderings\n  javer version | help
+
+Environment:
+  JAVER_API_KEY   use this key instead of the saved one (for CI)
+  JAVER_API_URL   point at a different server (for local development)`);
+
+// ── entry ──────────────────────────────────────────────────────────────
+(async () => {
+  const [, , cmd, ...rest] = process.argv;
+  if (!cmd || cmd === '--help' || cmd === '-h') return usage();
+  if (cmd === '--version' || cmd === '-v') return commands.version();
+  const handler = commands[cmd];
+  if (!handler) { console.error(`Unknown command: ${cmd}\n`); usage(); process.exit(1); }
+
+  const { positional, flags } = parseArgs(rest);
+  try {
+    await handler(positional, flags);
+  } catch (err) {
+    // Only rewrite the message when a key was actually sent and refused.
+    // Without this check the "not logged in" case — which api.js raises as a
+    // synthetic 401 before any request goes out — was reported as "key
+    // rejected or expired", sending people to re-check a key they never had.
+    if (err instanceof api.ApiError && err.status === 401 && config.apiKey()) {
+      die('Key rejected or expired. Run `javer login` again.');
+    }
+    die(err.message);
+  }
+})();