@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/init.mjs

@@ -0,0 +1,175 @@
+/**
+ * Substrio CLI: `substrio init` command
+ * 
+ * Scaffolds a new Substrio project with:
+ *   substrio.toml      : project config
+ *   functions/      : cloud functions directory
+ *   functions/hello.js: sample function
+ *   public/         : static assets directory
+ *   package.json    : esbuild as a devDependency, for a function that imports an npm package
+ *   .gitignore      : gets `.substrio/` (the local dev server's data and keys), once
+ */
+
+import { appendFileSync, writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ErrorCode, Prompter, fail, globals } from '../cli.mjs';
+import { DEFAULT_FUNCTIONS_DIR, DEFAULT_PUBLIC_DIR, PROJECT_STATE_DIR } from '../config.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m', yellow: '\x1b[93m',
+};
+
+
+/** The .gitignore line that keeps the project's local substrio state (the dev server's data and keys) out of git. */
+export const STATE_IGNORE_LINE = `${PROJECT_STATE_DIR}/`;
+const STATE_IGNORE_FORMS = new Set([STATE_IGNORE_LINE, PROJECT_STATE_DIR]);
+
+/**
+ * Makes sure `dir`'s .gitignore lists the state directory, creating the file
+ * or appending to it, and only once: a line already there (with or without
+ * its trailing slash) is left as it is. Returns whether the file was changed.
+ */
+export function ensureGitignored(dir) {
+    const path = join(dir, '.gitignore');
+    const text = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    if (text.split('\n').some((line) => STATE_IGNORE_FORMS.has(line.trim()))) return false;
+    appendFileSync(path, `${text === '' || text.endsWith('\n') ? '' : '\n'}${STATE_IGNORE_LINE}\n`);
+    return true;
+}
+
+/**
+ * The substrio.toml `substrio init` writes. Every key sits in [project], where loadConfig
+ * reads them (config.mjs); a [paths] table is not read.
+ */
+export function initToml({ url, tenant, profile }) {
+    return `# Substrio Project Configuration
+# The key is never kept here: it lives in the profile below (~/.substrio/config.toml,
+# written by "substrio login"), or in SUBSTRIO_MASTER_KEY.
+
+[project]
+url = "${url}"
+tenant = "${tenant}"
+profile = "${profile}"
+functions_dir = "${DEFAULT_FUNCTIONS_DIR}"
+public_dir = "${DEFAULT_PUBLIC_DIR}"
+`;
+}
+
+/** The AGENTS.md `substrio init` writes for a project with none yet: where an agent reads this project's own docs and skills. */
+export function agentsMdTemplate({ url }) {
+    return `# Agents
+
+This project runs on substrio. An agent working in this repo should read its
+docs and skills from the server before guessing:
+
+- \`GET ${url}/llms.txt\` - an index of every doc page and skill.
+- \`substrio skills install\` - writes the server's skills where this
+  agent reads its own from (Claude, Cursor, Codex, or this file).
+`;
+}
+
+/**
+ * The esbuild version `substrio init` writes into a new project's package.json: the one this CLI's own
+ * repo depends on, so a function that bundles locally and on the server bundles with the same
+ * esbuild. An existing project without it gets the typed error of function-build.mjs's buildFunction
+ * instead (no esbuild, no network call made for it).
+ */
+export const ESBUILD_VERSION = '^0.25.10';
+
+/** The package.json `substrio init` writes, as an object (JSON.stringify it to write it). */
+export function packageJsonTemplate({ name }) {
+    return { name, private: true, devDependencies: { esbuild: ESBUILD_VERSION } };
+}
+
+/**
+ * substrio init [--url URL] [--tenant SLUG] [--profile NAME] [--yes]
+ *
+ * substrio.toml never holds a key (it is meant to be committed): the key lives in
+ * a profile ("substrio login"), which substrio.toml names. Values not given as flags
+ * are asked on a terminal, on one readline; with no terminal, the defaults
+ * are used. An existing substrio.toml is replaced only with --yes or a yes
+ * answer; declining exits non-zero.
+ */
+export async function cmdInit(args = []) {
+    const cwd = process.cwd();
+    let url = null;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url' && args[i + 1]) url = args[++i];
+        else fail(`unexpected argument "${args[i]}"`, 'substrio init --help');
+    }
+    const prompter = new Prompter();
+    let tenant = globals.tenant;
+    let profile = globals.profile;
+    try {
+        if (existsSync(join(cwd, 'substrio.toml')) && !globals.yes) {
+            const overwrite = await prompter.ask(`${C.yellow}substrio.toml already exists.${C.reset} Overwrite? (yes/no)`, '', '--yes');
+            if (!/^y(es)?$/i.test(overwrite)) fail('Aborted; substrio.toml is unchanged.', null, ErrorCode.UNKNOWN);
+        }
+        if (prompter.interactive) console.log(`\n${C.bold}${C.cyan}Substrio Project Setup${C.reset}\n`);
+        url = url || await prompter.ask('Server URL', 'http://localhost:9000');
+        tenant = tenant || await prompter.ask('Tenant/project name', 'default');
+        profile = profile || await prompter.ask('Profile holding the key (substrio login saves it)', 'default');
+    } catch (err) {
+        fail(err, 'substrio init --url URL --tenant SLUG --profile NAME --yes');
+    } finally {
+        prompter.close();
+    }
+
+    const tomlContent = initToml({ url, tenant, profile });
+
+    // Write files
+    writeFileSync(join(cwd, 'substrio.toml'), tomlContent);
+    console.log(`  ${C.green}✓${C.reset} Created ${C.bold}substrio.toml${C.reset}`);
+
+    // Create directories
+    mkdirSync(join(cwd, DEFAULT_FUNCTIONS_DIR), { recursive: true });
+    console.log(`  ${C.green}✓${C.reset} Created ${C.bold}functions/${C.reset}`);
+
+    mkdirSync(join(cwd, DEFAULT_PUBLIC_DIR), { recursive: true });
+    console.log(`  ${C.green}✓${C.reset} Created ${C.bold}public/${C.reset}`);
+
+    if (ensureGitignored(cwd)) console.log(`  ${C.green}✓${C.reset} Added ${C.bold}${STATE_IGNORE_LINE}${C.reset} to ${C.bold}.gitignore${C.reset} ${C.dim}(the dev server's data and keys)${C.reset}`);
+
+    // Sample function
+    const sampleFn = `/**
+ * Hello World: Sample Substrio Cloud Function
+ * 
+ * Deploy with: substrio deploy
+ * Invoke with: substrio invoke hello --data '{"name": "world"}'
+ */
+(function(event) {
+    return JSON.stringify({
+        message: "Hello from Substrio! 🚀",
+        timestamp: Date.now(),
+        input: event.body
+    });
+})
+`;
+
+    if (!existsSync(join(cwd, 'functions', 'hello.js'))) {
+        writeFileSync(join(cwd, 'functions', 'hello.js'), sampleFn);
+        console.log(`  ${C.green}✓${C.reset} Created ${C.bold}functions/hello.js${C.reset} ${C.dim}(sample function)${C.reset}`);
+    }
+
+    // esbuild bundles a function's npm imports (packages/substrio-cli/src/function-build.mjs); a
+    // function importing only the runtime's builtins needs it at neither install nor deploy time.
+    if (!existsSync(join(cwd, 'package.json'))) {
+        writeFileSync(join(cwd, 'package.json'), JSON.stringify(packageJsonTemplate({ name: tenant }), null, 2) + '\n');
+        console.log(`  ${C.green}✓${C.reset} Created ${C.bold}package.json${C.reset} ${C.dim}(esbuild, to bundle a function's npm imports)${C.reset}`);
+    }
+
+    if (!existsSync(join(cwd, 'AGENTS.md'))) {
+        writeFileSync(join(cwd, 'AGENTS.md'), agentsMdTemplate({ url }));
+        console.log(`  ${C.green}✓${C.reset} Created ${C.bold}AGENTS.md${C.reset} ${C.dim}(points an agent at /llms.txt and substrio skills install)${C.reset}`);
+    }
+
+    console.log(`
+${C.bold}${C.green}✓ Project initialized!${C.reset}
+
+${C.bold}Next steps:${C.reset}
+  ${C.cyan}1.${C.reset} Edit ${C.bold}functions/hello.js${C.reset} or add more functions
+  ${C.cyan}2.${C.reset} Run ${C.green}substrio deploy${C.reset} to push to your server
+  ${C.cyan}3.${C.reset} Test with: ${C.green}substrio invoke hello --data '{"name": "world"}'${C.reset}
+`);
+}

