@astris-labs/cli 0.1.0 → 0.1.2

package/README.md

@@ -12,7 +12,7 @@ From this repository, run `pnpm install` at the root. Then run the client with `
 
 ## API key
 
-`astris login` reads the key from stdin and saves it only after the API accepts it. `astris logout` deletes that one file.
+`astris login` asks for the key. On a terminal the question is `Paste your Astris API key:` and the typed key is not shown. With a pipe, `astris login` reads the key from stdin. The key is saved only after the API accepts it. `astris logout` deletes that one file.
 
 The file name is `key`, in a directory named `astris`.
 
@@ -30,7 +30,7 @@ Requests go to `https://api.astris.run`.
 
 ## Commands
 
-v0 commands are `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `list`, `logs`, `usage`, `plans`, `whoami`, `login`, and `logout`.
+v0 commands are `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `list`, `logs`, `usage`, `plans`, `whoami`, `login`, `logout`, `app`, `preflight`, and `export`.
 
 `--json` writes one JSON object to stdout. Without `--json`, success is text on stdout and an error is a sentence on stderr.
 
@@ -38,15 +38,21 @@ v0 commands are `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `da
 
 `--app <id>` redeploys that application. The value is the application id.
 
-To create a project and an application, then queue a deploy, pass these flags. The names are kebab-case.
+To create a project and an application, then queue a deploy, pass these flags. A private repository over SSH is the exception below. The names are kebab-case.
 
 - `--project`
 - `--name`
 - `--git-url`
 - `--branch`
 
+`--git-url` is a public http or https URL, or an SSH URL for a private repository in the form `ssh://git@host/owner/repo.git`. In an `ssh://` URL the user name `git` is the only user name allowed; an http or https URL takes none. Any other user name, or any password, is refused with `The Git URL must not include a user name or password.`
+
+When the API answers the create with a deploy key (an SSH URL), the CLI makes the project and the application and queues no deploy. It prints the project id, the application id, the name, the slug, the deploy key type, the public key, the fingerprint, and then the next step: `Add this public key to the repository as a read-only deploy key, then deploy again with this app_id. On GitHub the key goes in the repository Settings under Deploy keys, and write access stays off.`
+
 Optional flags are `--build-path`, `--dockerfile`, `--port`, `--build`, `--publish-directory`, `--spa`, `--kind`, `--command`, and `--schedule`.
 
+`--app <id> --hook` prints the push-to-deploy hook URL of that application, one line. The URL is a credential: keep it private. `--hook` needs `--app`; without it the sentence is `Send --app set to the application id.` `--hook` follows the same `--app` rules as a redeploy, so the flags that rule refuses are refused with it.
+
 `--build nixpacks` builds with Nixpacks. `--build dockerfile` builds from the Dockerfile named by `--dockerfile`; without `--build`, a `--dockerfile` value alone means a Dockerfile build. `--build static` serves static files; with it, `--publish-directory <dir>` names the directory to publish, relative to the build, and `--spa` serves it as a single-page application. `--spa` takes no value, and `--spa=false` is refused.
 
 `--kind web` is the default kind. `--kind worker` runs `--command` as the container's process. `--kind cron` runs `--command` on `--schedule`, five space-separated fields. A worker or a cron app cannot use `--build static`. `--app` with any of `--build`, `--publish-directory`, `--spa`, `--kind`, `--command`, or `--schedule` is refused and makes no request; the create flags `--project`, `--name`, `--git-url`, `--branch`, `--port`, `--dockerfile`, and `--build-path` are still ignored with `--app`.
@@ -59,7 +65,7 @@ Optional flags are `--build-path`, `--dockerfile`, `--port`, `--build`, `--publi
 
 `astris env --app <id>` reads one JSON object from stdin and replaces the whole variable set.
 
-`astris env --app <id> --names` prints the names of the application's variables, one per line, and never a value. `--json` prints `{application_id, names}`. It reads no stdin. The runner still waits for stdin to close when stdin is not a terminal, so close it when nothing is piped in, for example with `< /dev/null`.
+`astris env --app <id> --names` prints the names of the application's variables, one per line, and never a value. `--json` prints `{application_id, names}`. It reads no stdin and does not wait for stdin to close.
 
 ### domains
 
@@ -121,16 +127,31 @@ When storage is not configured, all four commands print `Storage is not availabl
 
 ### login
 
