@astris-labs/cli 0.1.1 → 0.1.3

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`, `compose`, `list`, `logs`, `usage`, `plans`, `whoami`, `next`, `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.
 
@@ -65,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
 
@@ -93,6 +93,18 @@ Optional flags are `--build-path`, `--dockerfile`, `--port`, `--build`, `--publi
 
 `astris database delete --id <id> --yes` calls `DELETE /v1/databases/:id` and sends no body. Without `--yes` it makes no request and says the database and its data are removed and that `--yes` confirms. A repeated `--id` is refused and makes no request. Human output is `Database removed.` `--json` prints one JSON object `{"database_id":"<id>","removed":true}`.
 
+### compose
+
+`astris compose list` calls `GET /v1/compose`. Human output is one line per stack in the order the API returned: the id, the name, and the project name. An empty list prints nothing. `--json` prints one JSON object `{"compose":[...]}` of the stack rows.
+
+`astris compose deploy --id <id>` calls `POST /v1/compose/:id/deploy` and sends no body. Human output is the stack id, project id, name, git URL, branch, compose path, memory limit, created_at, and updated_at, one per line. `--json` prints one JSON object `{"compose":{...}}`.
+
+`astris compose start --id <id>` calls `POST /v1/compose/:id/start` and sends no body. Human output is the status the API returned, then the same stack fields as deploy, one per line. `--json` prints one JSON object `{"compose":{...},"status":"<status>"}`.
+
+`astris compose stop --id <id>` calls `POST /v1/compose/:id/stop` and sends no body. Human output matches start. `--json` prints one JSON object `{"compose":{...},"status":"<status>"}`.
+
+Without `--id`, or with an id that is not a stack id, deploy, start, and stop make no request and say `Send --id set to the compose stack id.`
+
 ### storage
 
 `astris storage create --name <name>` calls `POST /v1/buckets` with `name` after trim. Human output is the bucket id, the name, the endpoint, the bucket, the access key id, and the secret key, one value per line. The secret key is printed on this command only, so save it now. `--json` prints one JSON object of the response body: the bucket row and the credentials.
@@ -125,18 +137,37 @@ When storage is not configured, all four commands print `Storage is not availabl
 
 `astris whoami` calls `GET /v1/me`. It takes no flags besides `--json`. `--json` prints the account id, email, status, plan, and created_at, and the key id, name, and key_prefix. Human output is three lines: `Account: <email>`, `Plan: <plan>` (`Plan: none` when plan is null), and `Key: <name> (<key_prefix>)`.
 
+### next
+
+`astris next` prints this account's next step as one sentence. `--json` prints `{step, sentence}`.
+
 ### 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.
@@ -145,18 +176,22 @@ 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`, `compose`, `list`, `usage`, `plans`, `whoami`, `next`, `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.
 
-After the key, `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, and `storage` refuse a flag they do not know, a flag with no value, and a bare word that is not a flag. The sentence is `Those arguments were refused. Check the flags and send them again.`
+After the key, `deploy`, `status`, `env`, `domains`, `restart`, `diagnose`, `database`, `storage`, `compose`, and `next` refuse a flag they do not know, a flag with no value, and a bare word that is not a flag. The sentence is `Those arguments were refused. Check the flags and send them again.`
 
 `diagnose` requires `--app` set to an application id, the same check as `status`. `database` takes one word, `create`, `status`, `backup`, or `delete`. `create` requires `--project`, `--kind`, and `--name`. `--project` is a project id. `--kind` is exactly `postgres` or `redis`. `status` and `backup` each require `--id` set to a database id. `backup` is accepted. `delete` requires `--id` set to a database id and `--yes`, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. The plural `backups` is refused and makes no request.
 
 `storage` takes one word, `create`, `list`, `show`, or `delete`. `create` requires `--name`. `show` and `delete` each require `--id` set to a bucket id, and a `--id` that is not a bucket id makes no request. `delete` requires `--yes`, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. `list` takes no word, so `storage list buckets` is refused and makes no request.
 
+`compose` takes one word, `list`, `deploy`, `start`, or `stop`. `deploy`, `start`, and `stop` each require `--id` set to a compose stack id, and a repeated `--id` is refused with `Those arguments were refused. Check the flags and send them again.` and makes no request. `list` rejects `--id`.
+
+`next` takes no word and no flag besides `--json`.
+
 `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 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astris-labs/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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";
