aweshare 0.7.2 → 0.7.4

package/apps/hub/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { fmtDate, fmtTime, fmtTokens } from '../../../packages/protocol/dist/index.js';
+import { fmtDate, fmtTime, fmtTokens, isValidAlias } from '../../../packages/protocol/dist/index.js';
+import { parseBackups, readBackupsFile, serializeBackups, writeBackupsFile } from './backups.js';
 import { ensureDataDir, HUB_CONFIG_TEMPLATE, initHubProduceFiles, loadHubConfig, readAdminToken, resolvePaths, } from './config.js';
 import { createHubServer, installConfigReloader } from './server.js';
 import { refreshTargets, renderConsumers, renderHubStatus, renderInvites, renderOfferings, renderProducers, renderUsage, renderUsageSummary, } from './table.js';
@@ -22,7 +23,8 @@ Commands:
   admin    Govern: invite mint|revoke|restore, offering revoke|restore.
   list     Read hub state: invites (default), producers, consumers, offerings, usage.
   status   Live dashboard: capacity, 5m health, admission pressure, defaults.
-  limits   Show, set or clear one consumer's limit overrides.`;
+  limits   Show, set or clear one or more consumers' limit overrides.
+  backups  Per-alias failover queues: show, add, remove or clear.`;
 const COMMAND_HELP = {
     init: `Usage: aweshare hub init
 
@@ -61,19 +63,20 @@ Options:
   initializes the Hub data directory, database, pepper and admin token.
 
   ` +
-        '`refresh ALIAS`' +
+        '`refresh ALIAS...`' +
         ` works on a running hub, no restart: re-anchor the daily token
-  budget of one hub/... model at this moment (past usage today stops
-  counting), or raise it for the rest of today. Producer-registered models
-  (ns/...) are not the hub's to refresh — that producer runs
-  'aweshare producer refresh' itself. A permanent raise belongs in
-  config.produce.toml (dailyTokens), which hot-reloads. --all
+  budget of one or several hub/... models at this moment (past usage today
+  stops counting), or raise it for the rest of today — several aliases per
+  call, space- or comma-separated, one failure does not stop the rest.
+  Producer-registered models (ns/...) are not the hub's to refresh — that
+  producer runs 'aweshare producer refresh' itself. A permanent raise
+  belongs in config.produce.toml (dailyTokens), which hot-reloads. --all
   bare-refreshes every hub/ model with a daily cap in one run; unlimited
-  ones (dailyTokens = 0) are reported and skipped, and one failure does
-  not stop the rest.
+  ones (dailyTokens = 0) are reported and skipped.
 
   Examples:
     aweshare hub produce refresh glm-5.3                # today restarts now
+    aweshare hub produce refresh glm-5.3 glm-4.6        # several at once
     aweshare hub produce refresh --all                  # every hub/ model restarts today
     aweshare hub produce refresh glm-5.3 --add 2000000  # today's cap +2M
     aweshare hub produce refresh glm-5.3 --clear        # drop both markers
@@ -92,15 +95,19 @@ Options:
 
   Commands:
     invite mint [...]         Mint one-time invite codes.
-    invite revoke N           Kill invite N — the sledgehammer: a pending
+    invite revoke N...        Kill invites — the sledgehammer: a pending
                               code stops pairing, a redeemed one suspends
                               the whole producer or consumer it minted.
-    invite restore N          Undo an invite revoke.
-    invite extend N [...]     Set an invite and its minted identity's expiry.
-    offering revoke ALIAS     The scalpel: 503 OFFERING_BLOCKED for new
+    invite restore N...       Undo an invite revoke.
+    invite extend N [...]     Set a pending invite's expiry; a redeemed
+                              invite's token never expires.
+    offering revoke ALIAS...  The scalpel: 503 OFFERING_BLOCKED for new
                               requests to one alias while the producer's
                               other offerings keep serving.