package/src/commands/key.mjs

@@ -0,0 +1,172 @@
+/**
+ * Substrio CLI: `substrio key` command
+ *
+ * The tenant's own key, the credential its owner deploys with. The server
+ * keeps only a digest of it: the key is shown once, when it is created or
+ * rotated, and no call returns it again.
+ *   substrio key rotate            Replace the tenant's key and save the new one
+ *                              in the current profile (never printed). The
+ *                              old key stops working at once.
+ *   substrio key rotate --overlap 1h
+ *                              The old key keeps working for that long beside
+ *                              the new one (s, m, h or d; at most 7d), so a
+ *                              deploy can switch over.
+ *   substrio key rotate --expires-in 90d
+ *                              The new key stops working after that long
+ *                              (a request with it then answers KEY_EXPIRED).
+ *   substrio key rotate --print    Also write the new key to stdout, alone on
+ *                              one line, for handing it on (e.g. to CI).
+ *   substrio key list              The tenant's keys: ids, created, expires and
+ *                              state (never a key).
+ *   substrio key revoke ID         End the previous key's overlap now.
+ *   substrio key export --env FILE [--var NAME] [--force]
+ *                              Write NAME=<the key in use> (default SUBSTRIO_KEY) to FILE,
+ *                              owner-only (0600), for an MCP client config or a
+ *                              process that reads its key from the environment
+ *                              (".mcp.json" names ${SUBSTRIO_KEY}). Never printed. An
+ *                              existing FILE is refused unless --force replaces it.
+ */
+
+import { existsSync } from 'node:fs';
+
+import { CliError, ErrorCode, emit, emitIssuedKey, fail } from '../cli.mjs';
+import { setProfileKey, writePrivateFile } from '../config.mjs';
+import { FlagKind, parseFlags } from '../local/args.mjs';
+import { splitPositional } from '../ops.mjs';
+import { invokeOperation, runOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m',
+};
+
+const USAGE = 'substrio key rotate [--overlap 1h] [--expires-in 90d] [--print] | list | revoke ID | export --env FILE [--var NAME] [--force]';
+/** The variable `key export` writes unless --var names another. */
+export const DEFAULT_KEY_VARIABLE = 'SUBSTRIO_KEY';
+
+const isLetterOrUnderscore = (c) => (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || c === '_';
+const isDigit = (c) => c >= '0' && c <= '9';
+
+/** Whether `name` can be an environment variable's name: a letter or _ first, then letters, digits and _ (pure). */
+export const isVariableName = (name) => name.length > 0 && isLetterOrUnderscore(name[0]) && [...name].every((c) => isLetterOrUnderscore(c) || isDigit(c));
+
+/**
+ * The key in use, written as one `NAME=KEY` line to `file`, owner-only (pure but for the file): refused when
+ * `file` exists unless `force`. Returns {file, variable}; the key is in no return value, message or output.
+ */
+export function exportKey(key, { file, variable = DEFAULT_KEY_VARIABLE, force = false }) {
+    if (!isVariableName(variable)) throw new CliError(`--var ${variable} is not a variable name (letters, digits and _, not starting with a digit)`, { code: ErrorCode.INVALID_ARGUMENT });
+    if (typeof key !== 'string' || key === '') {
+        throw new CliError('No key to export: none is saved in the profile in use', { code: ErrorCode.CREDENTIAL_REQUIRED, hint: 'Run "substrio login" first' });
+    }
+    if (!force && existsSync(file)) throw new CliError(`${file} exists; --force replaces it`, { code: ErrorCode.INVALID_ARGUMENT });
+    try {
+        writePrivateFile(file, `${variable}=${key}\n`, { exclusive: !force });
+    } catch (err) {
+        if (err.code === 'EEXIST') throw new CliError(`${file} exists; --force replaces it`, { code: ErrorCode.INVALID_ARGUMENT });
+        throw new CliError(`Could not write ${file}: ${err.message}`, { code: ErrorCode.UNKNOWN });
+    }
+    return { file, variable };
+}
+
+const SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
+
+// The value after `name`, or null when the flag is absent. A flag given with
+// no value (last, or followed by another flag) is an error, never absent.
+function flag(args, name) {
+    const at = args.indexOf(name);
+    if (at === -1) return null;
+    const value = args[at + 1];
+    if (value === undefined || value.startsWith('--')) fail(`${name} needs a value`);
+    return value;
+}
+
+// "90s", "15m", "2h", "7d", or a bare count of `bare` units, in seconds.
+function duration(text, flagName, bare) {
+    const match = /^(\d+)([smhd]?)$/.exec(text ?? '');
+    if (!match) fail(`${flagName} takes a duration like 90s, 15m, 2h or 7d`);
+    return Number(match[1]) * SECONDS[match[2] || bare];
+}
+
+function whenText(seconds) {
+    return seconds == null ? 'never' : new Date(seconds * 1000).toISOString();
+}
+
+function showKeys({ slug, keys = [] }) {
+    console.log(`\n${C.bold}Keys of ${slug}${C.reset} ${C.dim}(stored as digests)${C.reset}\n`);
+    for (const key of keys) {
+        const created = key.created == null ? 'unknown' : whenText(key.created);
+        console.log(`  ${C.bold}${key.id}${C.reset}  ${key.state.padEnd(8)} created ${created}  expires ${whenText(key.expires)}`);
+    }
+    console.log('');
+}
+
+const EXPORT_FLAGS = Object.freeze({ '--env': FlagKind.VALUE, '--var': FlagKind.VALUE, '--force': FlagKind.SWITCH });
+
+// `key export`: the flags parsed, the key written; says where it went, never the key.
+function exportCommand(config, args) {
+    let done;
+    try {
+        const { flags, positional } = parseFlags(args, EXPORT_FLAGS);
+        if (positional.length > 0) throw new CliError(`unexpected argument "${positional[0]}"`, { code: ErrorCode.INVALID_ARGUMENT });
+        if (!flags.has('--env')) throw new CliError('key export needs --env FILE', { code: ErrorCode.INVALID_ARGUMENT, hint: USAGE });
+        done = exportKey(config.master_key, { file: flags.get('--env'), variable: flags.get('--var') ?? DEFAULT_KEY_VARIABLE, force: flags.has('--force') });
+    } catch (err) {
+        fail(err);
+    }
+    emit({ ...done, profile: config.profile || null }, () => {
+        console.log(`${C.green}✓${C.reset} The key${config.profile ? ` of profile ${C.bold}${config.profile}${C.reset}` : ''} written to ${done.file} as ${C.bold}${done.variable}${C.reset} (owner-only); it is shown nowhere.`);
+    });
+}
+
+export async function cmdKey(api, config, args) {
+    switch (args[0]) {
+        case 'export':
+            return exportCommand(config, args.slice(1));
+        case 'rotate':
+            return rotate(api, config, args.slice(1));
+        case 'list':
+        case 'ls':
+            return runOperation(api, 'tenant.key.list', args.slice(1), { render: showKeys });
+        case 'revoke': {
+            // The key id is a bare word: it fills the route's {id} like any
+            // other operation alias (splitPositional, then runOperation).
+            const { positional, rest } = splitPositional(args.slice(1));
+            if (positional.length !== 1) fail(`Usage: substrio key revoke ID`);
+            return runOperation(api, 'tenant.key.revoke', rest, { positional });
+        }
+        default:
+            return fail(`Usage: ${USAGE}`);
+    }
+}
+
+async function rotate(api, config, args) {
+    const print = args.includes('--print');
+    // A key from SUBSTRIO_MASTER_KEY or substrio.toml has nowhere to be saved.
+    const saved = config.profile && !process.env.SUBSTRIO_MASTER_KEY;
+    if (!saved && !print) {
+        fail('The key does not come from a saved profile, so the new one could not be kept.',
+            'Run "substrio login" first, or pass --print to receive the new key.');
+    }
+
+    const input = {};
+    const overlap = flag(args, '--overlap');
+    if (overlap !== null) input.overlap_seconds = duration(overlap, '--overlap', 's');
+    const expiresIn = flag(args, '--expires-in');
+    if (expiresIn !== null) {
+        // Whole days: 90d, or a bare 90.
+        const days = duration(expiresIn, '--expires-in', 'd') / SECONDS.d;
+        if (!Number.isInteger(days)) fail('--expires-in takes whole days, like 90d');
+        input.expires_in_days = days;
+    }
+
+    const data = await invokeOperation(api, 'tenant.key.rotate', input);
+    if (typeof data?.key !== 'string' || !data.key) fail('The key was rotated but the server returned no new key.', null, ErrorCode.UNKNOWN);
+    if (saved) setProfileKey(config.profile, data.key);
+    emitIssuedKey(data, print);
+    const where = saved ? `saved to profile ${C.bold}${config.profile}${C.reset}` : 'printed above';
+    const old = data.previous
+        ? `the old key works until ${whenText(data.previous.expires)}.`
+        : 'the old key no longer works.';
+    console.error(`${C.green}✓${C.reset} New key ${C.bold}${data.key_id}${C.reset} for ${C.bold}${data.slug}${C.reset} ${where}; ${old}`);
+}

package/src/commands/login.mjs

@@ -0,0 +1,167 @@
+/**
+ * Substrio CLI: login command
+ * 
+ * Usage:
+ *   substrio login                                  Interactive login (a terminal)
+ *   substrio login [--url X] --key - [--tenant T] [--profile N] [--default]
+ *                                               The key read from stdin
+ *   substrio login --offline --url X --tenant T --key - [--profile N] [--default]
+ *                                               Saves the profile with no round trip (--tenant required)
+ *   substrio login --list                           List saved profiles
+ *   substrio login --remove NAME                    Remove a profile
+ *
+ * The profile keeps the URL, the key and the tenant the key belongs to
+ * (--tenant, the global flag; else the server's auth.whoami for the key).
+ * --profile (the global flag) names the profile saved. Without --profile the
+ * profile becomes the default, so later commands need neither --profile nor
+ * --tenant. With --profile it never changes the default profile (it is shared
+ * by every project) unless --default is passed or no default exists yet. With
+ * no terminal, nothing is asked: a missing key is an error. With no --url the profile is the hosted platform,
+ * DEFAULT_URL, so an outside developer's first login needs only the key.
+ *
+ * --offline skips the round trip entirely (the server need not be up yet): no
+ * auth.whoami lookup, so --tenant is required; the profile is saved marked
+ * `checked: false` (config.mjs writeProfile) until a login without --offline
+ * saves it again.
+ */
+
+import { CliError, ErrorCode, Prompter, emit, fail, globals } from '../cli.mjs';
+import { listProfiles, loadRC, rcPath, removeProfile, writeProfile } from '../config.mjs';
+import { SubstrioAPI, errorText } from '../api.mjs';
+import { OpError, callOperation, loadOperations } from './op.mjs';
+
+// The hosted platform: the server a login names when no --url is given.
+export const DEFAULT_URL = 'https://mcp.substrio.com';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+
+export async function cmdLogin(args) {
+    // --list
+    if (args.includes('--list')) {
+        const profiles = listProfiles();
+        if (globals.json) return emit(profiles);
+        if (profiles.length === 0) {
+            console.log(`${C.dim}No profiles saved. Run "substrio login" to add one.${C.reset}`);
+            return;
+        }
+        console.log(`\n${C.bold}Saved Profiles${C.reset}\n`);
+        const nameW = Math.max(10, ...profiles.map(p => p.name.length));
+        console.log(`  ${'NAME'.padEnd(nameW)}  URL`);
+        console.log(`  ${'─'.repeat(nameW)}  ${'─'.repeat(30)}`);
+        for (const p of profiles) {
+            const marker = p.isDefault ? ` ${C.green}(default)${C.reset}` : '';
+            console.log(`  ${p.name.padEnd(nameW)}  ${p.url}${marker}`);
+        }
+        console.log('');
+        return;
+    }
+
+    // --remove NAME
+    const rmIdx = args.indexOf('--remove');
+    if (rmIdx !== -1) {
+        const name = args[rmIdx + 1];
+        if (!name) {
+            console.error(`${C.red}✗ Profile name required.${C.reset}`);
+            process.exit(1);
+        }
+        if (removeProfile(name)) {
+            console.log(`${C.green}✓${C.reset} Profile ${C.bold}${name}${C.reset} removed.`);
+        } else {
+            console.error(`${C.red}✗ Profile "${name}" not found.${C.reset}`);
+            process.exit(1);
+        }
+        return;
+    }
+
+    // --url X --key Y (or - for stdin); --tenant and --profile are global.
+    let url = null, key = null, makeDefault = globals.profile === null, offline = false;
+    let tenant = globals.tenant, profileName = globals.profile;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--url' && args[i + 1]) url = args[++i];
+        else if (args[i] === '--key' && args[i + 1]) key = args[++i];
+        else if (args[i] === '--default') makeDefault = true;
+        else if (args[i] === '--offline') offline = true;
+        else fail(`unexpected argument "${args[i]}"`, 'substrio login --help');
+    }
+    if (offline && !tenant) {
+        return fail('--offline needs --tenant: with no server reachable the CLI cannot look the tenant up for the key',
+            'substrio login --offline --url URL --tenant SLUG --key - < keyfile', ErrorCode.INVALID_ARGUMENT);
+    }
+
+    // --key - reads the key from stdin, keeping it out of argv and history.
+    if (key === '-') {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        key = Buffer.concat(chunks).toString('utf-8').trim();
+    }
+
+    const prompter = new Prompter();
+    try {
+        if (!url || !key) {
+            if (prompter.interactive) console.log(`\n${C.bold}${C.cyan}Substrio Login${C.reset}\n`);
+            url = url || await prompter.ask('  Server URL', DEFAULT_URL, '--url');
+            key = key || await prompter.ask('  Key (your tenant\'s key, given when it was created or by "substrio key rotate")', '', '--key -');
+        }
+        url = url.replace(/\/+$/, '');
+        if (offline) {
+            // No round trip: the tenant is required (checked above), nothing to look up.
+        } else {
+            const server = await connect(url, key);
+            // The tenant: --tenant, else the one the server says the key belongs
+            // to, else asked (default "default").
+            tenant = tenant || await keyTenant(server) || await prompter.ask('  Tenant the key belongs to', 'default');
+        }
+        profileName = profileName || await prompter.ask('  Profile name', 'default');
+    } catch (err) {
+        fail(err, offline ? 'substrio login --offline --url URL --tenant SLUG --key - < keyfile' : 'substrio login --url URL [--tenant SLUG] --key - < keyfile');
+    } finally {
+        prompter.close();
+    }
+
+    // The profile keeps the tenant. It becomes the default when no --profile
+    // named it (later commands need neither --profile nor --tenant) or
+    // --default says so; writeProfile also makes it the default when there is
+    // none. A named profile otherwise leaves the shared default alone.
+    writeProfile(profileName, url, key, tenant, { makeDefault, checked: !offline });
+    const defaultProfile = loadRC().default_profile;
+    const isDefault = defaultProfile === profileName;
+    emit({ profile: profileName, url, tenant, default: isDefault, default_profile: defaultProfile, path: rcPath(), ...(offline ? { checked: false } : {}) }, () => {
+        console.log(`${C.green}✓${C.reset} Profile ${C.bold}${profileName}${C.reset} (tenant ${C.bold}${tenant}${C.reset}) saved to ${rcPath()}` +
+            `${isDefault ? ' as the default' : `; the default profile stays ${C.bold}${defaultProfile}${C.reset} (--default makes this one the default)`}`);
+        if (offline) console.log(`${C.dim}  Saved without checking the server (--offline); "substrio whoami" shows whether the key works once the server is up.${C.reset}`);
+        console.log(`${C.dim}  "substrio whoami" shows it; "substrio login --list" lists every profile.${C.reset}`);
+    });
+}
+
+// The server at `url`, read with `key` and no tenant: its catalog, after
+// system.health says it is up. Throws the server's typed error otherwise.
+async function connect(url, key) {
+    const api = new SubstrioAPI({ url, master_key: key, tenant: null });
+    const ops = await loadOperations(api);
+    const health = await callOperation(api, ops, 'system.health', undefined);
+    if (!health.ok) {
+        throw CliError.fromResponse(`Server responded with ${health.status}: ${errorText(health.data, health.status)}. Check the URL.`,
+            health.data, health.status);
+    }
+    // The server tells its version to a holder of the master key only (a tenant or account key gets the status alone).
+    const version = health.data?.version;
+    console.log(`${C.green}✓${C.reset} Connected to server${typeof version === 'string' && version !== '' ? ` (${version})` : ''}`);
+    return { api, ops };
+}
+
+// The tenant the server says the key belongs to (auth.whoami), or null (an
+// account or system key, or a server without whoami).
+async function keyTenant({ api, ops }) {
+    try {
+        const result = await callOperation(api, ops, 'auth.whoami', undefined);
+        const tenant = result.ok ? result.data?.tenant : null;
+        return typeof tenant === 'string' && tenant ? tenant : null;
+    } catch (err) {
+        if (err instanceof OpError) return null;
+        throw err;
+    }
+}