@@ -14,6 +16,7 @@ const SENTENCE = {
   projectId: "Send --project set to the project id.",
   databaseFlags: "Those arguments were refused. Send --project, --kind, and --name.",
   databaseId: "Send --id set to the database id.",
+  composeId: "Send --id set to the compose stack id.",
   domainId: "Send --id set to the domain id.",
   git: "The Git URL must not include a user name or password.",
   // T-169: reused word for word from the MCP's SENTENCE.deployKey (T-139).
@@ -41,6 +44,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([
@@ -48,6 +58,7 @@ const HTTP_SENTENCE = new Map([
   [401, SENTENCE.unauthorized],
   [404, SENTENCE.notFound],
   [409, SENTENCE.taken],
+  [429, "This account asked for too many changes in a short time. Wait a little, then try again."],
   [502, SENTENCE.platform],
 ]);
 
@@ -55,6 +66,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 +110,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 +124,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 +1513,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 +1537,487 @@ 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 };
+}
+
+const NEXT_OPTIONS = {
+  json: { type: "boolean" },
+};
+
+export async function next(args, io) {
+  const loaded = loadKey(io);
+  if (loaded.exit) return loaded.exit;
+  const parsed = parseStrict(args, NEXT_OPTIONS, false);
+  if (parsed === null || parsed.positionals.length > 0) {
+    return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const result = await call(io, loaded.key, { path: "/v1/me/next-step", method: "GET" });
+  if (result.network) return fail(io, loaded.key, json, SENTENCE.platform);
+  if (result.status !== 200) return fail(io, loaded.key, json, sentenceFor(result.status));
+  const body = isRecord(result.body) ? result.body : null;
+  const step = body?.step;
+  const sentence = body?.sentence;
+  if (typeof step !== "string" || typeof sentence !== "string") {
+    return fail(io, loaded.key, json, SENTENCE.failed);
+  }
+  if (json) return succeed(io, loaded.key, json, { step, sentence }, "");
+  return succeed(io, loaded.key, json, { step, sentence }, `${sentence}\n`);
+}
+
+const COMPOSE_LIST_OPTIONS = {
+  json: { type: "boolean" },
+};
+
+const COMPOSE_ACTION_OPTIONS = {
+  json: { type: "boolean" },
+  id: { type: "string", multiple: true },
+};
+
+const COMPOSE_UNION = {
+  json: { type: "boolean" },
+  id: { type: "string" },
+};
+
+function composePositionals(args) {
+  try {
+    return parseArgs({
+      args: Array.isArray(args) ? args : [],
+      strict: false,
+      allowPositionals: true,
+      options: COMPOSE_UNION,
+    }).positionals;
+  } catch {
+    return null;
+  }
+}
+
+function composeFields(value) {
+  if (!isRecord(value)) return null;
+  const id = value.id;
+  const projectId = value.project_id;
+  const name = value.name;
+  const gitUrl = value.git_url;
+  const branch = value.branch;
+  const composePath = value.compose_path;
+  const memoryLimit = value.memory_limit;
+  const createdAt = value.created_at;
+  const updatedAt = value.updated_at;
+  if (typeof id !== "string" || typeof projectId !== "string" || typeof name !== "string") return null;
+  if (typeof gitUrl !== "string" || typeof branch !== "string" || typeof composePath !== "string") return null;
+  if (typeof createdAt !== "string" || typeof updatedAt !== "string") return null;
+  if (typeof memoryLimit !== "number" || !Number.isInteger(memoryLimit)) return null;
+  const view = {
+    id,
+    project_id: projectId,
+    name,
+    git_url: gitUrl,
+    branch,
+    compose_path: composePath,
+    memory_limit: memoryLimit,
+    created_at: createdAt,
+    updated_at: updatedAt,
+  };
+  const projectName = value.project_name;
+  if (typeof projectName === "string") {
+    return { ...view, project_name: projectName };
+  }
+  return view;
+}
+
+function composeLines(view) {
+  return [
+    view.id,
+    view.project_id,
+    view.name,
+    view.git_url,
+    view.branch,
+    view.compose_path,
+    String(view.memory_limit),
+    view.created_at,
+    view.updated_at,
+  ];
+}
+
+function composeListLine(view) {
+  const base = `${view.id} ${view.name}`;
+  return typeof view.project_name === "string" ? `${base} ${view.project_name}` : base;
+}
+
+function requireComposeId(io, key, json, rawId) {
+  const ids = Array.isArray(rawId) ? rawId : rawId === undefined ? [] : [rawId];
+  if (ids.length > 1) return { exit: fail(io, key, json, SENTENCE.refused) };
+  const id = appUuid(ids[0]);
+  if (id === null) return { exit: fail(io, key, json, SENTENCE.composeId) };
+  return { id };
+}
+
+async function composeList(args, io, key) {
+  const parsed = parseStrict(args, COMPOSE_LIST_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== "list") {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  if (parsed.values.id !== undefined) return fail(io, key, wantsJson(args), SENTENCE.refused);
+  const json = parsed.values.json === true;
+  const result = await call(io, key, { path: "/v1/compose", method: "GET" });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 200) return fail(io, key, json, sentenceFor(result.status));
+  const items = isRecord(result.body) && Array.isArray(result.body.compose) ? result.body.compose : null;
+  if (items === null) return fail(io, key, json, SENTENCE.failed);
+  const views = [];
+  for (const item of items) {
+    const row = composeFields(item);
+    if (row === null) return fail(io, key, json, SENTENCE.failed);
+    views.push(row);
+  }
+  const human = views.length === 0 ? "" : `${views.map((row) => composeListLine(row)).join("\n")}\n`;
+  return succeed(io, key, json, { compose: views }, human);
+}
+
+async function composeDeploy(args, io, key) {
+  const parsed = parseStrict(args, COMPOSE_ACTION_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== "deploy") {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const required = requireComposeId(io, key, json, parsed.values.id);
+  if (required.exit) return required.exit;
+  const result = await call(io, key, {
+    path: `/v1/compose/${encodeURIComponent(required.id)}/deploy`,
+    method: "POST",
+  });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 202) {
+    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status));
+  }
+  const view = composeFields(isRecord(result.body) ? result.body.compose : null);
+  if (view === null) return fail(io, key, json, SENTENCE.failed);
+  const payload = { compose: view };
+  return succeed(io, key, json, payload, `${composeLines(view).join("\n")}\n`);
+}
+
+async function composeStartStop(args, io, key, action) {
+  const parsed = parseStrict(args, COMPOSE_ACTION_OPTIONS, true);
+  if (parsed === null || parsed.positionals.length !== 1 || parsed.positionals[0] !== action) {
+    return fail(io, key, wantsJson(args), SENTENCE.refused);
+  }
+  const json = parsed.values.json === true;
+  const required = requireComposeId(io, key, json, parsed.values.id);
+  if (required.exit) return required.exit;
+  const result = await call(io, key, {
+    path: `/v1/compose/${encodeURIComponent(required.id)}/${action}`,
+    method: "POST",
+  });
+  if (result.network) return fail(io, key, json, SENTENCE.platform);
+  if (result.status !== 200) {
+    return fail(io, key, json, upgradeMessage(result.status, result.body) ?? sentenceFor(result.status));
+  }
+  const body = isRecord(result.body) ? result.body : null;
+  const view = body === null ? null : composeFields(body.compose);
+  const statusText = body?.status;
+  if (view === null || typeof statusText !== "string") return fail(io, key, json, SENTENCE.failed);
+  const payload = { compose: view, status: statusText };
+  const lines = [statusText, ...composeLines(view)];
+  return succeed(io, key, json, payload, `${lines.join("\n")}\n`);
+}
+
+export async function compose(args, io) {
+  const loaded = loadKey(io);
+  if (loaded.exit) return loaded.exit;
+  const words = composePositionals(args);
+  if (words === null || words.length !== 1) return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+  if (words[0] === "list") return composeList(args, io, loaded.key);
+  if (words[0] === "deploy") return composeDeploy(args, io, loaded.key);
+  if (words[0] === "start") return composeStartStop(args, io, loaded.key, "start");
+  if (words[0] === "stop") return composeStartStop(args, io, loaded.key, "stop");
+  return fail(io, loaded.key, wantsJson(args), SENTENCE.refused);
+}

package/src/main.mjs

@@ -1,28 +1,82 @@
 #!/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, compose, database, deploy, diagnose, domains, env, list, login, logout, logs, next, 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],
+  ["compose", compose],
+  ["env", env],
+  ["domains", domains],
+  ["restart", restart],
+  ["logs", logs],
+  ["list", list],
+  ["usage", usage],
+  ["plans", plans],
+  ["whoami", whoami],
+  ["next", next],
+  ["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 +91,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);
 }