-    offering restore ALIAS    Undo an offering revoke.
+    offering restore ALIAS... Undo an offering revoke.
+
+  Every N/ALIAS argument accepts several targets, space- or comma-separated;
+  one failure does not stop the rest.
 
   Run 'aweshare hub admin invite -h' or 'aweshare hub admin offering -h'
   for the full semantics of each group.
@@ -112,20 +119,24 @@ Options:
   The invite lifecycle. One code, one identity — and the invite is the
   operator's handle from mint to suspension: revoking a redeemed code
   suspends the producer or consumer it minted (a producer's tunnel closes,
-  a consumer's key stops working); restoring brings both back.
+  a consumer's key stops working); restoring brings both back. The code's
+  expiry bounds only the redemption window — the token a redeem mints never
+  expires; revoke/restore is its only lifecycle handle.
 
   Commands:
-    mint      Mint one-time invite codes. Printed once; recover
-              with: aweshare hub list invites --reveal. Listing lives under
-              'list invites' on purpose — minting sends real codes, reading
-              the ledger never should.
-    revoke N  Kill invite N: a pending code stops pairing, a redeemed one
-              suspends its identity (find ids with: aweshare hub list invites).
-    restore N Undo a revoke: pending pairs again, redeemed revives its
-              identity. Restoring a redeemed producer needs a free slot
-              (403 HUB_FULL at AWESHARE_MAX_PRODUCERS).
-    extend N  Set expiry from now for a pending code or its redeemed identity.
-              It does not restore a manually revoked identity.
+    mint          Mint one-time invite codes. Printed once; recover
+                  with: aweshare hub list invites --reveal. Listing lives under
+                  'list invites' on purpose — minting sends real codes, reading
+                  the ledger never should.
+    revoke N...   Kill invites: a pending code stops pairing, a redeemed one
+                  suspends its identity (find ids with: aweshare hub list
+                  invites).
+    restore N...  Undo a revoke: pending pairs again, redeemed revives its
+                  identity. Restoring a redeemed producer needs a free slot
+                  (403 HUB_FULL at AWESHARE_MAX_PRODUCERS).
+    extend N...   Reset a pending code's expiry from now ('none' = no
+                  deadline). A redeemed invite has nothing to extend — its
+                  token never expires — and says so.
 
   Options:
     --role ROLE     producer (default) or consumer — a consumer code redeems into
@@ -133,15 +144,14 @@ Options:
     --name NAME     Bind the codes to one name (required for --role consumer;
                     producers may leave it for redeem-time name + email).
     --count N       Mint N codes, 1..100 (default 1; producer codes only).
-    --expires-in D  How long codes stay usable: 30m, 12h or 7d (default 7d) —
-                    since identity expiry landed, this also bounds the minted
-                    token's lifetime; 'none' mints a code (and identity) that
-                    never expires. With extend, this is required and resets
-                    expiry from now.
+    --expires-in D  How long the code stays redeemable: 30m, 12h or 7d
+                    (default 7d); 'none' = no deadline. It bounds the code
+                    only — the minted token never expires. With extend, this
+                    is required.
     -h, --help      Show this message and exit.`,
-    'admin offering': `Usage: aweshare hub admin offering revoke|restore ALIAS
+    'admin offering': `Usage: aweshare hub admin offering revoke|restore ALIAS...
 
-  Revoke one offering alias (every protocol row of it) or bring it back —
+  Revoke offering aliases (every protocol row of them) or bring them back —
   the scalpel between doing nothing and revoking the whole producer
   ('admin invite revoke'). A revoke 503s new requests with
   OFFERING_BLOCKED while the producer's other offerings keep serving;
@@ -150,6 +160,9 @@ Options:
   autoBlockModelMismatch is enabled) clear once the producer re-declares
   a different upstreamModel.
 
+  Several aliases per call, space- or comma-separated; one failure does
+  not stop the rest.
+
 Options:
   -h, --help  Show this message and exit.`,
     list: `Usage: aweshare hub list [invites|producers|consumers|offerings|usage] [OPTIONS]
@@ -189,11 +202,13 @@ Options:
     --limit N         Usage --details only: rows to show, 1..1000 (default 100).
     --json            Print the raw API rows instead of a table.
     -h, --help        Show this message and exit.`,