-`astris login` reads the key from stdin. It does not take the key as an argument. When the API accepts the key, it writes `Logged in.`
+`astris login` takes no key as an argument. On a terminal it asks `Paste your Astris API key:` and does not show what is typed. With a pipe it reads the key from stdin. When the API accepts the key, it writes `Logged in.`
 
 ### logout
 
 `astris logout` deletes the saved key file and writes `Logged out.` When there is no file, it writes `There was nothing to remove.`
 
+### app
+
+`astris app remove --app <id> --confirm <name>` calls `GET /v1/apps/<id>` and then `DELETE /v1/apps/<id>`. `--confirm` must equal the application name exactly; without `--confirm` the sentence is `Send --confirm set to the application name.` A different name is refused with `The name does not match the application.` and nothing is deleted. Human output is `App removed.` `--json` prints one JSON object `{"app_id":"<id>","removed":true}`.
+
+### preflight
+
+`astris preflight [dir]` calls `POST /v1/preflight` with the files it finds under `dir` (the current directory when `dir` is omitted) and prints the verdict and one line per check with its reason. It sends no file or folder whose name starts with a dot (so no .env file and nothing under .git), nothing under node_modules, dist, build, out or coverage, no binary file, and nothing outside dir. Files the request cannot hold are left out and counted on stderr. `--json` prints one JSON object of the response body.
+
+### export
+
+`astris export --email <address>` calls `POST /v1/account-export` and prints the answer. If the address is on an Astris account, check its inbox for the download link. The link works for one hour. Nothing is written to disk. `--json` prints one JSON object of the response body.
+
+
 ## Exit codes
 
 Exit code 0 means the command succeeded. Any error exits with a non-zero code. With `--json`, an error that happens after the key check is one object `{"error":"<sentence>"}` on stdout. A missing key and an unknown command write their sentence to stderr.
 
+`astris preflight` exits 0 when the verdict is `pass` or `fixable`, 1 when it is `refuse`, and 2 when it could not run. `astris export` exits 0 when the server accepts the request and 2 when it could not run.
+
 ## Not in this version
 
 `rollback` is not in v0. The route it needs waits for T-042 item 3.
@@ -139,9 +160,9 @@ Exit code 0 means the command succeeded. Any error exits with a non-zero code. W
 
 Some arguments are refused on this machine, before any request.
 
-The command name is checked first. `deploy`, `status`, `env`, `domains`, `restart`, `logs`, `rollback`, `diagnose`, `database`, `storage`, `list`, `usage`, `plans`, `whoami`, `login`, and `logout` are known. Any other name writes `Unknown command.` and makes no request.
+The command name is checked first. The words `help`, `--help`, and `-h` print the usage and the command names, exit 0, and make no request. `deploy`, `status`, `env`, `domains`, `restart`, `logs`, `rollback`, `diagnose`, `database`, `storage`, `list`, `usage`, `plans`, `whoami`, `login`, `logout`, `app`, `preflight`, and `export` are known. Any other name writes `Unknown command.` and makes no request.
 
-Login reads the key from stdin. Logout deletes that one file. Every other known command uses this sentence: When `ASTRIS_API_KEY` is set to a non-empty value, that value is the key, and the saved file is used only when the variable is missing or empty. A missing or empty variable and a missing or empty file write `ASTRIS_API_KEY is not set` to stderr and make no request. That is also true when `--json` is set.
+Login asks for the key on a terminal and reads it from stdin otherwise. Logout deletes that one file. Every other known command uses this sentence: When `ASTRIS_API_KEY` is set to a non-empty value, that value is the key, and the saved file is used only when the variable is missing or empty. A missing or empty variable and a missing or empty file write `ASTRIS_API_KEY is not set` to stderr and make no request. That is also true when `--json` is set.
 
 `login` and `logout` take no arguments. An argument is refused, and `logout` does not delete the file.
 
@@ -153,9 +174,9 @@ After the key, `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `dat
 
 `domains` binds with no word, or verifies with the one word `verify`. `--hostname` with `--slug` is refused. An empty `--hostname`, or one containing a space, is refused before any request. Other hostname rules are left to the API. `verify` requires `--app` set to an application id and `--id` set to a domain id; a missing or non-UUID `--id`, and a word other than `verify`, make no request.
 
