@shardflux/cli 0.1.0

package/dist/format.js

@@ -0,0 +1,177 @@
+export function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function table(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+    const line = (cells) => cells
+        .map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i])))
+        .join('  ')
+        .trimEnd();
+    return `${[line(headers), ...rows.map(line)].join('\n')}\n`;
+}
+export function kv(pairs) {
+    const w = Math.max(...pairs.map(([k]) => k.length));
+    return `${pairs.map(([k, v]) => `${k.padEnd(w)}  ${v}`).join('\n')}\n`;
+}
+/** ISO timestamp to second precision ("2026-09-26 12:00:00Z"), "-" when absent. */
+export function time(iso) {
+    if (!iso)
+        return '-';
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    return `${d.toISOString().slice(0, 19).replace('T', ' ')}Z`;
+}
+function scalar(v) {
+    if (v === null || v === undefined)
+        return '-';
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    return JSON.stringify(v);
+}
+/** { a: 1, b: 2 } -> "a=1 b=2" */
+export function pairs(obj) {
+    if (!obj)
+        return '-';
+    const entries = Object.entries(obj).filter(([, v]) => typeof v !== 'object' || v === null);
+    return entries.length ? entries.map(([k, v]) => `${k}=${scalar(v)}`).join(' ') : '-';
+}
+export function operationSummary(op) {
+    if (!op)
+        return '-';
+    return `${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}`;
+}
+export const WORKSPACE_HEADERS = ['ID', 'KEY', 'STATE', 'DESIRED', 'TEMPLATE', 'OPERATION', 'CREATED'];
+export function workspaceRow(w) {
+    const state = w.deleted_at ? `${w.observed_state} (deleted)` : w.observed_state;
+    return [w.id, w.workspace_key, state, w.desired_state, `${w.template.slug}@${w.template.version}`, operationSummary(w.active_operation), time(w.created_at)];
+}
+export function workspaceTable(ws) {
+    return table(WORKSPACE_HEADERS, ws.map(workspaceRow));
+}
+export function isReady(w) {
+    return w.observed_state === 'running' && w.desired_state === 'running' && w.deleted_at === null;
+}
+export function workspaceDetail(w) {
+    const c = w.ceilings;
+    return kv([
+        ['id', w.id],
+        ['key', w.workspace_key],
+        ['state', `${w.observed_state} (desired ${w.desired_state})`],
+        ['ready', isReady(w) ? 'yes' : 'no'],
+        ['template', `${w.template.slug} v${w.template.version} (${w.template.version_id})`],
+        ['cell', w.cell_id ? `${w.cell_id} ${w.cell_endpoint ?? '(endpoint unresolved)'}` : '-'],
+        ['ceilings', c ? `cpu ${c.cpu_millis}m (${c.sources.cpu_millis}), memory ${c.memory_mib} MiB (${c.sources.memory_mib}), disk ${c.disk_gib} GiB (${c.sources.disk_gib})` : '-'],
+        ['grants', pairs(w.grants)],
+        ['caps', pairs(w.caps)],
+        ['operation', w.active_operation ? `${operationSummary(w.active_operation)} ${w.active_operation.id}` : '-'],
+        ['pending', w.pending_reason ?? '-'],
+        ['forked from', w.forked_from_workspace_id ?? '-'],
+        ['created', time(w.created_at)],
+        ['deleted', time(w.deleted_at)],
+    ]);
+}
+export const OPERATION_HEADERS = ['ID', 'KIND', 'STATE', 'REASON', 'CREATED', 'COMPLETED'];
+export function operationTable(ops) {
+    return table(OPERATION_HEADERS, ops.map((o) => [o.id, o.kind, o.state, o.state_reason ?? '-', time(o.created_at), time(o.completed_at)]));
+}
+export function operationDetail(op) {
+    const err = op.error;
+    return kv([
+        ['id', op.id],
+        ['kind', op.kind],
+        ['state', op.state],
+        ['reason', op.state_reason ?? '-'],
+        ['workspace', op.workspace_id ?? '-'],
+        ['created', time(op.created_at)],
+        ['updated', time(op.updated_at)],
+        ['completed', time(op.completed_at)],
+        ['error', err ? `${scalar(err.code)}${err.message ? `: ${scalar(err.message)}` : ''}` : '-'],
+    ]);
+}
+export function sessionTable(sessions) {
+    return table(['ID', 'LABEL', 'PRINCIPAL', 'TOKENS', 'LAST TOKEN', 'REVOKED'], sessions.map((s) => [s.id, s.agent_label, `${s.principal_type}:${s.principal_id}`, String(s.tokens_issued), time(s.last_token_issued_at), time(s.revoked_at)]));
+}
+export function fileTable(list) {
+    return table(['TYPE', 'SIZE', 'MODIFIED', 'NAME'], list.entries.map((e) => [e.type, String(e.size), time(e.modified_at), e.name]));
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** A table of the listed columns that at least one row actually has. */
+function objectTable(rows, columns) {
+    if (!Array.isArray(rows) || rows.length === 0)
+        return '';
+    const objs = rows.filter(isObject);
+    const cols = columns.filter(([k]) => objs.some((o) => k in o));
+    return table(cols.map(([, h]) => h), objs.map((o) => cols.map(([k]) => (k === 'percent_used' && typeof o[k] === 'number' ? `${o[k]}%` : scalar(o[k])))));
+}
+const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'meters', 'allowances', 'exhausted', 'alert_thresholds']);
+/**
+ * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
+ * freshness, then meters and allowances as tables. Columns absent from the response are omitted.
+ */
+export function usageText(summary) {
+    if (!isObject(summary))
+        return json(summary);
+    const s = summary;
+    const head = [];
+    if (isObject(s.plan))
+        head.push(['plan', `${scalar(s.plan.plan_key)}${s.plan.catalog_version !== undefined ? ` (catalog ${scalar(s.plan.catalog_version)})` : ''}`]);
+    if (isObject(s.period))
+        head.push(['period', `${time(scalar(s.period.start))} .. ${time(scalar(s.period.end))}`]);
+    const m = isObject(s.measurement) ? s.measurement : s;
+    if (m.measured_through !== undefined)
+        head.push(['measured through', time(m.measured_through)]);
+    if (isObject(s.measurement) && s.measurement.estimate_status !== undefined)
+        head.push(['estimate', scalar(s.measurement.estimate_status)]);
+    if (typeof s.allowance_exhausted === 'boolean')
+        head.push(['allowance exhausted', s.allowance_exhausted ? 'yes (new opens/resumes are refused)' : 'no']);
+    for (const [k, v] of Object.entries(s))
+        if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
+            head.push([k.replace(/_/g, ' '), scalar(v)]);
+    let out = head.length ? kv(head) : '';
+    const meters = objectTable(s.meters, [
+        ['meter', 'METER'],
+        ['unit', 'UNIT'],
+        ['raw_quantity', 'RAW'],
+        ['billable_quantity', 'BILLABLE'],
+        ['included_quantity', 'INCLUDED'],
+        ['percent_used', 'USED'],
+        ['cap_state', 'CAP'],
+    ]);
+    if (meters)
+        out += `\n${meters}`;
+    const allowances = objectTable(s.allowances, [
+        ['key', 'ALLOWANCE'],
+        ['unit', 'UNIT'],
+        ['included', 'INCLUDED'],
+        ['used', 'USED'],
+        ['remaining', 'REMAINING'],
+        ['percent_used', 'USED %'],
+        ['enforcement', 'ENFORCEMENT'],
+        ['cap_state', 'CAP'],
+    ]);
+    if (allowances)
+        out += `\n${allowances}`;
+    return out || json(summary);
+}
+/** One stderr line: `error: <message> [code=... status=... request_id=...]` plus a hint when there is one. */
+export function errorText(e, hint) {
+    const meta = [`code=${e.code}`];
+    if (e.status !== undefined)
+        meta.push(`status=${e.status}`);
+    if (e.request_id)
+        meta.push(`request_id=${e.request_id}`);
+    if (e.operation_id)
+        meta.push(`operation_id=${e.operation_id}`);
+    if (e.source === 'cell')
+        meta.push('source=cell');
+    const reason = e.details && typeof e.details.reason === 'string' ? ` (${e.details.reason})` : '';
+    const issues = Array.isArray(e.details?.issues)
+        ? e.details.issues.filter(isObject).map((i) => `  ${scalar(i.path)}: ${scalar(i.message)}\n`).join('')
+        : '';
+    return `error: ${e.message}${reason} [${meta.join(' ')}]\n${issues}${hint ? `hint: ${hint}\n` : ''}`;
+}