-    limits: `Usage: aweshare hub limits NAME [OPTIONS]
+    limits: `Usage: aweshare hub limits NAME... [OPTIONS]
 
-  Show, set or clear one consumer's limit overrides. Unset keys keep the
-  hub-wide defaults (AWESHARE_CONSUMER_* env vars); setting merges into
-  what is already stored.
+  Show, set or clear consumers' limit overrides — one consumer or several
+  (space- or comma-separated). Unset keys keep the hub-wide defaults
+  (AWESHARE_CONSUMER_* env vars); setting merges into what is already
+  stored. One failure does not stop the rest; with --json a single name
+  keeps the plain object, several become an array.
 
   Options:
     --rps N               Requests per second (may be fractional).
@@ -205,6 +220,34 @@ Options:
     --clear               Drop every override (back to hub-wide defaults).
     --json                Print the raw API response instead of text.
     -h, --help            Show this message and exit.`,
+    backups: `Usage: aweshare hub backups [ALIAS] [OPTIONS]
+
+  Per-alias failover queues in the data dir's config.backups.toml: when an
+  alias cannot serve (producer offline, daily budget spent, degraded
+  backend, blocked, share window closed, busy), the hub retries the queue
+  in order before answering with the alias's own error. Entries resolve
+  to nothing are skipped; a queue is exactly what was written — no
+  implicit hops, no expansion. Edits hot-reload within ~2s. The file is
+  this machine's, so the command edits it locally: on a remote hub run it
+  there (ssh / docker exec), like every other config.toml change.
+
+  Bare ALIAS shows its queue; no ALIAS lists every queue.
+
+  Examples:
+    aweshare hub backups                                  # every queue
+    aweshare hub backups peng/qwen3-coder                 # one queue
+    aweshare hub backups peng/qwen3-coder --add alice/qwen3-coder
+    aweshare hub backups peng/qwen3-coder --add hub/glm-4.6 --first
+    aweshare hub backups peng/qwen3-coder --remove hub/glm-4.6
+    aweshare hub backups peng/qwen3-coder --clear
+
+Options:
+  --add ALIASES  Append (comma-separated aliases accepted); --first prepends instead.
+  --first        With --add: put the new backups at the front of the queue.
+  --remove A     Remove one backup alias from ALIAS's queue.
+  --clear        Drop ALIAS's queue entirely (the key disappears).
+  --json         Print the queue(s) as JSON.
+  -h, --help     Show this message and exit.`,
     status: `Usage: aweshare hub status
 
   The hub's live dashboard: capacity, the last-5m health, admission
@@ -393,6 +436,52 @@ function fmtLimits(name, overrides) {
         ? `${name}: ${set.join(', ')}`
         : `${name}: no overrides — hub-wide defaults apply (AWESHARE_CONSUMER_* env vars)`;
 }
