@progyai/cli 0.0.1

package/README.md

@@ -0,0 +1,151 @@
+# @progyai/cli
+
+Customer-side CLI for [progy](https://github.com/whatl3y/progy) — the permissionless AI proxy. Works against any progy deployment without cloning the server.
+
+## First-time setup (2 commands)
+
+```bash
+npx @progyai/cli init                       # mint a key, save to ~/.progy/credentials
+npx @progyai/cli topup --amount 10          # fund it
+```
+
+That's it. `progy balance`, `progy usage`, and provider requests through the proxy now Just Work because the saved key is picked up automatically.
+
+## Install
+
+Use ad-hoc with `npx` (recommended — always picks up the latest):
+
+```bash
+npx @progyai/cli <command>
+```
+
+Or install globally if you use it often:
+
+```bash
+npm i -g @progyai/cli
+progy <command>
+```
+
+> The x402 rail pulls in on-chain signing libraries (`viem` for EVM, `@solana/kit` for Solana) via the `@x402/*` packages, so the install footprint is larger than a typical CLI. This is required to sign payments locally without ever sending your key to the server.
+
+## Configuration
+
+The CLI resolves the URL and API key from (most-explicit wins):
+
+1. CLI flags (`--url`, `--key`)
+2. Env vars (`PROGY_URL`, `PROGY_API_KEY`)
+3. `~/.progy/credentials` for the active profile (written by `progy init`)
+4. Default URL `https://x.progy.ai` (key has no default)
+
+The credentials file is JSON with one entry per profile (`{ default: {...}, staging: {...}, ... }`), POSIX perms `0600` on the file and `0700` on the directory. Safe to delete at any time — `progy init` will recreate it.
+
+| Env | Flag | What |
+|---|---|---|
+| `PROGY_URL` | `--url` | the progy instance to talk to (default `https://x.progy.ai`) |
+| `PROGY_API_KEY` | `--key` | your `progy_sk_…` customer key |
+| `PROGY_PROFILE` | `--profile` | credentials profile to use (default `default`) |
+| `PROGY_TOPUP_PM_ID` | `--pm` | (topup) Stripe PaymentMethod id, e.g. `pm_card_visa` in test mode |
+| `PROGY_EVM_PRIVATE_KEY` | — | (topup x402) EVM wallet private key (`0x…`) that signs the on-chain payment |
+| `PROGY_SVM_PRIVATE_KEY` | — | (topup x402) Solana wallet secret key (base58) that signs the on-chain payment |
+| `PROGY_SVM_RPC_URL` | — | (topup x402) optional Solana RPC URL (defaults to a public RPC per network) |
+
+### Multi-environment usage
+
+The `--profile` flag (or `PROGY_PROFILE` env) lets a single user juggle several progy deployments — e.g. local + staging + prod — without re-running `init` each time:
+
+```bash
+progy init --profile prod --url https://progy.example.com
+progy init --profile staging --url https://staging.progy.example.com
+
+progy balance --profile prod
+PROGY_PROFILE=staging progy whoami
+```
+
+Profile names must be lowercase ASCII with optional dashes (e.g. `prod-eu-west-1`). The `default` profile is what's used when no profile is specified.
+
+## Commands
+
+### Setup
+
+#### `progy init`  *(alias: `progy keygen`)*
+
+Mint a fresh progy API key and save it to `~/.progy/credentials`. The new key has zero balance — top it up before making provider requests.
+
+Idempotent: if a key is already configured (env or file), prints what's there and exits 0. Pass `--force` to mint a new one anyway (which replaces the saved one).
+
+```bash
+npx @progyai/cli init                       # local default
+npx @progyai/cli init --url https://progy.example.com
+npx @progyai/cli init --force               # mint a new key over the saved one
+```
+
+#### `progy whoami`
+
+Show which account the CLI is configured to use and where the credentials came from (flag, env, or file). Best-effort pings `/v1/balance` for account_id and balance; falls back to local-only output if the proxy is unreachable.
+
+```bash
+npx @progyai/cli whoami
+```
+
+#### `progy logout`
+
+Delete saved credentials. With no flags, removes the default profile (and the whole file if no other profiles remain); with `--profile <name>`, removes just that one profile and leaves siblings intact. Exit 0 whether or not the profile existed (safe in cleanup scripts). The server-side account is untouched — only the local copy of the key is removed.
+
+```bash
+npx @progyai/cli logout
+npx @progyai/cli logout --profile staging        # remove just that one profile
+```
+
+#### `progy config`
+
+View or update the saved credentials for a profile. Unlike `init --force` (which mints a brand-new key), this **merges** — so you can repoint the URL while keeping your existing key, or swap the key while keeping the URL.
+
+```bash
+npx @progyai/cli config                          # show saved url + key prefix
+npx @progyai/cli config --url https://x.progy.ai # repoint the saved profile (keeps the key)
+npx @progyai/cli config --key progy_sk_…         # replace the saved key (keeps the url)
+```
+
+### Account
+
+#### `progy topup --amount <usd>`
+
+Credit your balance via either rail. `--rail` is auto-picked from what the server advertises (and whether you supplied a Stripe PM); pass it explicitly to force one.
+
+**Stripe (card)** — requires a Stripe PaymentMethod id:
+
+```bash
+PROGY_TOPUP_PM_ID=pm_… \
+npx @progyai/cli topup --amount 10 --rail stripe
+```
+
+**x402 (on-chain USDC)** — signs the payment locally with your wallet and settles via the proxy's facilitator. Works on EVM chains (Base, Polygon, …) and Solana. Pick the chain with `--network`:
+
+```bash
+# EVM (Base) — needs an EVM private key
+PROGY_EVM_PRIVATE_KEY=0x… \
+npx @progyai/cli topup --amount 10 --rail x402 --network base
+
+# Solana — needs a base58 secret key (and optionally a dedicated RPC)
+PROGY_SVM_PRIVATE_KEY=… \
+PROGY_SVM_RPC_URL=https://… \
+npx @progyai/cli topup --amount 10 --rail x402 --network solana
+```
+
+If the wallet key env var isn't set, the CLI prompts for it securely (hidden input) — nothing is written to disk. The key signs an EIP-3009 authorization (EVM) or an SPL-USDC transfer (Solana); the proxy never sees your private key. Built on the x402 v2 protocol (`PAYMENT-SIGNATURE` header) via the `@x402/*` packages.
+
+#### `progy balance`
+
+Show your current balance and the last 20 ledger entries.
+
+#### `progy usage [--since <Nd|Nh|Nm>]`
+
+Show your last 50 per-request usage records, optionally filtered to a recent window (e.g. `--since 7d`, `--since 3h`).
+
+### `progy --help` / `progy <command> --help`
+
+Print the dispatch help, or per-command help.
+
+## Versioning
+
+This CLI is **decoupled from the progy server** — it talks to whatever progy instance `PROGY_URL` points at, over the documented HTTP contract.

package/dist/commands/balance.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.balanceCommand = balanceCommand;
+const http_1 = require("../lib/http");
+const format_1 = require("../lib/format");
+async function balanceCommand(flags) {
+    const ctx = (0, http_1.resolveClient)(flags);
+    const body = (await (0, http_1.progyFetch)(ctx, '/v1/balance'));
+    console.log(`Account: #${body.account_id}${body.wallet_address ? ` (${body.wallet_address})` : ''}`);
+    console.log(`Balance: ${(0, format_1.usd)(body.balance_usd)}`);
+    const rows = body.recent_ledger.map((e) => [
+        (0, format_1.ts)(e.created_at),
+        e.type,
+        (0, format_1.usd)(e.amount_usd, true),
+        `→ ${(0, format_1.usd)(e.balance_after_usd)}`,
+        (0, format_1.shortId)(e.request_id),
+    ]);
+    if (rows.length === 0) {
+        console.log('\nNo ledger activity yet.');
+        return;
+    }
+    console.log('\nRecent activity:');
+    console.log((0, format_1.table)(rows, ['when', 'type', 'amount', 'balance after', 'request']));
+}

package/dist/commands/config.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configCommand = configCommand;
+const flags_1 = require("../lib/flags");
+const http_1 = require("../lib/http");
+const credentials_1 = require("../lib/credentials");
+/**
+ * View or update the saved credentials for a profile.
+ *
+ *   progy config                         # print the saved url + key prefix
+ *   progy config --url https://x.progy.ai  # repoint the saved profile (keeps the key)
+ *   progy config --key progy_sk_…        # replace the saved key (keeps the url)
+ *
+ * Updates are merged into the profile, so changing the url leaves the api_key
+ * intact and vice versa — unlike `init --force`, which mints a brand-new key.
+ */
+async function configCommand(flags) {
+    const profile = (0, http_1.resolveProfile)(flags);
+    const profileSuffix = profile === credentials_1.DEFAULT_PROFILE ? '' : ` --profile ${profile}`;
+    // `--url` / `--key` double as the connection flags; here they mean "save this".
+    const newUrl = (0, flags_1.readFlag)(flags, 'url');
+    const newKey = (0, flags_1.readFlag)(flags, 'key');
+    // No setters → just show the current saved config.
+    if (!newUrl && !newKey) {
+        const saved = (0, credentials_1.loadCredentials)(profile);
+        if (!saved || (!saved.url && !saved.api_key)) {
+            console.log(`No saved credentials for profile "${profile}".`);
+            console.log(`Mint one with: progy init${profileSuffix}`);
+            return;
+        }
+        console.log(`Profile:  ${profile}`);
+        console.log(`File:     ${(0, credentials_1.credentialsPath)()}`);
+        if (saved.url)
+            console.log(`URL:      ${saved.url}`);
+        if (saved.api_key)
+            console.log(`Key:      ${saved.api_key.slice(0, 18)}…`);
+        console.log(`\nUpdate with: progy config${profileSuffix} --url <url> [--key <key>]`);
+        return;
+    }
+    const update = {};
+    if (newUrl)
+        update.url = newUrl.replace(/\/$/, '');
+    if (newKey)
+        update.api_key = newKey;
+    (0, credentials_1.saveCredentials)(update, profile);
+    const saved = (0, credentials_1.loadCredentials)(profile);
+    console.log(`Updated profile "${profile}" at ${(0, credentials_1.credentialsPath)()}:`);
+    if (update.url)
+        console.log(`  URL: ${saved?.url}`);
+    if (update.api_key)
+        console.log(`  Key: ${saved?.api_key?.slice(0, 18)}…`);
+    if (update.url && !saved?.api_key) {
+        console.log(`\nNote: no key is saved for this profile yet — run \`progy init${profileSuffix}\` or set one with --key.`);
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initCommand = initCommand;
+const flags_1 = require("../lib/flags");
+const http_1 = require("../lib/http");
+const credentials_1 = require("../lib/credentials");
+async function initCommand(flags) {
+    const force = flags.force === true;
+    const profile = (0, http_1.resolveProfile)(flags);
+    const profileSuffix = profile === credentials_1.DEFAULT_PROFILE ? '' : ` --profile ${profile}`;
+    const url = ((0, flags_1.readFlag)(flags, 'url', 'PROGY_URL') || 'https://x.progy.ai').replace(/\/$/, '');
+    if (!force) {
+        // Idempotent check — env wins over file (both signal "you already have a key").
+        const envKey = process.env.PROGY_API_KEY;
+        const saved = (0, credentials_1.loadCredentials)(profile);
+        if (envKey) {
+            const prefix = envKey.slice(0, 18);
+            console.log(`You already have a progy API key configured via PROGY_API_KEY (prefix: ${prefix}).`);
+            console.log(`To mint a new one anyway: progy init${profileSuffix} --force`);
+            return;
+        }
+        if (saved?.api_key) {
+            const prefix = saved.api_key.slice(0, 18);
+            console.log(`You already have a progy account saved at ${(0, credentials_1.credentialsPath)()} (profile: ${profile}).`);
+            console.log(`  prefix: ${prefix}`);
+            if (saved.url)
+                console.log(`  url:    ${saved.url}`);
+            console.log(`\nTo mint a new one anyway: progy init${profileSuffix} --force`);
+            return;
+        }
+    }
+    // The mint endpoint is unauthenticated by design — no key required to call
+    // it (this is how you get one). Pass an empty `_` key to bypass the
+    // resolveClient guard; the bearer header gets ignored server-side for this
+    // public route, and a stub value keeps the fetch wrapper happy.
+    const body = (await (0, http_1.progyFetch)({ url, key: 'unauthenticated' }, '/v1/accounts', { method: 'POST', body: {} }));
+    (0, credentials_1.saveCredentials)({ url, api_key: body.api_key }, profile);
+    console.log('Created progy account.');
+    console.log('');
+    console.log(`Your API key (also saved to ${(0, credentials_1.credentialsPath)()} under profile "${profile}"):`);
+    console.log('');
+    console.log(`  ${body.api_key}`);
+    console.log('');
+    console.log(`Account #${body.account_id} · prefix ${body.prefix} · balance $${body.balance_usd}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log(`  progy topup${profileSuffix} --amount 10      # fund the new key`);
+    console.log(`  progy balance${profileSuffix}                # confirm the balance`);
+}

package/dist/commands/logout.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logoutCommand = logoutCommand;
+const http_1 = require("../lib/http");
+const credentials_1 = require("../lib/credentials");
+async function logoutCommand(flags) {
+    const profile = (0, http_1.resolveProfile)(flags);
+    const removed = (0, credentials_1.deleteCredentials)(profile);
+    const target = profile === credentials_1.DEFAULT_PROFILE
+        ? `default profile at ${(0, credentials_1.credentialsPath)()}`
+        : `profile "${profile}" at ${(0, credentials_1.credentialsPath)()}`;
+    if (removed) {
+        console.log(`Removed ${target}.`);
+    }
+    else {
+        console.log(`Nothing to remove for ${target}.`);
+    }
+}

package/dist/commands/topup.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topupCommand = topupCommand;
+const flags_1 = require("../lib/flags");
+const http_1 = require("../lib/http");
+const x402_1 = require("../lib/x402");
+const format_1 = require("../lib/format");
+function b64(s) {
+    return Buffer.from(s).toString('base64');
+}
+async function topupCommand(flags) {
+    const ctx = (0, http_1.resolveClient)(flags);
+    const amount = Number((0, flags_1.readFlag)(flags, 'amount'));
+    if (!Number.isFinite(amount) || amount <= 0)
+        throw new Error('missing/invalid --amount (USD)');
+    const rail = String((0, flags_1.readFlag)(flags, 'rail') ?? '').toLowerCase();
+    const network = (0, flags_1.readFlag)(flags, 'network');
+    const pm = (0, flags_1.readFlag)(flags, 'pm', 'PROGY_TOPUP_PM_ID');
+    // 1) Combined challenge — learns which rails the server has configured.
+    console.log(`Requesting challenge for ${(0, format_1.usd)(amount)} from ${ctx.url}/v1/topup …`);
+    const challenge = await (0, http_1.progyFetch)(ctx, '/v1/topup', {
+        method: 'POST',
+        body: { amountUsd: amount },
+    }).catch((err) => {
+        if (err.status === 402)
+            return err.body;
+        throw err;
+    });
+    const accepts = (challenge.accepts ?? []);
+    const railNames = accepts.map((a) => a.scheme).filter(Boolean);
+    const hasStripe = accepts.some((a) => a.scheme === 'stripe');
+    const x402Nets = (0, x402_1.offeredNetworks)(accepts);
+    console.log(`Configured rails: ${railNames.join(', ') || '(none)'}`);
+    if (x402Nets.length)
+        console.log(`x402 networks: ${x402Nets.join(', ')}`);
+    // 2) Pick the rail. Explicit --rail wins; otherwise prefer stripe when a PM is
+    // available, else fall back to x402 when an on-chain network is offered.
+    let chosen = rail;
+    if (!chosen) {
+        if (hasStripe && pm)
+            chosen = 'stripe';
+        else if (x402Nets.length)
+            chosen = 'x402';
+        else if (hasStripe)
+            chosen = 'stripe';
+        else
+            chosen = '';
+    }
+    if (chosen === 'x402') {
+        if (x402Nets.length === 0) {
+            throw new Error('x402 rail not advertised by the server for this top-up');
+        }
+        const result = await (0, x402_1.topupViaX402)(ctx, amount, { network });
+        console.log(`\n✓ Top-up settled on ${result.network}. New balance: ${(0, format_1.usd)(result.balanceUsd)}\n`);
+        return;
+    }
+    if (chosen !== 'stripe' || !hasStripe) {
+        throw new Error(`no usable rail (auto-picked "${chosen || 'none'}"). Configured: [${railNames.join(', ')}]. ` +
+            'For x402 set a wallet key (PROGY_EVM_PRIVATE_KEY / PROGY_SVM_PRIVATE_KEY) and pass --rail x402; ' +
+            'for stripe set STRIPE_SECRET_KEY + STRIPE_PUBLISHABLE_KEY on the proxy and provide --pm.');
+    }
+    if (!pm) {
+        throw new Error('missing PROGY_TOPUP_PM_ID (or --pm) — a saved Stripe PaymentMethod id ' +
+            '(e.g. pm_card_visa for test mode, or a real pm_… from the Stripe dashboard).');
+    }
+    // Stripe settle: base64-encoded {paymentMethodId, topUpAmountUsd} on a `payment` header.
+    const paymentHeader = b64(JSON.stringify({ paymentMethodId: pm, topUpAmountUsd: amount }));
+    console.log(`Charging ${(0, format_1.usd)(amount)} via Stripe (pm=${pm}) …`);
+    const result = await (0, http_1.progyFetch)(ctx, '/v1/topup', {
+        method: 'POST',
+        body: { amountUsd: amount },
+        extraHeaders: { payment: paymentHeader },
+    });
+    console.log(`\n✓ Top-up settled. New balance: ${(0, format_1.usd)(result?.balance_usd)}\n`);
+}

package/dist/commands/usage.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usageCommand = usageCommand;
+const flags_1 = require("../lib/flags");
+const http_1 = require("../lib/http");
+const format_1 = require("../lib/format");
+async function usageCommand(flags) {
+    const ctx = (0, http_1.resolveClient)(flags);
+    const sinceMs = (0, format_1.parseDuration)((0, flags_1.readFlag)(flags, 'since'));
+    const body = (await (0, http_1.progyFetch)(ctx, '/v1/usage'));
+    let records = body.usage;
+    if (sinceMs !== undefined) {
+        const threshold = Date.now() - sinceMs;
+        records = records.filter((r) => new Date(r.created_at).getTime() >= threshold);
+    }
+    console.log(`Account: #${body.account_id}  (${records.length} record${records.length === 1 ? '' : 's'})`);
+    if (records.length === 0)
+        return;
+    const rows = records.map((r) => [
+        (0, format_1.ts)(r.created_at),
+        r.provider,
+        r.model,
+        `${r.input_tokens}→${r.output_tokens}`,
+        (0, format_1.usd)(r.cost_usd),
+        (0, format_1.shortId)(r.request_id),
+    ]);
+    console.log();
+    console.log((0, format_1.table)(rows, ['when', 'provider', 'model', 'tokens (in→out)', 'cost', 'request']));
+    const total = records.reduce((sum, r) => sum + Number(r.cost_usd || 0), 0);
+    console.log(`\nTotal cost: ${(0, format_1.usd)(total)}`);
+}

package/dist/commands/whoami.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whoamiCommand = whoamiCommand;
+const flags_1 = require("../lib/flags");
+const http_1 = require("../lib/http");
+const credentials_1 = require("../lib/credentials");
+async function whoamiCommand(flags) {
+    const profile = (0, http_1.resolveProfile)(flags);
+    const profileSuffix = profile === credentials_1.DEFAULT_PROFILE ? '' : ` --profile ${profile}`;
+    const flagKey = (0, flags_1.readFlag)(flags, 'key', undefined);
+    const envKey = process.env.PROGY_API_KEY;
+    const saved = (0, credentials_1.loadCredentials)(profile);
+    let source;
+    let key;
+    if (flagKey) {
+        source = '--key flag';
+        key = flagKey;
+    }
+    else if (envKey) {
+        source = 'PROGY_API_KEY env';
+        key = envKey;
+    }
+    else if (saved?.api_key) {
+        source = `${(0, credentials_1.credentialsPath)()} [profile: ${profile}]`;
+        key = saved.api_key;
+    }
+    else {
+        source = '(none)';
+    }
+    const url = ((0, flags_1.readFlag)(flags, 'url', 'PROGY_URL') ||
+        saved?.url ||
+        'https://x.progy.ai').replace(/\/$/, '');
+    if (!key) {
+        console.log(`No progy API key is configured for profile "${profile}".`);
+        console.log(`URL would resolve to: ${url}`);
+        const others = (0, credentials_1.listProfiles)().filter((p) => p !== profile);
+        if (others.length > 0) {
+            console.log(`\nOther saved profiles: ${others.join(', ')}`);
+        }
+        console.log(`\nMint and save one with: progy init${profileSuffix}`);
+        return;
+    }
+    const prefix = key.slice(0, 18);
+    console.log(`Profile:    ${profile}`);
+    console.log(`Key prefix: ${prefix}`);
+    console.log(`Source:     ${source}`);
+    console.log(`URL:        ${url}`);
+    // Best-effort account lookup so the user sees account_id + balance without
+    // a second command. Network failures degrade gracefully.
+    try {
+        const body = (await (0, http_1.progyFetch)({ url, key }, '/v1/balance'));
+        console.log(`Account:    #${body.account_id}${body.wallet_address ? ` (${body.wallet_address})` : ''}`);
+        console.log(`Balance:    $${body.balance_usd}`);
+    }
+    catch (err) {
+        console.log(`Account:    (could not verify — ${err.message})`);
+    }
+}

package/dist/lib/credentials.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROFILE = void 0;
+exports.credentialsPath = credentialsPath;
+exports.loadCredentials = loadCredentials;
+exports.saveCredentials = saveCredentials;
+exports.deleteCredentials = deleteCredentials;
+exports.listProfiles = listProfiles;
+const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
+exports.DEFAULT_PROFILE = 'default';
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+function credentialsPath() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.progy', 'credentials');
+}
+function credentialsDir() {
+    return (0, path_1.dirname)(credentialsPath());
+}
+function assertValidProfile(name) {
+    if (!PROFILE_NAME_RE.test(name)) {
+        throw new Error(`invalid profile name "${name}" — must be lowercase ASCII letters, digits, or dashes (max 32 chars, must start with letter or digit)`);
+    }
+}
+/** Load a profile from the credentials file, or `undefined` if missing/unreadable. */
+function loadCredentials(profile = exports.DEFAULT_PROFILE) {
+    assertValidProfile(profile);
+    const path = credentialsPath();
+    if (!(0, fs_1.existsSync)(path))
+        return undefined;
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw.trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed[profile];
+    }
+    catch {
+        // Corrupt or hand-edited file — surface as "no credentials" rather than
+        // crashing the CLI; the user can recover by re-running `progy init`.
+        return undefined;
+    }
+}
+/**
+ * Persist credentials to the named profile (default: 'default'). Creates
+ * `~/.progy/` with 0700 and the file with 0600 if they don't already exist.
+ * Merges with any existing profiles so writes to one profile don't clobber
+ * siblings.
+ */
+function saveCredentials(creds, profile = exports.DEFAULT_PROFILE) {
+    assertValidProfile(profile);
+    const dir = credentialsDir();
+    const path = credentialsPath();
+    if (!(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    }
+    else {
+        // Existed already — tighten perms in case a previous run created it loose.
+        try {
+            (0, fs_1.chmodSync)(dir, 0o700);
+        }
+        catch {
+            // POSIX-only; ignore on platforms (e.g. Windows) where chmod is a no-op
+            // or unsupported.
+        }
+    }
+    let existing = {};
+    if ((0, fs_1.existsSync)(path)) {
+        try {
+            const raw = (0, fs_1.readFileSync)(path, 'utf8');
+            if (raw.trim())
+                existing = JSON.parse(raw);
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const merged = {
+        ...existing,
+        [profile]: { ...existing[profile], ...creds },
+    };
+    (0, fs_1.writeFileSync)(path, JSON.stringify(merged, null, 2) + '\n', {
+        mode: 0o600,
+        encoding: 'utf8',
+    });
+    try {
+        (0, fs_1.chmodSync)(path, 0o600);
+    }
+    catch {
+        // Same rationale as above.
+    }
+}
+/**
+ * Delete a single profile from the file (the whole file is removed when the
+ * last profile is gone, so the directory stays clean). When called with the
+ * default profile and no other profiles exist, behaves identically to the
+ * pre-multi-profile behavior. Returns true if something was removed.
+ */
+function deleteCredentials(profile = exports.DEFAULT_PROFILE) {
+    assertValidProfile(profile);
+    const path = credentialsPath();
+    if (!(0, fs_1.existsSync)(path))
+        return false;
+    let parsed;
+    try {
+        parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch {
+        // Corrupt file — easiest recovery is to nuke it.
+        try {
+            (0, fs_1.unlinkSync)(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (!(profile in parsed))
+        return false;
+    delete parsed[profile];
+    const remaining = Object.keys(parsed).filter((k) => parsed[k] !== undefined);
+    if (remaining.length === 0) {
+        try {
+            (0, fs_1.unlinkSync)(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    (0, fs_1.writeFileSync)(path, JSON.stringify(parsed, null, 2) + '\n', {
+        mode: 0o600,
+        encoding: 'utf8',
+    });
+    return true;
+}
+/** List the names of all profiles currently stored in the file. */
+function listProfiles() {
+    const path = credentialsPath();
+    if (!(0, fs_1.existsSync)(path))
+        return [];
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        return Object.keys(parsed)
+            .filter((k) => parsed[k] !== undefined)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/flags.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readFlag = readFlag;
+/** Read a string-typed flag with env fallback; throws with a clear hint if missing and required. */
+function readFlag(flags, name, envVar, required = false) {
+    const v = flags[name];
+    if (typeof v === 'string')
+        return v;
+    if (envVar) {
+        const env = process.env[envVar];
+        if (env)
+            return env;
+    }
+    if (required) {
+        const hint = envVar ? ` (or set ${envVar})` : '';
+        throw new Error(`missing --${name}${hint}`);
+    }
+    return undefined;
+}