-`--app` is refused unless the value, after trim, is an id of eight, four, four, four, and twelve hexadecimal digits, with hyphens, in either case. The sentence is `Send --app set to the application id.` `status`, `env`, `domains`, and `restart` require that id. `deploy` requires it when `--app` is present, and then refuses `--build`, `--publish-directory`, `--spa`, `--kind`, `--command`, and `--schedule`; the other create flags are ignored.
+`--app` is refused unless the value, after trim, is an id of eight, four, four, four, and twelve hexadecimal digits, with hyphens, in either case. The sentence is `Send --app set to the application id.` `status`, `env`, `domains`, and `restart` require that id. `deploy` requires it when `--app` is present or when `--hook` is sent (`--hook` without `--app` is refused with `Send --app set to the application id.`), and then refuses `--build`, `--publish-directory`, `--spa`, `--kind`, `--command`, and `--schedule`; the other create flags are ignored.
 
-`deploy` without `--app` refuses the call unless `--project`, `--name`, `--git-url`, and `--branch` each have a non-empty value after trim. The sentence names those four flags. On that same path, a `--git-url` whose user or password is set is refused. The sentence says the Git URL must be a public http or https URL with no user or password. A `--port` on that path is refused unless it is a whole number from 1 to 65535 with no leading zero. Other Git URL rules are left to the API. On that path, `--build` is exactly `nixpacks`, `dockerfile`, or `static`. `nixpacks` refuses `--dockerfile`, `--publish-directory`, and `--spa`. `dockerfile` needs `--dockerfile`. `static` takes an optional `--publish-directory` and an optional `--spa`, and refuses `--dockerfile`. `--publish-directory` or `--spa` without `--build` is refused. `--kind` is exactly `web`, `worker`, or `cron`. A web app refuses `--command` and `--schedule`. A worker needs `--command` and refuses `--schedule`. A cron needs `--command` and a `--schedule` of five space-separated fields of digits, `*`, `,`, `-`, or `/`, at most 100 characters, each field non-empty. A command is 1 to 512 characters, with no line break and no NUL character. A worker or cron app with `--build static` is refused. Any refusal on this path makes no request.
+`deploy` without `--app` refuses the call unless `--project`, `--name`, `--git-url`, and `--branch` each have a non-empty value after trim. The sentence names those four flags. On that same path, a `--git-url` whose password is set, or whose user name is set and is not the `git` of an `ssh://` URL, is refused. The sentence is `The Git URL must not include a user name or password.` A `--port` on that path is refused unless it is a whole number from 1 to 65535 with no leading zero. Other Git URL rules are left to the API. On that path, `--build` is exactly `nixpacks`, `dockerfile`, or `static`. `nixpacks` refuses `--dockerfile`, `--publish-directory`, and `--spa`. `dockerfile` needs `--dockerfile`. `static` takes an optional `--publish-directory` and an optional `--spa`, and refuses `--dockerfile`. `--publish-directory` or `--spa` without `--build` is refused. `--kind` is exactly `web`, `worker`, or `cron`. A web app refuses `--command` and `--schedule`. A worker needs `--command` and refuses `--schedule`. A cron needs `--command` and a `--schedule` of five space-separated fields of digits, `*`, `,`, `-`, or `/`, at most 100 characters, each field non-empty. A command is 1 to 512 characters, with no line break and no NUL character. A worker or cron app with `--build static` is refused. Any refusal on this path makes no request.
 
 `env` refuses stdin that is not one JSON object. An array, a bare value, and text that is not JSON are refused, before any request. `env --names` sends no replace: it prints the names of the application's variables, one per line, and never a value, and it reads no stdin.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astris-labs/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The Astris CLI, a command-line client of the Astris API.",
   "repository": {
     "type": "git",

package/src/commands.mjs

@@ -1,3 +1,5 @@
+import { lstatSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
 import { parseArgs } from "node:util";
 
 import { astrisFetch, DEFAULT_BASE_URL, redact } from "./client.mjs";
@@ -41,6 +43,13 @@ const SENTENCE = {
   loggedIn: "Logged in.",
   loggedOut: "Logged out.",
   nothingToRemove: "There was nothing to remove.",
+  appRemoved: "App removed.",
+  confirmRequired: "Send --confirm set to the application name.",
+  nameMismatch: "The name does not match the application.",
+  unreadableDir: "That directory cannot be read.",
+  exportEmail: "Send --email set to the account email address.",
+  exportAccepted:
+    "Accepted. If that address is on an Astris account, check its inbox for the download link. The link works for one hour.",
 };
 
 const HTTP_SENTENCE = new Map([
@@ -55,6 +64,11 @@ function sentenceFor(status) {
   return HTTP_SENTENCE.get(status) ?? SENTENCE.failed;
 }
 
+function errorMessage(status, body) {
+  if (isRecord(body) && typeof body.message === "string") return body.message;
+  return sentenceFor(status);
+}
+
 function upgradeMessage(status, body) {
   if (status !== 403 || !isRecord(body) || body.error !== "upgrade_required" || typeof body.message !== "string") {
     return null;
@@ -94,12 +108,12 @@ function withCreated(sentence, created) {
   return text;
 }
 
-function fail(io, key, json, sentence, created) {
+function fail(io, key, json, sentence, created, exitCode = 1) {
   const text = withCreated(sentence, created);
   const safe = redact(text, key);
   if (json) writeStdout(io, key, `${JSON.stringify({ error: safe })}\n`);
   else writeStderr(io, key, `${safe}\n`);
-  return { exitCode: 1 };
+  return { exitCode };
 }
 
 function succeed(io, key, json, payload, human) {
@@ -108,13 +122,13 @@ function succeed(io, key, json, payload, human) {
   return { exitCode: 0 };
 }
 
-function loadKey(io) {
+function loadKey(io, exitCode = 1) {
   try {
     return { key: readApiKey(io.env) };
   } catch (error) {
     if (error instanceof NoApiKeyError) {
       io.stderr.write(`${SENTENCE.missingKey}\n`);
-      return { exit: { exitCode: 1 } };
+      return { exit: { exitCode } };
     }
     throw error;
   }
@@ -1497,7 +1511,15 @@ function stdinKey(io) {
 
 export async function login(args, io) {
   if (Array.isArray(args) && args.length > 0) return fail(io, "", false, SENTENCE.refused);
-  const key = stdinKey(io);
+  let key = stdinKey(io);
+  if (key === "" && typeof io.readSecret === "function") {
+    try {
+      key = (await io.readSecret()).trim();
+    } catch {
+      // Ctrl+C at the prompt: leave with no output and nothing saved.
+      return { exitCode: 1 };
+    }
+  }
   if (key === "") return fail(io, "", false, SENTENCE.emptyKey);
   const result = await call(io, key, { path: "/v1/me", method: "GET" });
   if (result.network) return fail(io, key, false, SENTENCE.platform);
@@ -1513,3 +1535,294 @@ export async function logout(args, io) {
   io.stdout.write(`${removed ? SENTENCE.loggedOut : SENTENCE.nothingToRemove}\n`);
   return { exitCode: 0 };
 }
+
+const APP_REMOVE_OPTIONS = {
+  json: { type: "boolean" },
+  app: { type: "string" },
+  confirm: { type: "string" },
+};
+
+function appPositionals(args) {
+  try {
+    return parseArgs({
+      args: Array.isArray(args) ? args : [],
+      strict: false,
+      allowPositionals: true,
+      options: APP_REMOVE_OPTIONS,
+    }).positionals;
+  } catch {
+    return null;
+  }
+}
+
+export async function app(args, io) {
+  const loaded = loadKey(io);
+  if (loaded.exit) return loaded.exit;
+  const words = appPositionals(args);
+  if (words === null || words.length !== 1) return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+  if (words[0] === "remove") return appRemove(args, io, loaded.key);
+  return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+}
+
+async function appRemove(args, io, key) {
+  const parsed = parseStrict(args, APP_REMOVE_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== "remove") {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const appId = appUuid(parsed.values.app);
+  if (appId === null) return fail(io, key, json, SENTENCE.app);
+  const confirm = typeof parsed.values.confirm === "string" ? parsed.values.confirm : "";
+  if (confirm === "") return fail(io, key, json, SENTENCE.confirmRequired);
+
+  const got = await call(io, key, { path: `/v1/apps/${encodeURIComponent(appId)}`, method: "GET" });
+  if (got.network) return fail(io, key, json, SENTENCE.platform);
+  if (got.status !== 200) return fail(io, key, json, sentenceFor(got.status));
+  if (!isRecord(got.body)) return fail(io, key, json, SENTENCE.failed);
+  const application = isRecord(got.body.application) ? got.body.application : null;
+  if (application === null) return fail(io, key, json, SENTENCE.failed);
+  const name = typeof application.name === "string" ? application.name : null;
+  if (name === null) return fail(io, key, json, SENTENCE.failed);
+
+  if (name !== confirm) {
+    io.stderr.write(`${SENTENCE.nameMismatch}\n`);
+    return { exitCode: 1 };
+  }
+
+  const deleted = await call(io, key, { path: `/v1/apps/${encodeURIComponent(appId)}`, method: "DELETE" });
+  if (deleted.network) return fail(io, key, json, SENTENCE.platform);
+  if (deleted.status !== 200) return fail(io, key, json, sentenceFor(deleted.status));
+  return succeed(io, key, json, { app_id: appId, removed: true }, `${SENTENCE.appRemoved}\n`);
+}
+
+export const PREFLIGHT_MAX_FILES = 64;                  // the server's, src/app/v1/preflight/route.ts:24
+export const PREFLIGHT_MAX_FILE_BYTES = 32 * 1024;      // the server's, src/app/v1/preflight/route.ts:25
+export const PREFLIGHT_MAX_LOCKFILE_BYTES = 320 * 1024; // the server's, src/app/v1/preflight/route.ts:26
+export const PREFLIGHT_MAX_BODY_BYTES = 512 * 1024;     // the server's, src/app/v1/preflight/route.ts:27
+
+const ROOT_LOCKFILES = new Set([
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+]);
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+]);
+
+function validRelPath(p) {
+  if (p.length === 0 || p.length > 256) return false;
+  if (p.startsWith("/") || p.includes("\\") || /^[A-Za-z]:/.test(p)) return false;
+  return p.split("/").every((segment) => segment.length > 0 && segment !== "..");
+}
+
+export function preflightFiles(root) {
+  let rootStat;
+  try {
+    rootStat = lstatSync(root);
+  } catch {
+    return null;
+  }
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) return null;
+
+  const candidates = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return false;
+    }
+    for (const name of entries) {
+      if (name.startsWith(".")) continue;
+      const fullPath = path.join(dir, name);
+      let stat;
+      try {
+        stat = lstatSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isDirectory()) {
+        if (SKIP_DIRS.has(name)) continue;
+        const ok = walk(fullPath);
+        if (!ok) return false;
+      } else if (stat.isFile()) {
+        const rel = path.relative(root, fullPath).split(path.sep).join("/");
+        const depth = rel.split("/").length - 1;
+        candidates.push({ rel, fullPath, depth, stat });
+      }
+    }
+    return true;
+  }
+
+  if (!walk(root)) return null;
+
+  candidates.sort((a, b) => {
+    if (a.depth !== b.depth) return a.depth - b.depth;
+    return a.rel.localeCompare(b.rel);
+  });
+
+  const files = [];
+  let leftOut = 0;
+
+  for (const candidate of candidates) {
+    if (!validRelPath(candidate.rel)) {
+      leftOut++;
+      continue;
+    }
+
+    if (files.length >= PREFLIGHT_MAX_FILES) {
+      leftOut++;
+      continue;
+    }
+
+    const isRootLock = candidate.depth === 0 && ROOT_LOCKFILES.has(candidate.rel);
+    const maxBytes = isRootLock ? PREFLIGHT_MAX_LOCKFILE_BYTES : PREFLIGHT_MAX_FILE_BYTES;
+    if (candidate.stat.size > maxBytes) {
+      leftOut++;
+      continue;
+    }
+
+    let buf;
+    try {
+      buf = readFileSync(candidate.fullPath);
+    } catch {
+      leftOut++;
+      continue;
+    }
+
+    if (buf.includes(0x00)) {
+      leftOut++;
+      continue;
+    }
+
+    const text = buf.toString("utf8");
+    if (Buffer.byteLength(text, "utf8") > maxBytes) {
+      leftOut++;
+      continue;
+    }
+
+    const candidateFile = { path: candidate.rel, text };
+    const wouldBeBytes = Buffer.byteLength(
+      JSON.stringify({ files: [...files, candidateFile] }),
+      "utf8",
+    );
+    if (wouldBeBytes > PREFLIGHT_MAX_BODY_BYTES) {
+      leftOut++;
+      continue;
+    }
+
+    files.push(candidateFile);
+  }
+
+  return { files, leftOut };
+}
+
+const PREFLIGHT_OPTIONS = {
+  json: { type: "boolean" },
+};
+
+export async function preflight(args, io) {
+  const loaded = loadKey(io, 2);
+  if (loaded.exit) return loaded.exit;
+  const parsed = parseStrict(args, PREFLIGHT_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length > 1) {
+    return fail(io, loaded.key, wantsJson(args), SENTENCE.refused, undefined, 2);
+  }
+  const json = parsed.values.json === true;
+  const dir = parsed.positionals.length === 1 ? parsed.positionals[0] : ".";
+  const walked = preflightFiles(dir);
+  if (walked === null) {
+    return fail(io, loaded.key, json, SENTENCE.unreadableDir, undefined, 2);
+  }
+
+  const result = await call(io, loaded.key, {
+    path: "/v1/preflight",
+    method: "POST",
+    body: { files: walked.files },
+  });
+  if (result.network) return fail(io, loaded.key, json, SENTENCE.platform, undefined, 2);
+  if (result.status < 200 || result.status >= 300) {
+    return fail(io, loaded.key, json, errorMessage(result.status, result.body), undefined, 2);
+  }
+
+  if (
+    !isRecord(result.body) ||
+    typeof result.body.verdict !== "string" ||
+    !Array.isArray(result.body.checks) ||
+    (result.body.verdict !== "pass" && result.body.verdict !== "fixable" && result.body.verdict !== "refuse")
+  ) {
+    return fail(io, loaded.key, json, SENTENCE.failed, undefined, 2);
+  }
+
+  if (walked.leftOut > 0) {
+    const leftOutMsg =
+      walked.leftOut === 1
+        ? "Left out 1 file. The checks did not read it.\n"
+        : `Left out ${walked.leftOut} files. The checks did not read them.\n`;
+    io.stderr.write(leftOutMsg);
+  }
+
+  const exitCode = result.body.verdict === "refuse" ? 1 : 0;
+  if (json) {
+    writeStdout(io, loaded.key, `${JSON.stringify(result.body)}\n`);
+    return { exitCode };
+  }
+
+  let human = `Verdict: ${result.body.verdict}\n`;
+  for (const check of result.body.checks) {
+    if (
+      isRecord(check) &&
+      typeof check.name === "string" &&
+      typeof check.result === "string" &&
+      typeof check.reason === "string"
+    ) {
+      human += `${check.name}: ${check.result} - ${check.reason}\n`;
+    }
+  }
+  writeStdout(io, loaded.key, human);
+  return { exitCode };
+}
+
+const EXPORT_OPTIONS = {
+  json: { type: "boolean" },
+  email: { type: "string" },
+};
+
+export async function accountExport(args, io) {
+  const loaded = loadKey(io, 2);
+  if (loaded.exit) return loaded.exit;
+  const parsed = parseStrict(args, EXPORT_OPTIONS, false);
+  if (parsed === null) {
+    return fail(io, loaded.key, wantsJson(args), SENTENCE.refused, undefined, 2);
+  }
+  const json = parsed.values.json === true;
+  const email = typeof parsed.values.email === "string" ? parsed.values.email.trim() : "";
+  if (email === "") {
+    return fail(io, loaded.key, json, SENTENCE.exportEmail, undefined, 2);
+  }
+
+  const result = await call(io, loaded.key, {
+    path: "/v1/account-export",
+    method: "POST",
+    body: { email },
+  });
+  if (result.network) return fail(io, loaded.key, json, SENTENCE.platform, undefined, 2);
+  if (result.status < 200 || result.status >= 300) {
+    return fail(io, loaded.key, json, errorMessage(result.status, result.body), undefined, 2);
+  }
+
+  if (json) {
+    writeStdout(io, loaded.key, `${JSON.stringify(result.body ?? { status: "accepted" })}\n`);
+    return { exitCode: 0 };
+  }
+
+  writeStdout(io, loaded.key, `${SENTENCE.exportAccepted}\n`);
+  return { exitCode: 0 };
+}

package/src/main.mjs

@@ -1,28 +1,80 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_BASE_URL } from "./client.mjs";
-import { database, deploy, diagnose, domains, env, list, login, logout, logs, plans, restart, rollback, status, storage, usage, whoami } from "./commands.mjs";
+import { accountExport, app, database, deploy, diagnose, domains, env, list, login, logout, logs, plans, preflight, restart, rollback, status, storage, usage, whoami } from "./commands.mjs";
+
+const PROMPT = "Paste your Astris API key: ";
+
+// Hides what is typed: the interface writes only to a muted stream, the prompt
+// and its closing newline go to stderr. Resolves the typed line, resolves ""
+// when stdin ends (Ctrl+D), and rejects on Ctrl+C.
+function readSecret() {
+  return new Promise((resolve, reject) => {
+    process.stderr.write(PROMPT);
+    const muted = new Writable({
+      write(_chunk, _encoding, done) {
+        done();
+      },
+    });
+    const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+    let settled = false;
+    const finish = (settle, value) => {
+      if (settled) return;
+      settled = true;
+      rl.removeListener("line", onLine);
+      rl.removeListener("SIGINT", onSigint);
+      rl.removeListener("close", onClose);
+      rl.close();
+      process.stderr.write("\n");
+      settle(value);
+    };
+    const onLine = (line) => finish(resolve, line);
+    const onSigint = () => finish(reject, new Error("interrupted"));
+    const onClose = () => finish(resolve, "");
+    rl.on("line", onLine);
+    rl.on("SIGINT", onSigint);
+    rl.on("close", onClose);
+  });
+}
+
+// One table: the usage text and the dispatch both read it. A Map, so a word
+// such as "constructor" or "__proto__" is not found on Object.prototype.
+const handlers = new Map([
+  ["deploy", deploy],
+  ["status", status],
+  ["diagnose", diagnose],
+  ["database", database],
+  ["storage", storage],
+  ["env", env],
+  ["domains", domains],
+  ["restart", restart],
+  ["logs", logs],
+  ["list", list],
+  ["usage", usage],
+  ["plans", plans],
+  ["whoami", whoami],
+  ["rollback", rollback],
+  ["login", login],
+  ["logout", logout],
+  ["app", app],
+  ["preflight", preflight],
+  ["export", accountExport],
+]);
+
+export const COMMANDS = [...handlers.keys()];
 
 export async function main(argv, io) {
   const command = argv?.[2];
   const args = Array.isArray(argv) ? argv.slice(3) : [];
-  if (command === "deploy") return (await deploy(args, io)).exitCode;
-  if (command === "status") return (await status(args, io)).exitCode;
-  if (command === "diagnose") return (await diagnose(args, io)).exitCode;
-  if (command === "database") return (await database(args, io)).exitCode;
-  if (command === "storage") return (await storage(args, io)).exitCode;
-  if (command === "env") return (await env(args, io)).exitCode;
-  if (command === "domains") return (await domains(args, io)).exitCode;
-  if (command === "restart") return (await restart(args, io)).exitCode;
-  if (command === "logs") return (await logs(args, io)).exitCode;
-  if (command === "list") return (await list(args, io)).exitCode;
-  if (command === "usage") return (await usage(args, io)).exitCode;
-  if (command === "plans") return (await plans(args, io)).exitCode;
-  if (command === "whoami") return (await whoami(args, io)).exitCode;
-  if (command === "rollback") return rollback(args, io).exitCode;
-  if (command === "login") return (await login(args, io)).exitCode;
-  if (command === "logout") return (await logout(args, io)).exitCode;
+  if (command === "--help" || command === "-h" || command === "help") {
+    io.stdout.write(`Usage: astris <command> [flags]\n\nCommands:\n  ${COMMANDS.join("\n  ")}\n`);
+    return 0;
+  }
+  const handler = handlers.get(command);
+  if (handler) return (await handler(args, io)).exitCode;
   io.stderr.write("Unknown command.\n");
   return 1;
 }
@@ -37,14 +89,17 @@ async function readStdin() {
 }
 
 if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
-  const stdin = (process.argv[2] === "env" || process.argv[2] === "login") && !process.stdin.isTTY ? await readStdin() : "";
-  const code = await main(process.argv, {
+  const isEnvWithoutNames = process.argv[2] === "env" && !process.argv.slice(3).includes("--names");
+  const stdin = (isEnvWithoutNames || process.argv[2] === "login") && !process.stdin.isTTY ? await readStdin() : "";
+  const io = {
     env: process.env,
     fetchImpl: globalThis.fetch,
     baseUrl: DEFAULT_BASE_URL,
     stdin,
     stdout: process.stdout,
     stderr: process.stderr,
-  });
+  };
+  if (process.argv[2] === "login" && process.stdin.isTTY) io.readSecret = readSecret;
+  const code = await main(process.argv, io);
   process.exit(code);
 }