+/** Split a comma-separated alias list ('a/b,c/d') — aliases cannot contain
+ * commas, so the split is unambiguous. */
+function splitAliases(raw) {
+    return raw
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+/** Several targets on one command line: spaces or commas both work
+ * ('18 19 22' or '18,19,22' — ids, names and aliases contain no commas). */
+function parseTargets(raw) {
+    return raw
+        .flatMap((arg) => arg.split(','))
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+/** --json across batch commands: one target keeps the plain object, several
+ * become an array. */
+function printJsonBatch(entries) {
+    console.log(JSON.stringify(entries.length === 1 ? entries[0] : entries, null, 2));
+}
+/** One API call per target, one line each — a failure does not stop the rest
+ * (same contract as `produce refresh --all`), and a nonzero exit code closes
+ * the run so scripts notice. Failed targets become {target, error} entries,
+ * so a --json run stays parseable. */
+async function runBatch(targets, verb, json, each) {
+    const entries = [];
+    let failed = 0;
+    for (const target of targets) {
+        try {
+            entries.push(await each(target));
+        }
+        catch (err) {
+            failed++;
+            const error = errorMessage(err);
+            entries.push({ target, error });
+            if (!json)
+                console.log(`✗ ${target} — ${error}`);
+        }
+    }
+    if (failed > 0) {
+        console.error(`error: ${failed} of ${targets.length} ${verb} failed`);
+        process.exitCode = 1;
+    }
+    return entries;
+}
 /** The five readable tables; bare `list` defaults to the ledger (a read,
  * and the one operators reach for first). */
 const LIST_TARGETS = ['invites', 'producers', 'consumers', 'offerings', 'usage'];
@@ -444,6 +533,10 @@ async function main() {
                 writeFileSync(paths.configFile, HUB_CONFIG_TEMPLATE, { mode: 0o600 });
                 console.log(`config file: ${paths.configFile} (every key commented out — edit to override)`);
             }
+            if (!existsSync(paths.backupsFile)) {
+                writeFileSync(paths.backupsFile, serializeBackups(new Map()), { mode: 0o600 });
+                console.log(`backups file: ${paths.backupsFile} (empty — per-alias failover queues, see: aweshare hub backups -h)`);
+            }
             const hub = createHubServer({ paths }); // creates the db schema
             await hub.close();
             console.log(`data dir:    ${paths.dataDir}`);
@@ -494,46 +587,50 @@ async function main() {
                 return;
             }
             checkFlags('produce', flags, ['add', 'clear', 'all', 'json']);
-            const raw = positional[1];
+            const raws = parseTargets(positional.slice(1));
             const all = flags.get('all') === 'true';
-            if (positional[2])
-                fail(`unexpected argument '${positional[2]}' (see: aweshare hub produce -h)`);
             if (all) {
-                if (raw)
-                    fail(`--all refreshes every hub/ model — drop the alias '${raw}'`);
+                if (raws.length > 0)
+                    fail(`--all refreshes every hub/ model — drop the alias '${raws[0]}'`);
                 if (flags.get('add') !== undefined || flags.get('clear') === 'true')
-                    fail('--all is a bare refresh of every hub/ model — --add/--clear stay single-alias');
+                    fail('--all is a bare refresh of every hub/ model — --add/--clear are per-alias');
                 const api = adminApi();
                 await runProduceRefreshAll(api, flags.get('json') === 'true');
                 return;
             }
-            if (!raw)
+            if (raws.length === 0)
                 fail('produce refresh: alias is required (hub/model — the hub/ prefix is optional), or --all for every hub/ model');
             // hub-hosted offerings live in the reserved hub/ namespace — accept
             // the bare name too; anything else the hub rejects as not its own
-            const alias = raw.includes('/') ? raw : `hub/${raw}`;
-            const params = new URLSearchParams({ alias });
+            const aliases = raws.map((raw) => (raw.includes('/') ? raw : `hub/${raw}`));
             const add = flags.get('add');
+            let addN;
             if (add !== undefined) {
-                const n = Number(add);
-                if (!Number.isSafeInteger(n) || n <= 0)
+                addN = Number(add);
+                if (!Number.isSafeInteger(addN) || addN <= 0)
                     fail(`--add must be a positive integer, got '${add}'`);
-                params.set('add', String(n));
-            }
-            if (flags.get('clear') === 'true') {
-                if (add !== undefined)
-                    fail('--clear drops both markers — drop --add too');
-                params.set('clear', 'true');
             }
+            const clear = flags.get('clear') === 'true';
+            if (clear && add !== undefined)
+                fail('--clear drops both markers — drop --add too');
+            const json = flags.get('json') === 'true';
             const api = adminApi();
-            const out = (await api('POST', `/admin/v1/offerings/refresh?${params}`));
-            if (flags.get('json') === 'true') {
-                console.log(JSON.stringify(out, null, 2));
-                return;
-            }
-            printRefreshResult(out);
-            if (out.reset)
-                console.log(`  undo: aweshare hub produce refresh ${out.alias} --clear`);
+            const entries = await runBatch(aliases, 'refresh(es)', json, async (alias) => {
+                const params = new URLSearchParams({ alias });
+                if (addN !== undefined)
+                    params.set('add', String(addN));
+                if (clear)
+                    params.set('clear', 'true');
+                const out = (await api('POST', `/admin/v1/offerings/refresh?${params}`));
+                if (!json) {
+                    printRefreshResult(out);
+                    if (out.reset)
+                        console.log(`  undo: aweshare hub produce refresh ${out.alias} --clear`);
+                }
+                return out;
+            });
+            if (json)
+                printJsonBatch(entries);
             return;
         }
         case 'admin': {
@@ -578,8 +675,9 @@ async function main() {
                     if (role === 'consumer' && count && count !== '1')
                         fail('consumer invites are one per name — drop --count and mint one per consumer');
                     // absent flag still mints a 7d code — an unexpiring secret should be a
-                    // deliberate choice (`none` here; API callers may omit expiresAt). Since
-                    // v12 the expiry also bounds the minted identity's lifetime.
+                    // deliberate choice (`none` here; API callers may omit expiresAt). The
+                    // expiry bounds the redemption window only; the minted identity
+                    // never expires.
                     const expiresIn = flags.get('expires-in') ?? '7d';
                     if (expiresIn !== 'none') {
                         body.expiresAt = new Date(Date.now() + parseDuration(expiresIn)).toISOString();
@@ -608,24 +706,27 @@ async function main() {
                     return;
                 }
                 checkFlags('admin invite', flags, action === 'extend' ? ['expires-in'] : []);
-                const id = positional[2];
-                if (!id)
+                const ids = parseTargets(positional.slice(2));
+                if (ids.length === 0)
                     fail(`invite ${action}: id is required (find ids with: aweshare hub list invites)`);
-                if (positional[3])
-                    fail(`unexpected argument '${positional[3]}' (see: aweshare hub admin invite -h)`);
                 if (action === 'revoke') {
-                    const out = (await api('DELETE', `/admin/v1/invites/${id}`));
-                    if (!out.revoked && !out.suspended) {
-                        console.log(`invite ${id} was already revoked — nothing to do`);
-                        return;
-                    }
-                    if (out.suspended) {
-                        console.log(`✓ invite ${id} revoked — ${out.suspended.role} '${out.suspended.name}' suspended, its token no longer works`);
-                    }
-                    else {
-                        console.log(`✓ invite ${id} revoked — the code no longer pairs`);
-                    }
-                    console.log(`  undo: aweshare hub admin invite restore ${id}`);
+                    const revokedIds = [];
+                    await runBatch(ids, 'revoke(s)', false, async (id) => {
+                        const out = (await api('DELETE', `/admin/v1/invites/${id}`));
+                        if (!out.revoked && !out.suspended) {
+                            console.log(`- invite ${id} was already revoked — nothing to do`);
+                            return;
+                        }
+                        revokedIds.push(id);
+                        if (out.suspended) {
+                            console.log(`✓ invite ${id} revoked — ${out.suspended.role} '${out.suspended.name}' suspended, its token no longer works`);
+                        }
+                        else {
+                            console.log(`✓ invite ${id} revoked — the code no longer pairs`);
+                        }
+                    });
+                    if (revokedIds.length > 0)
+                        console.log(`  undo: aweshare hub admin invite restore ${revokedIds.join(' ')}`);
                     return;
                 }
                 if (action === 'extend') {
@@ -635,26 +736,33 @@ async function main() {
                     const expiresAt = expiresIn === 'none'
                         ? null
                         : new Date(Date.now() + parseDuration(expiresIn)).toISOString();
-                    const out = (await api('POST', `/admin/v1/invites/${id}/extend`, { expiresAt }));
-                    console.log(out.expiresAt === null
-                        ? `✓ invite ${id} never expires`
-                        : `✓ invite ${id} expires ${fmtTime(out.expiresAt)}`);
-                    return;
-                }
-                const out = (await api('POST', `/admin/v1/invites/${id}/restore`));
-                if (!out.restored) {
-                    console.log(`invite ${id} was not revoked — nothing to restore`);
+                    await runBatch(ids, 'extend(s)', false, async (id) => {
+                        const out = (await api('POST', `/admin/v1/invites/${id}/extend`, { expiresAt }));
+                        if (out.redeemed)
+                            console.log(`✓ invite ${id} is redeemed — its token never expires, nothing to extend`);
+                        else
+                            console.log(out.expiresAt === null
+                                ? `✓ invite ${id} never expires`
+                                : `✓ invite ${id} expires ${fmtTime(out.expiresAt)}`);
+                    });
                     return;
                 }
-                if (out.restoredProducer) {
-                    console.log(`✓ invite ${id} restored — producer '${out.restoredProducer.name}' is back`);
-                }
-                else if (out.restoredConsumer) {
-                    console.log(`✓ invite ${id} restored — consumer '${out.restoredConsumer.name}' is back`);
-                }
-                else {
-                    console.log(`✓ invite ${id} restored — the code pairs again (its original expiry still applies)`);
-                }
+                await runBatch(ids, 'restore(s)', false, async (id) => {
+                    const out = (await api('POST', `/admin/v1/invites/${id}/restore`));
+                    if (!out.restored) {
+                        console.log(`- invite ${id} was not revoked — nothing to restore`);
+                        return;
+                    }
+                    if (out.restoredProducer) {
+                        console.log(`✓ invite ${id} restored — producer '${out.restoredProducer.name}' is back`);
+                    }
+                    else if (out.restoredConsumer) {
+                        console.log(`✓ invite ${id} restored — consumer '${out.restoredConsumer.name}' is back`);
+                    }
+                    else {
+                        console.log(`✓ invite ${id} restored — the code pairs again (its original expiry still applies)`);
+                    }
+                });
                 return;
             }
             // offering: the per-alias scalpel ('block' renamed to 'revoke' — the
@@ -666,19 +774,24 @@ async function main() {
                 fail(`unknown offering action '${action}' — expected revoke or restore`);
             }
             checkFlags('admin offering', flags, []);
-            const alias = positional[2];
-            if (!alias)
+            const aliases = parseTargets(positional.slice(2));
+            if (aliases.length === 0)
                 fail(`offering ${action}: alias is required (ns/model)`);
-            if (positional[3])
-                fail(`unexpected argument '${positional[3]}' (see: aweshare hub admin offering -h)`);
             if (action === 'revoke') {
-                const out = (await api('POST', `/admin/v1/offerings/block?alias=${encodeURIComponent(alias)}`));
-                console.log(`✓ ${alias} revoked (${out.offerings} protocol row(s)) — new requests get 503 OFFERING_BLOCKED`);
-                console.log(`  undo: aweshare hub admin offering restore ${alias}`);
+                const revokedAliases = [];
+                await runBatch(aliases, 'revoke(s)', false, async (alias) => {
+                    const out = (await api('POST', `/admin/v1/offerings/block?alias=${encodeURIComponent(alias)}`));
+                    revokedAliases.push(alias);
+                    console.log(`✓ ${alias} revoked (${out.offerings} protocol row(s)) — new requests get 503 OFFERING_BLOCKED`);
+                });
+                if (revokedAliases.length > 0)
+                    console.log(`  undo: aweshare hub admin offering restore ${revokedAliases.join(' ')}`);
                 return;
             }
-            const out = (await api('POST', `/admin/v1/offerings/restore?alias=${encodeURIComponent(alias)}`));
-            console.log(`✓ ${alias} restored (${out.offerings} protocol row(s)) — requests flow again`);
+            await runBatch(aliases, 'restore(s)', false, async (alias) => {
+                const out = (await api('POST', `/admin/v1/offerings/restore?alias=${encodeURIComponent(alias)}`));
+                console.log(`✓ ${alias} restored (${out.offerings} protocol row(s)) — requests flow again`);
+            });
             return;
         }
         case 'list': {
@@ -816,13 +929,11 @@ async function main() {
         }
         case 'limits': {
             checkFlags('limits', flags, [...LIMIT_FLAGS.map(([flag]) => flag), 'clear', 'json']);
-            const name = positional[0];
-            if (!name)
+            const names = parseTargets(positional);
+            if (names.length === 0)
                 fail('consumer name is required (see: aweshare hub limits -h)');
-            if (positional[1])
-                fail(`unexpected argument '${positional[1]}' (see: aweshare hub limits -h)`);
             const api = adminApi();
-            const path = `/admin/v1/consumers/${encodeURIComponent(name)}/limits`;
+            const path = (name) => `/admin/v1/consumers/${encodeURIComponent(name)}/limits`;
             const json = flags.get('json') === 'true';
             const set = {};
             for (const [flag, key] of LIMIT_FLAGS) {
@@ -837,20 +948,141 @@ async function main() {
             if (flags.get('clear') === 'true') {
                 if (Object.keys(set).length > 0)
                     fail('--clear drops every override — drop the value flags too');
-                const out = (await api('DELETE', path));
-                console.log(json
-                    ? JSON.stringify(out, null, 2)
-                    : `✓ ${name}: overrides cleared — hub-wide defaults apply`);
+                const entries = await runBatch(names, 'clear(s)', json, async (name) => {
+                    const out = (await api('DELETE', path(name)));
+                    if (!json)
+                        console.log(`✓ ${out.name}: overrides cleared — hub-wide defaults apply`);
+                    return out;
+                });
+                if (json)
+                    printJsonBatch(entries);
                 return;
             }
             if (Object.keys(set).length > 0) {
                 // integer/precision rules live server-side; its error lists all problems
-                const out = (await api('PUT', path, set));
-                console.log(json ? JSON.stringify(out, null, 2) : `✓ ${fmtLimits(out.name, out.overrides)}`);
+                const entries = await runBatch(names, 'update(s)', json, async (name) => {
+                    const out = (await api('PUT', path(name), set));
+                    if (!json)
+                        console.log(`✓ ${fmtLimits(out.name, out.overrides)}`);
+                    return out;
+                });
+                if (json)
+                    printJsonBatch(entries);
                 return;
             }
-            const out = (await api('GET', path));
-            console.log(json ? JSON.stringify(out, null, 2) : fmtLimits(out.name, out.overrides));
+            const entries = await runBatch(names, 'lookup(s)', json, async (name) => {
+                const out = (await api('GET', path(name)));
+                if (!json)
+                    console.log(fmtLimits(out.name, out.overrides));
+                return out;
+            });
+            if (json)
+                printJsonBatch(entries);
+            return;
+        }
+        case 'backups': {
+            checkFlags('backups', flags, ['add', 'first', 'remove', 'clear', 'json']);
+            const alias = positional[0];
+            if (positional[1])
+                fail(`unexpected argument '${positional[1]}' (see: aweshare hub backups -h)`);
+            const json = flags.get('json') === 'true';
+            const add = flags.get('add');
+            const remove = flags.get('remove');
+            const clear = flags.get('clear') === 'true';
+            const mutating = add !== undefined || remove !== undefined || clear;
+            if (mutating && alias === undefined)
+                fail('which queue to modify: pass ALIAS (see: aweshare hub backups -h)');
+            if (clear && (add !== undefined || remove !== undefined))
+                fail('--clear drops the whole queue — drop --add/--remove too');
+            if (flags.get('first') === 'true' && add === undefined)
+                fail('--first only makes sense with --add');
+            let queues;
+            try {
+                queues = readBackupsFile(paths.backupsFile);
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+            if (!mutating) {
+                const print = (key, queue) => console.log(queue && queue.length > 0
+                    ? `${key} → ${queue.join(', ')}`
+                    : `${key}: no backups configured`);
+                if (!alias) {
+                    if (queues.size === 0) {
+                        console.log('no backup queues configured — create one:');
+                        console.log('  aweshare hub backups SOME/ALIAS --add OTHER/BACKUP');
+                        return;
+                    }
+                    if (json)
+                        console.log(JSON.stringify(Object.fromEntries(queues), null, 2));
+                    else
+                        for (const [key, queue] of queues)
+                            print(key, queue);
+                    return;
+                }
+                const queue = queues.get(alias);
+                if (json)
+                    console.log(JSON.stringify({ [alias]: queue ?? [] }, null, 2));
+                else
+                    print(alias, queue);
+                return;
+            }
+            // unreachable in plain control flow (mutating implies ALIAS, checked
+            // above) but needed so the compiler sees the string
+            if (alias === undefined)
+                fail('which queue to modify: pass ALIAS (see: aweshare hub backups -h)');
+            if (!isValidAlias(alias))
+                fail(`'${alias}' is not an alias (namespace/name, lowercase)`);
+            // every mutation lands in memory first and the file is written once,
+            // so a rejected flag leaves the file untouched
+            if (clear) {
+                if (!queues.delete(alias))
+                    fail(`${alias}: no queue configured (see: aweshare hub backups)`);
+            }
+            if (remove !== undefined) {
+                for (const target of splitAliases(remove)) {
+                    const queue = queues.get(alias);
+                    if (!queue?.includes(target))
+                        fail(`${alias}: '${target}' is not in its queue`);
+                    const rest = queue.filter((entry) => entry !== target);
+                    if (rest.length > 0)
+                        queues.set(alias, rest);
+                    else
+                        queues.delete(alias);
+                }
+            }
+            if (add !== undefined) {
+                const additions = splitAliases(add);
+                if (new Set(additions).size !== additions.length)
+                    fail(`--add repeats an alias: '${add}'`);
+                for (const entry of additions) {
+                    if (!isValidAlias(entry))
+                        fail(`'${entry}' is not an alias (namespace/name, lowercase)`);
+                    if (entry === alias)
+                        fail(`${alias}: it cannot be its own backup`);
+                    if (queues.get(alias)?.includes(entry))
+                        fail(`${alias}: '${entry}' is already in its queue`);
+                }
+                const queue = queues.get(alias) ?? [];
+                queues.set(alias, flags.get('first') === 'true' ? [...additions, ...queue] : [...queue, ...additions]);
+            }
+            try {
+                // revalidate the whole file the way the hub will parse it
+                parseBackups(serializeBackups(queues));
+            }
+            catch (err) {
+                fail(err instanceof Error ? err.message : String(err));
+            }
+            writeBackupsFile(paths.backupsFile, queues);
+            const queue = queues.get(alias);
+            if (json) {
+                console.log(JSON.stringify(Object.fromEntries(queues), null, 2));
+            }
+            else {
+                const shown = queue && queue.length > 0 ? queue.join(', ') : '(none — queue removed)';
+                console.log(`✓ ${alias} → ${shown}`);
+                console.log('(config.backups.toml written — the hub picks it up within ~2s)');
+            }
             return;
         }
         case 'status': {