package/dist/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
+ * every request (API and cell gateway).
+ *
+ * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
+ * sent on a reused keep-alive connection until an unrelated timer fires (up to
+ * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
+ * with bare fetch against both node:http and Fastify servers; Node 22 (undici
+ * 6.28) and `Connection: close` do not stall. A fresh connection per request
+ * costs one TCP/TLS handshake, which is negligible for these call rates.
+ * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ */
+export declare function makeFetch(env: Record<string, string | undefined>, base?: typeof fetch): typeof fetch;

package/dist/http.js

@@ -0,0 +1,21 @@
+/**
+ * The fetch given to the SDK: the runtime's fetch with `Connection: close` on
+ * every request (API and cell gateway).
+ *
+ * Why: Node 26.7's bundled undici (8.9.0) intermittently stalls a request
+ * sent on a reused keep-alive connection until an unrelated timer fires (up to
+ * ~30 s, the SDK's request timeout, after which the SDK retries). Reproduced
+ * with bare fetch against both node:http and Fastify servers; Node 22 (undici
+ * 6.28) and `Connection: close` do not stall. A fresh connection per request
+ * costs one TCP/TLS handshake, which is negligible for these call rates.
+ * Set SHARDFLUX_HTTP_KEEPALIVE=1 to use the runtime's keep-alive pooling.
+ */
+export function makeFetch(env, base = fetch) {
+    if (env.SHARDFLUX_HTTP_KEEPALIVE === '1')
+        return base;
+    return (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('connection', 'close');
+        return base(input, { ...init, headers });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @shardflux/cli — `shard`, the Shardflux command line on @shardflux/sdk.
+ * The executable is src/bin.ts; `run()` drives the same code in-process.
+ */
+export { run, abortableSleep } from './main.js';
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from './args.js';
+export type { CommandSpec, OptionSpec, Parsed, PositionalSpec, Values } from './args.js';
+export { HANDLERS, execExitCode, resolveWorkspace } from './commands.js';
+export type { Ctx, Handler, Io, Writer } from './commands.js';
+export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from './errors.js';
+export type { ErrorInfo } from './errors.js';
+export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @shardflux/cli — `shard`, the Shardflux command line on @shardflux/sdk.
+ * The executable is src/bin.ts; `run()` drives the same code in-process.
+ */
+export { run, abortableSleep } from "./main.js";
+export { COMMANDS, GLOBAL_OPTIONS, CLI_VERSION, commandHelp, findCommand, normalizeWords, parseCommandLine, parseDuration, parseEnvPairs, parsePositiveInt, resolveApiUrl, topHelp } from "./args.js";
+export { HANDLERS, execExitCode, resolveWorkspace } from "./commands.js";
+export { EXIT, AuthConfigError, InterruptedError, NotFoundError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
+export { errorText, json, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";

package/dist/main.d.ts

@@ -0,0 +1,6 @@
+import type { Io } from './commands.js';
+/** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
+export declare function abortableSleep(signal: AbortSignal): (ms: number) => Promise<void>;
+export declare function run(argv: readonly string[], io: Io, opts?: {
+    signal?: AbortSignal;
+}): Promise<number>;

package/dist/main.js

@@ -0,0 +1,120 @@
+/**
+ * `shard` entry: parse, build the SDK client from the environment, run the
+ * command, report errors (stderr, with the API error code and request id) and
+ * return the exit code. In-process and side-effect free apart from `io`, so
+ * the whole CLI can be driven by tests; bin.ts wires it to the real process.
+ */
+import { SDK_VERSION, Shardflux } from '@shardflux/sdk';
+import { CLI_VERSION, parseCommandLine, resolveApiUrl } from "./args.js";
+import { HANDLERS } from "./commands.js";
+import { AuthConfigError, EXIT, InterruptedError, UsageError, describeError, exitCodeFor, redact } from "./errors.js";
+import { errorText, json } from "./format.js";
+import { makeFetch } from "./http.js";
+const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
+// Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
+const isLabel = (s) => s.length >= 1 && s.length <= 100 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+/** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
+export function abortableSleep(signal) {
+    return (ms) => new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener('abort', done, { once: true });
+    });
+}
+function hintFor(info) {
+    if (info.code === 'timeout' && info.operation_id)
+        return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
+    if (info.code === 'interrupted' && info.operation_id)
+        return `keep waiting with: shard operations wait ${info.operation_id}`;
+    if (info.code === 'unauthenticated' && info.status === undefined)
+        return 'export SHARDFLUX_API_KEY=<project API key> (create one in the console under Project > API keys)';
+    if (info.code === 'usage')
+        return 'run "shard --help" or "shard <command> --help"';
+    if (info.source === 'cell' && info.code === 'workspace_not_running')
+        return 'open or resume the workspace first: shard workspaces open <key> --template <slug>';
+    return undefined;
+}
+export async function run(argv, io, opts = {}) {
+    const signal = opts.signal ?? new AbortController().signal;
+    const rawKey = io.env.SHARDFLUX_API_KEY;
+    const wantsJson = argv.slice(0, argv.includes('--') ? argv.indexOf('--') : argv.length).includes('--json');
+    const report = (err) => {
+        const code = exitCodeFor(err, signal.aborted);
+        const info = describeError(err);
+        if (code === EXIT.interrupted && info.code !== 'interrupted') {
+            info.code = 'interrupted';
+            info.message = 'Interrupted.';
+        }
+        info.message = redact(info.message, rawKey);
+        io.stderr.write(redact(wantsJson ? json({ error: info }) : errorText(info, hintFor(info)), rawKey));
+        return code;
+    };
+    let parsed;
+    try {
+        parsed = parseCommandLine(argv);
+    }
+    catch (err) {
+        return report(err);
+    }
+    if (parsed.kind === 'help') {
+        io.stdout.write(parsed.text);
+        return EXIT.ok;
+    }
+    if (parsed.kind === 'version') {
+        io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
+        return EXIT.ok;
+    }
+    let ctx;
+    try {
+        const apiUrl = resolveApiUrl(parsed.global.apiUrl, io.env.SHARDFLUX_API_URL);
+        const agentLabel = parsed.global.agentLabel ?? io.env.SHARDFLUX_AGENT_LABEL ?? 'cli';
+        if (!isLabel(agentLabel))
+            throw new UsageError('--agent-label must be 1-100 printable characters');
+        let cloud;
+        ctx = {
+            io,
+            json: parsed.global.json,
+            apiUrl,
+            agentLabel,
+            signal,
+            cloud() {
+                if (cloud)
+                    return cloud;
+                const key = rawKey?.trim();
+                if (!key)
+                    throw new AuthConfigError('SHARDFLUX_API_KEY is not set.');
+                if (!KEY_SHAPE.test(key))
+                    throw new AuthConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>).');
+                cloud = new Shardflux({ apiKey: key, baseUrl: apiUrl, userAgent: `shard-cli/${CLI_VERSION} shardflux-sdk-ts/${SDK_VERSION}`, fetch: makeFetch(io.env), sleep: abortableSleep(signal) });
+                return cloud;
+            },
+        };
+    }
+    catch (err) {
+        return report(err);
+    }
+    const handler = HANDLERS[parsed.command.path.join(' ')];
+    if (!handler)
+        return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
+    const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
+    // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
+    const interrupted = new Promise((resolve) => {
+        const onAbort = () => setTimeout(() => resolve({ interrupted: true }), 4_000).unref();
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    });
+    const outcome = await Promise.race([running, interrupted]);
+    if ('interrupted' in outcome)
+        return report(new InterruptedError('Interrupted.'));
+    if ('err' in outcome)
+        return report(outcome.err);
+    return outcome.code;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@shardflux/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "shard: the Shardflux command line. Open, run commands in, move files to, suspend, resume and fork persistent agent workspaces.",
+  "license": "Apache-2.0",
+  "homepage": "https://shardflux.dev",
+  "keywords": [
+    "shardflux",
+    "cli",
+    "shard",
+    "agents",
+    "ai-agents",
+    "sandbox",
+    "workspace",
+    "microvm"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "shard": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./bin": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@shardflux/sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "24.13.6",
+    "eslint": "10.11.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.70.1"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "node --test test/*.test.ts"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}