insta 0.0.27 → 0.0.29

package/dist/api.js

@@ -11,6 +11,13 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+// Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
+export function storeApiKeyCredential(cfg, token, user) {
+    cfg.accessToken = token;
+    delete cfg.refreshToken;
+    if (user)
+        cfg.user = user;
+}
 export class ApiClient {
     cfg;
     constructor(cfg) {
@@ -27,6 +34,10 @@ export class ApiClient {
         if (user)
             this.cfg.user = user;
     }
+    // Adopt a durable insta_ key as the credential (non-interactive `login --api-key`).
+    setApiKey(token, user) {
+        storeApiKeyCredential(this.cfg, token, user);
+    }
     clearSession() {
         delete this.cfg.accessToken;
         delete this.cfg.refreshToken;

package/dist/commands/auth.js

@@ -17,6 +17,13 @@ function targetApiUrl(opts) {
     return ENVS[want].api;
 }
 export async function login(opts) {
+    // Login modes are exclusive — pick one. Check presence (not truthiness) so an explicit
+    // empty --api-key= is rejected by validation rather than silently falling through.
+    if (opts.apiKey !== undefined) {
+        if (opts.device || opts.oauth || opts.email)
+            die('choose one login mode: --api-key, --device, --oauth, or --email');
+        return loginApiKey(opts.apiKey, opts);
+    }
     if (opts.device)
         return loginDevice(opts);
     if (opts.oauth)
@@ -65,6 +72,36 @@ export async function loginDevice(opts) {
     await api.persist();
     info(`logged in as ${me.user.email ?? me.user.id} @ ${api.apiUrl}`);
 }
+// Non-interactive login with a durable insta_ key (minted via POST /tokens): store it and confirm against /me. No browser, no polling.
+export async function loginApiKey(key, opts) {
+    const api = await ApiClient.load();
+    const target = targetApiUrl(opts);
+    if (target)
+        api.setApiUrl(target);
+    const user = await applyApiKeyLogin(api, key);
+    await api.persist();
+    info(`logged in as ${user.email ?? user.id} @ ${api.apiUrl}`);
+}
+// Verify an insta_ key and store it: set it first so the /me probe is authed with the key itself, then re-store with the resolved user (401 → bad/revoked).
+export async function applyApiKeyLogin(client, key) {
+    key = key.trim(); // tolerate a trailing newline / stray whitespace from `--api-key "$(cat token)"`
+    if (!key.startsWith('insta_'))
+        throw new Error('--api-key expects an insta_ token (mint one with POST /tokens)');
+    client.setApiKey(key);
+    let me;
+    try {
+        me = await client.request('GET', '/me');
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 401)
+            throw new Error('that insta_ API key was rejected (invalid or revoked) — check it or mint a new one');
+        throw e;
+    }
+    if (!me?.user)
+        throw new Error('unexpected response while verifying the API key');
+    client.setApiKey(key, me.user);
+    return me.user;
+}
 const sleepSeconds = (s) => new Promise((r) => setTimeout(r, s * 1000));
 // Drives the device grant against the platform's Better Auth mount (/api/auth/device*) and
 // returns the approved session token. Injectable poster + wait keep this testable without a

package/dist/commands/compute.js

@@ -1,6 +1,6 @@
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson, handleApproval } from '../util.js';
-import { resolveComputeServiceId, q } from './services.js';
+import { resolveComputeServiceId, q, parseVolumeGib } from './services.js';
 // Attach a developer-owned custom domain to a branch's compute service. Fly issues the cert + routes
 // it; the platform returns the DNS records to set in your OWN zone.
 export async function setDomain(host, opts) {
@@ -116,6 +116,46 @@ export function parseCpu(raw) {
         throw new Error(`invalid cpu: ${raw} (provider sizes: ${CPU_SIZES.join(', ')})`);
     return n;
 }
+// ---- volume (the persistent /data disk; attach is create-time only) ----
+// Render the volume read. Pure, exported for tests (mirrors serviceListLine). Every plan may view;
+// only growth is paid — that gate is the backend's to enforce, so nothing here pre-blocks.
+export function volumeLines(name, volume, cap) {
+    if (!volume)
+        return [
+            `compute ${name}: no volume attached (attach is create-time only: \`insta services add compute <name> --volume <gi>\`)`,
+        ];
+    return [
+        `compute ${name}: volume ${volume.sizeGib}Gi at ${volume.mountPath}  (plan max ${cap.volumeGib}Gi)`,
+        '  billing is actual data stored — the size is a cap, not a price; grow with --size (grow-only)',
+    ];
+}
+// Show or grow a compute service's /data volume. No --size: a safe read (size + mount path + the
+// plan cap). --size: grow via PUT .../volume — paid and grow-only, but both gates belong to the
+// backend, whose 403/400 messages carry the upgrade hints and must reach the user verbatim (the
+// guard prints ApiError messages as-is).
+export async function computeVolume(serviceName, opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
+    const id = resolveComputeServiceId(services, serviceName);
+    if (!opts.size) {
+        const r = await api.request('GET', `/projects/${p.projectId}/services/${id}/volume`);
+        if (opts.json)
+            return printJson(r);
+        for (const line of volumeLines(serviceName ?? id, r.volume, r.cap))
+            info(line);
+        return;
+    }
+    const sizeGib = parseVolumeGib(opts.size);
+    const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${id}/volume`, { sizeGib });
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const v = res.body.volume;
+    info(`compute ${res.body.service?.name ?? serviceName ?? id}: volume grown to ${v.sizeGib}Gi at ${v.mountPath}  (plan max ${res.body.cap.volumeGib}Gi)`);
+}
 // Show or set a compute service's ceiling. With no --memory it PRINTS the current limits and the
 // plan cap (so `insta compute limits` is a safe read), which is also what a UI renders as a slider
 // with its plan-limit marker.

package/dist/commands/db.js

@@ -1,5 +1,6 @@
 import { ApiClient, ApiError, requireProject } from '../api.js';
 import { info, printJson, handleApproval } from '../util.js';
+import { parseVolumeGib } from './services.js';
 // Toggle a postgres service between scale-to-zero (the default: instance suspends when idle,
 // cold-starts on the next connection) and always-on (instance stays warm; idle RAM bills at
 // actual usage). Thin wrapper over PATCH /database/settings {scaleToZero} — insta-db-backed
@@ -116,4 +117,120 @@ export async function dbLimits(opts) {
     const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (opts.memory ?? 'unchanged');
     info(`postgres ${opts.group ?? 'default'}: ceiling set to ${cpu} / ${mem}`);
 }
+// Render the instance's volume from a database/instance read. Pure, exported for tests. Reads the
+// CANONICAL volume* names only — storageSize/storageGiB are deprecated aliases the platform drops
+// next release, so depending on them here would be a scheduled breakage.
+// Bytes → human units, one decimal above KiB. Local because the metrics payload is the only
+// bytes-denominated read in this file (fmtMib serves the MiB-denominated resize path).
+export function fmtBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KiB', 'MiB', 'GiB', 'TiB'];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(1)} ${units[i]}`;
+}
+// Human-readable stats lines from GET /database/metrics. Pure seam for tests. "—" for anything
+// unmeasured (old platform, suspended instance, no cache traffic yet) — never a fake 0: the
+// platform omits cacheHitRatio and sends max 0 in exactly those cases.
+export function dbStatsLines(group, body) {
+    const c = body?.connections ?? {};
+    const max = typeof c.max === 'number' && c.max > 0 ? c.max : null;
+    const total = typeof c.total === 'number' ? c.total : null;
+    const conn = total === null ? '—'
+        : (max === null ? String(total) : `${total} / ${max}`)
+            + (typeof c.active === 'number' && max !== null ? ` (${c.active} active)` : '');
+    const ratio = body?.cacheHitRatio;
+    const cache = typeof ratio === 'number' ? `${(ratio * 100).toFixed(1)}%` : '—';
+    const size = typeof body?.dbSizeBytes === 'number' ? fmtBytes(body.dbSizeBytes) : '—';
+    const bits = [
+        typeof body?.state === 'string' ? body.state : null,
+        typeof body?.serverVersion === 'string' && body.serverVersion ? `PG ${body.serverVersion}` : null,
+    ].filter(Boolean);
+    const state = bits.length ? ` (${bits.join(' · ')})` : '';
+    return [
+        `postgres ${group}${state}`,
+        `  connections  ${conn}`,
+        `  cache hit    ${cache}`,
+        `  size         ${size}`,
+    ];
+}
+// Point-in-time stats snapshot for a postgres service: connections vs the server's ceiling, cache
+// hit rate, database size. Read-only. insta-db-backed: a suspended instance answers from the
+// provider's control plane (shown as "(suspended)" with structural zeros), never dialed.
+// Neon-backed: the platform reads over a direct SQL connection, so a one-shot call may wake a
+// suspended endpoint — acceptable for an explicit command, which is why nothing here polls.
+export async function dbStats(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const qs = new URLSearchParams();
+    const branch = opts.branch ?? p.branch;
+    if (branch)
+        qs.set('branch', branch);
+    if (opts.group)
+        qs.set('group', opts.group);
+    const res = await api.rawRequest('GET', `/projects/${p.projectId}/database/metrics${qs.toString() ? `?${qs}` : ''}`);
+    if (opts.json)
+        return printJson(res.body);
+    for (const line of dbStatsLines(opts.group ?? 'default', res.body))
+        info(line);
+}
+export function dbVolumeLines(group, body) {
+    const gib = typeof body?.volumeGib === 'number' ? `${body.volumeGib}Gi` : (typeof body?.volumeSize === 'string' ? body.volumeSize : undefined);
+    if (gib === undefined)
+        return [`postgres ${group}: provider reported no volume size`];
+    const cap = body?.cap?.volumeGib;
+    const region = typeof body?.region === 'string' ? `  ${body.region}` : '';
+    return [
+        `postgres ${group}: volume ${gib}${typeof cap === 'number' ? `  (plan max ${cap}Gi)` : ''}${region}`,
+        '  billing is actual data stored — the size is a cap, not a price; grow with --size (grow-only)',
+    ];
+}
+// Show or grow a postgres service's provisioned volume (block disk; insta-db-backed only). Viewing
+// is available on every plan; growth is paid and grow-only — both gates are the backend's to
+// enforce, so nothing here pre-blocks: its 403/400 messages carry the upgrade hints and are wrapped
+// with context but kept verbatim.
+export async function dbVolume(opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const qs = new URLSearchParams();
+    const branch = opts.branch ?? p.branch;
+    if (branch)
+        qs.set('branch', branch);
+    if (opts.group)
+        qs.set('group', opts.group);
+    const suffix = qs.toString() ? `?${qs}` : '';
+    if (!opts.size) {
+        const read = await fetchDbInstance(api, p.projectId, suffix);
+        if (read.kind === 'no-instance') {
+            info(`postgres ${opts.group ?? 'default'}: no manageable instance (Neon-backed services manage their own storage)`);
+            return;
+        }
+        if (opts.json)
+            return printJson(read.body);
+        for (const line of dbVolumeLines(opts.group ?? 'default', read.body))
+            info(line);
+        return;
+    }
+    const sizeGib = parseVolumeGib(opts.size);
+    let res;
+    try {
+        res = await api.rawRequest('PATCH', `/projects/${p.projectId}/database/settings${suffix}`, { volumeSize: `${sizeGib}Gi` });
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw new Error(`growing the volume failed (${e.status}): ${e.message}`);
+        throw e;
+    }
+    if (handleApproval(res))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const vg = res.body?.volumeGib;
+    info(`postgres ${opts.group ?? 'default'}: volume ${typeof vg === 'number' ? `grown to ${vg}Gi` : `set to ${sizeGib}Gi`}`);
+}
 //# sourceMappingURL=db.js.map

package/dist/commands/metrics.js

@@ -8,6 +8,58 @@ function qs(params) {
     const s = u.toString();
     return s ? `?${s}` : '';
 }
+// One printed series line. Pure seam so the formatting is testable without a backend.
+//
+// Byte-rate series (compute's egress/ingress) arrive as raw bytes per second, which is unreadable at
+// real traffic volumes — 20480031 bytes/s is 20 MB/s. Percent and vCPU units are already
+// human-sized, so only bytes and byte rates get scaled.
+export function metricLine(s) {
+    const last = s.points?.[s.points.length - 1];
+    const value = last ? formatMetricValue(last[1], s.unit) : 'n/a';
+    const unit = s.unit && !isScaled(s.unit) ? ` (${s.unit})` : '';
+    return `${s.name}${unit}: ${value}  [${s.points?.length ?? 0} points]`;
+}
+// The platform's unit strings are the contract here (`bytes` for memory/storage, `bytes/s` for
+// egress/ingress — src/adapters/fly.ts and insta-db.ts). Matching them loosely is deliberate: an
+// unrecognised unit fails SILENTLY back to the raw 8-digit number this scaling exists to fix, so a
+// casing or spacing change on the platform side must not be enough to regress it.
+function scaleOf(unit) {
+    const u = unit?.trim().toLowerCase();
+    if (u === 'bytes' || u === 'byte' || u === 'b')
+        return 'bytes';
+    if (u === 'bytes/s' || u === 'byte/s' || u === 'b/s' || u === 'bytes/sec')
+        return 'bytes/s';
+    return undefined;
+}
+function isScaled(unit) {
+    return scaleOf(unit) !== undefined;
+}
+function formatMetricValue(v, unit) {
+    if (!Number.isFinite(v))
+        return 'n/a';
+    const scale = scaleOf(unit);
+    // Traffic scales by 1000 because egress is BILLED per decimal GB (`bytes / 1e9`, platform
+    // src/adapters/fly.ts) — a 1024-based "GB/s" would sit ~7% off the invoice. Memory and storage
+    // stay binary: those ceilings are provisioned in GiB. Same split as the console.
+    if (scale === 'bytes')
+        return humanBytes(v, 1024);
+    if (scale === 'bytes/s')
+        return `${humanBytes(v, 1000)}/s`;
+    return String(v);
+}
+function humanBytes(v, base) {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = v;
+    let i = 0;
+    while (Math.abs(value) >= base && i < units.length - 1) {
+        value /= base;
+        i += 1;
+    }
+    // Sub-KB values keep their integer form (`512 B`, not `512.0 B`), but a RATE is fractional —
+    // PromQL rate() of a byte counter yields things like 342.857142, which must not print in full.
+    const shown = i === 0 && Number.isInteger(value) ? String(value) : value.toFixed(1);
+    return `${shown} ${units[i]}`;
+}
 // insta metrics <db|compute> [group]
 export async function metrics(component, group, opts) {
     const api = await ApiClient.load();
@@ -19,10 +71,8 @@ export async function metrics(component, group, opts) {
         info(`note: ${res.note}`);
     if (!res.series?.length)
         return info('(no series)');
-    for (const s of res.series) {
-        const last = s.points?.[s.points.length - 1];
-        info(`${s.name}${s.unit ? ` (${s.unit})` : ''}: ${last ? last[1] : 'n/a'}  [${s.points?.length ?? 0} points]`);
-    }
+    for (const s of res.series)
+        info(metricLine(s));
 }
 // Customer-facing name for each internal billing dimension (the platform stores RAM as `ram`).
 const DIMENSION_LABEL = { ram: 'memory' };

package/dist/commands/services.js

@@ -23,6 +23,19 @@ export function parseCount(raw) {
         throw new Error(`count must be a positive integer, got: ${raw}`);
     return n;
 }
+// Parse a volume size in whole Gi: "10" or "10Gi" (suffix case-insensitive — unlike the db
+// quantity strings this is not a provider pass-through; the wire value is an integer). Volumes
+// are provisioned block disks, so fractional and Mi values are rejected locally with an example
+// rather than travelling to the server as junk (the parseCpu lesson: NaN serializes to null).
+export function parseVolumeGib(raw) {
+    const m = /^\s*(\d+)\s*(gi|gib|g)?\s*$/i.exec(raw);
+    if (!m)
+        throw new Error(`invalid volume size: ${raw} (whole Gi — try 1 or 10)`);
+    const n = Number(m[1]);
+    if (n < 1)
+        throw new Error(`invalid volume size: ${raw} (whole Gi — try 1 or 10)`);
+    return n;
+}
 // Resolve a service id from a `services list` result by (type, name).
 export function resolveServiceId(services, type, name) {
     const svc = services.find((s) => s.type === type && s.name === name);
@@ -54,6 +67,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: Number(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
         ...(opts.alwaysOn ? { alwaysOn: true } : {}),
+        ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
     };
 }
 export async function servicesAdd(type, name, opts = {}) {
@@ -68,6 +82,11 @@ export async function servicesAdd(type, name, opts = {}) {
         throw new Error('--port is only valid for compute services');
     if (opts.alwaysOn && type !== 'compute')
         throw new Error('--always-on is only valid for compute services (for postgres, use `insta db always-on on` after creation)');
+    if (opts.volume !== undefined) {
+        if (type !== 'compute')
+            throw new Error('--volume is only valid for compute services (postgres has one by default — grow it with `insta db volume --size`)');
+        parseVolumeGib(opts.volume); // junk fails here, before any config/network access
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
@@ -77,14 +96,15 @@ export async function servicesAdd(type, name, opts = {}) {
     const svc = res.body.service;
     const access = svc.type === 'storage' ? `  [${svc.public ? 'public' : 'private'}]` : '';
     const img = svc.image ? `  running ${svc.image}${svc.port ? `:${svc.port}` : ''}` : '';
-    info(`added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${svc.domain ? ` — ${svc.domain}` : ''}`);
+    const vol = svc.volume_gib ? `  vol ${svc.volume_gib}Gi at /data` : '';
+    info(`added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${svc.domain ? ` — ${svc.domain}` : ''}`);
     renderNextActions(res.body.nextActions);
 }
 // Render one `services list` row. Pure, so it's unit-tested without a network mock (mirrors
 // billingLines in billing.ts). Compute rows show the running image when the platform reports one.
 export function serviceListLine(s) {
     const extra = s.type === 'compute'
-        ? `  x${s.machine_count}${s.image ? `  running ${s.image}${s.port ? `:${s.port}` : ''}` : ''}`
+        ? `  x${s.machine_count}${s.volume_gib ? `  vol ${s.volume_gib}Gi` : ''}${s.image ? `  running ${s.image}${s.port ? `:${s.port}` : ''}` : ''}`
         : s.type === 'storage' ? `  ${s.public ? 'public' : 'private'}` : '';
     return `${s.type}/${s.name}  [${s.status}]${extra}${s.domain ? `  ${s.domain}` : ''}  ${s.id}`;
 }

package/dist/index.js

@@ -54,11 +54,12 @@ function resolveVersion() {
 }
 program.name('insta').description('InstaCloud CLI — manage projects, branches, secrets, deploys').version(resolveVersion());
 // ---- auth ----
-program.command('login').description('Log in with email + password, --oauth <github|google> (browser), or --device (headless)')
+program.command('login').description('Log in with email + password, --oauth <github|google> (browser), --device (headless), or --api-key <insta_…> (headless, durable token)')
     .option('--email <email>', 'account email')
     .option('--password <password>', 'account password (else $INSTA_PASSWORD or prompt)')
     .option('--oauth <provider>', 'browser OAuth login: github | google')
     .option('--device', 'device-code login: approve from a browser on any other machine (VMs, SSH, CI)')
+    .option('--api-key <key>', 'non-interactive login with a durable insta_ API token (headless agents / CI)')
     .option('--api-url <url>', 'control-plane API base URL')
     .option('--env <name>', `deployment environment: ${ENV_NAMES.join(' | ')}`)
     .action(guard((o) => auth.login(o)));
@@ -114,6 +115,7 @@ svc.command('add <type> <name>').description('Provision a service on demand (ass
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080)')
     .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way)')
+    .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (create-time only; any plan may attach at the default 1; larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .action(guard((type, name, o) => services.servicesAdd(type, name, o)));
 svc.command('list').option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((o) => services.servicesList(o)));
@@ -169,15 +171,25 @@ compute.command('limits [service]').description("Show or set a compute service's
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
 compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
+compute.command('volume [service]').description("Show or grow a compute service's persistent /data volume. No --size: print size, mount path, and the plan cap (any plan). --size grows it (paid plans; grow-only — a provisioned disk cannot shrink). Attach is create-time only: `insta services add compute <name> --volume <gi>`. Billing is actual data stored — the size is a cap, not a price")
+    .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));
 // ---- db (postgres service controls) ----
-const db = program.command('db').description('Postgres service controls (limits / always-on / scale-to-zero)');
+const db = program.command('db').description('Postgres service controls (limits / volume / always-on / scale-to-zero)');
 db.command('limits').description("Show or set a postgres service's resource ceiling (paid plans; insta-db-backed only). Moves both directions")
     .option('--cpu <n>', "vCPU ceiling, e.g. 2 or 2500m").option('--memory <size>', "memory ceiling, e.g. 4Gi")
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbLimits(o)));
+db.command('stats').description("Postgres stats snapshot: connections vs the server's max (active count), cache hit rate, database size. insta-db-backed services answer without waking a suspended instance")
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbStats(o)));
 db.command('always-on <mode>').description('Set a postgres service always-on (mode: on|off). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((mode, o) => dbCmd.dbAlwaysOn(mode, o)));
+db.command('volume').description("Show or grow a postgres service's provisioned volume (block disk; insta-db-backed only). No --size: print size and the plan cap (any plan). --size grows it (paid plans; grow-only — a provisioned disk cannot shrink). Billing is actual data stored — the size is a cap, not a price")
+    .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
+    .action(guard((o) => dbCmd.dbVolume(o)));
 // ---- manifest ----
 program.command('manifest').description('Print an agent-legible view of the project environments').option('--json').action(guard((o) => manifest(o)));
 // ---- regions ----

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [