@buildinternet/uploads 0.8.0 → 0.10.0

package/dist/cli-help.js

@@ -0,0 +1,176 @@
+import { DEFAULT_TAGLINE, formatAuthBanner, formatBrandHeader, formatUpdateBanner, } from "./cli-brand.js";
+import { ROOT_COMMANDS } from "./cli-catalog.js";
+import { colorEnabled, createStyle, padCmd } from "./cli-style.js";
+import { packageVersion } from "./package-version.js";
+const CMD_WIDTH = 22;
+function toRow(c) {
+    return [c.usage ?? c.name, c.summary];
+}
+/** Preferred order for the short essentials help (subset of ROOT_COMMANDS). */
+const ESSENTIAL_ORDER = [
+    "put",
+    "attach",
+    "login",
+    "whoami",
+    "list",
+    "delete",
+    "doctor",
+    "install",
+];
+/** Day-to-day commands shown on bare `uploads` / `uploads help`. */
+const ESSENTIALS = ESSENTIAL_ORDER.map((name) => {
+    const cmd = ROOT_COMMANDS.find((c) => c.name === name);
+    if (!cmd)
+        throw new Error(`cli-catalog missing essential command: ${name}`);
+    return toRow(cmd);
+});
+/** Full catalog (same surface as before, still discoverable via help --all). */
+const ALL_COMMANDS = ROOT_COMMANDS.map(toRow);
+function rows(style, items) {
+    return items
+        .map(([name, desc]) => `  ${padCmd(name, CMD_WIDTH, style)}${style.body(desc)}`)
+        .join("\n");
+}
+function section(style, title) {
+    return style.heading(title);
+}
+function header(style, opts) {
+    const version = opts.version ?? packageVersion();
+    const brandMark = opts.brandMark !== false;
+    const parts = [];
+    // Auth first — loud and above everything when there's no token yet.
+    if (opts.needsAuth) {
+        parts.push(formatAuthBanner({ color: style.enabled }));
+    }
+    // Half-block mark when color is on. Plain three-line title otherwise so
+    // piped/agent output stays compact and greppable.
+    if (!brandMark || !style.enabled) {
+        parts.push(`${style.title("uploads.sh")}\n` +
+            `${style.muted(DEFAULT_TAGLINE)}\n` +
+            `${style.muted(`v${version}`)}\n`);
+    }
+    else {
+        parts.push(formatBrandHeader({
+            color: true,
+            label: "uploads.sh",
+            tagline: DEFAULT_TAGLINE,
+            version,
+        }));
+    }
+    if (opts.latestVersion && opts.latestVersion !== version) {
+        parts.push(formatUpdateBanner({
+            current: version,
+            latest: opts.latestVersion,
+            color: style.enabled,
+        }));
+    }
+    return parts.join("");
+}
+function essentialsBody(style, opts) {
+    return `${header(style, opts)}
+${section(style, "Usage:")}
+  uploads [globals] <command> [args]
+
+${section(style, "Essentials:")}
+${rows(style, ESSENTIALS)}
+
+${section(style, "More help:")}
+  ${padCmd("uploads help --all", CMD_WIDTH, style)}${style.body("Full command list, globals, and config")}
+  ${padCmd("uploads <cmd> --help", CMD_WIDTH, style)}${style.body("Per-command options and examples")}
+
+${section(style, "Globals (before command):")}
+  ${style.muted("--api-url, --token, --workspace/-w, --env-file, --json, --quiet, --version/-V")}
+
+${section(style, "Examples:")}
+  ${style.command("uploads login")}
+  ${style.command("uploads whoami")}
+  ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
+  ${style.command("uploads put")} ./after.png --pr 123 --comment
+  ${style.command("uploads put")} ./bug.png --issue 45
+  ${style.command("uploads put")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads attach")} ./before.png ./after.png
+  ${style.command("uploads attach")} ./shot.png --pr 123 --repo myorg/myapp
+  ${style.command("uploads attach")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads doctor")}
+  ${style.command("uploads install")}
+  ${style.command("uploads logout")}
+`;
+}
+function fullBody(style, opts) {
+    return `${header(style, opts)}
+${section(style, "Usage:")}
+  uploads [globals] <command> [args]
+
+${section(style, "Config")} ${style.muted("(first match wins, per key):")}
+  CLI flags           --api-url, --token, --workspace
+  environment         UPLOADS_API_URL, UPLOADS_TOKEN, UPLOADS_WORKSPACE
+  --env-file <path>
+  $BUILDINTERNET_CONFIG
+  ~/.config/buildinternet/config
+
+${section(style, "Workspace")} ${style.muted("(within config layers):")}
+  --workspace, -w     override — global (before command) or per-command (after)
+  UPLOADS_WORKSPACE   env / config file
+  (else inferred from token up_<name>_…, else "default")
+
+${section(style, "Other globals")} ${style.muted("(before command):")}
+  --api-url <url>     default: https://api.uploads.sh
+  --token <token>     or UPLOADS_TOKEN
+  --env-file <path>
+  --json              JSON on stdout
+  --quiet             Suppress stderr progress and update hints
+  --version, -V       Print package version and exit
+
+${section(style, "Commands:")}
+${rows(style, ALL_COMMANDS)}
+
+${section(style, "Put/list defaults")} ${style.muted("(config file or env):")}
+  UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
+  UPLOADS_DEFAULT_WIDTH, UPLOADS_NO_GIT
+
+${section(style, "Update hints")} ${style.muted("(stderr, once/day):")} silence with --quiet / UPLOADS_NO_UPDATE=1 / NO_UPDATE_NOTIFIER=1
+
+${section(style, "Examples:")}
+  ${style.command("uploads login")}
+  ${style.command("uploads whoami")}
+  ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
+  ${style.command("uploads put")} ./after.png --pr 123 --comment
+  ${style.command("uploads put")} ./bug.png --issue 45 --repo myorg/myapp
+  ${style.command("uploads put")} ./shot.png --dry-run --format url
+  ${style.command("uploads put")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads attach")} ./before.png ./after.png
+  ${style.command("uploads attach")} ./shot.png --pr 123 --repo myorg/myapp
+  ${style.command("uploads attach")} ./artifact.zip --issue 45 --no-comment
+  ${style.command("uploads attach")} ./shot.png --meta app=myapp --meta page=settings
+  ${style.command("uploads gallery")} create --title "Release screenshots"
+  ${style.command("uploads doctor")}
+  ${style.command("uploads logout")}
+  ${style.command("uploads --version")}
+
+${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up the agent skill and the hosted MCP server")}
+${style.body("(https://agents.uploads.sh/mcp, workspace inferred from the token). Run")}
+${style.body("`uploads mcp` for local stdio, or use createUploadsWorkerFileTools()")}
+${style.body("from @buildinternet/uploads/agent on the Worker.")}
+
+${style.muted("Tip: uploads help          essentials only")}
+${style.muted("     uploads help --all    this full listing")}
+`;
+}
+/**
+ * Root help text. Default is a short essentials view; pass `full: true` for
+ * the complete command + config dump (`uploads help --all`).
+ */
+export function formatRootHelp(options = {}) {
+    const style = options.style ??
+        createStyle(options.color !== undefined ? options.color : colorEnabled(process.stderr));
+    const body = options.full ? fullBody(style, options) : essentialsBody(style, options);
+    return body.endsWith("\n") ? body : `${body}\n`;
+}
+/** True when argv for the `help` command requests the full listing. */
+export function wantsFullHelp(args) {
+    for (const a of args) {
+        if (a === "--all" || a === "-a" || a === "all")
+            return true;
+    }
+    return false;
+}

package/dist/cli-style.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Minimal ANSI styling for CLI help hierarchy.
+ * Accent palette matches packages/ui tokens (truecolor when enabled).
+ * Honors NO_COLOR / FORCE_COLOR and the target stream's TTY status.
+ * @see https://no-color.org/
+ * @see packages/ui/src/tokens.css
+ */
+export type StyleFn = (text: string) => string;
+export interface CliStyle {
+    bold: StyleFn;
+    dim: StyleFn;
+    /** Section headings — brand accent violet */
+    heading: StyleFn;
+    /** Command / flag names — brand green */
+    command: StyleFn;
+    /** Muted secondary text — token muted gray */
+    muted: StyleFn;
+    /** Body / description text */
+    body: StyleFn;
+    /** High-emphasis title / wordmark */
+    title: StyleFn;
+    /** Errors / unknown-command banner — brand red */
+    error: StyleFn;
+    /** Brand accent (links, tips) */
+    accent: StyleFn;
+    enabled: boolean;
+}
+/** Whether color should be enabled for a given stream. */
+export declare function colorEnabled(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+export declare function createStyle(enabled: boolean): CliStyle;
+/** Pad a left column so descriptions line up (ANSI-aware length). */
+export declare function padCmd(name: string, width: number, style: CliStyle): string;
+/**
+ * Apply root-help visual hierarchy to a plain multi-line command help string:
+ * accent section headers, green flags/commands, muted body.
+ * No-op when color is disabled (returns text unchanged aside from trailing newline).
+ */
+export declare function formatCommandHelp(text: string, style?: CliStyle): string;
+/** Write styled command help to stderr (or a custom writer). */
+export declare function writeCommandHelp(text: string, write?: (chunk: string) => void): void;

package/dist/cli-style.js

@@ -0,0 +1,108 @@
+/**
+ * Minimal ANSI styling for CLI help hierarchy.
+ * Accent palette matches packages/ui tokens (truecolor when enabled).
+ * Honors NO_COLOR / FORCE_COLOR and the target stream's TTY status.
+ * @see https://no-color.org/
+ * @see packages/ui/src/tokens.css
+ */
+import { BRAND } from "./cli-brand.js";
+const identity = (t) => t;
+const RESET = "\u001b[0m";
+const BOLD = "\u001b[1m";
+function fgTrue(c) {
+    return `\u001b[38;2;${c.r};${c.g};${c.b}m`;
+}
+function wrapRgb(c, bold = false) {
+    const open = (bold ? BOLD : "") + fgTrue(c);
+    return (text) => `${open}${text}${RESET}`;
+}
+/** Whether color should be enabled for a given stream. */
+export function colorEnabled(stream = process.stderr, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR === "0")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "")
+        return true;
+    return stream.isTTY === true;
+}
+export function createStyle(enabled) {
+    if (!enabled) {
+        return {
+            bold: identity,
+            dim: identity,
+            heading: identity,
+            command: identity,
+            muted: identity,
+            body: identity,
+            title: identity,
+            error: identity,
+            accent: identity,
+            enabled: false,
+        };
+    }
+    return {
+        bold: (text) => `${BOLD}${fgTrue(BRAND.fg)}${text}${RESET}`,
+        dim: (text) => `\u001b[2m${text}${RESET}`,
+        heading: wrapRgb(BRAND.accent, true),
+        command: wrapRgb(BRAND.green, true),
+        muted: wrapRgb(BRAND.muted),
+        body: wrapRgb(BRAND.body),
+        title: wrapRgb(BRAND.fg, true),
+        error: wrapRgb(BRAND.red, true),
+        accent: wrapRgb(BRAND.accent),
+        enabled: true,
+    };
+}
+/** Pad a left column so descriptions line up (ANSI-aware length). */
+export function padCmd(name, width, style) {
+    const pad = Math.max(0, width - name.length);
+    return style.command(name) + " ".repeat(pad);
+}
+/** Section labels used across command --help blocks. */
+const SECTION_RE = /^(Options|Examples|Commands|Subcommands|Keys|Shells|Usage|What it does|What runs under the hood|Exit codes|Config|Workspace):\s*$/;
+/** Flag column: `  --pr <num>   …` or `  --workspace, -w <name>  …`. */
+const FLAG_RE = /^(\s+)(-[\w-]+(?:,\s*-[\w-]+)?(?:\s+<[^>]+>)?)(\s{2,})(.*)$/;
+/** Example / invocation line starting with the CLI name. */
+const EXAMPLE_RE = /^(\s*)(uploads(?:\s+\S+)*)(.*)$/;
+/**
+ * Apply root-help visual hierarchy to a plain multi-line command help string:
+ * accent section headers, green flags/commands, muted body.
+ * No-op when color is disabled (returns text unchanged aside from trailing newline).
+ */
+export function formatCommandHelp(text, style = createStyle(colorEnabled(process.stderr))) {
+    const normalized = text.endsWith("\n") ? text.slice(0, -1) : text;
+    if (!style.enabled)
+        return `${normalized}\n`;
+    const lines = normalized.split("\n");
+    let firstContent = true;
+    const out = lines.map((line) => {
+        if (line.trim() === "")
+            return line;
+        // Synopsis line (first non-empty): high emphasis
+        if (firstContent) {
+            firstContent = false;
+            return style.title(line);
+        }
+        if (SECTION_RE.test(line))
+            return style.heading(line);
+        const flag = FLAG_RE.exec(line);
+        if (flag) {
+            const [, indent, name, gap, desc] = flag;
+            return `${indent}${style.command(name)}${gap}${style.body(desc)}`;
+        }
+        const example = EXAMPLE_RE.exec(line);
+        if (example && line.trimStart().startsWith("uploads")) {
+            const [, indent, cmd, rest] = example;
+            return `${indent}${style.command(cmd)}${style.body(rest)}`;
+        }
+        return style.body(line);
+    });
+    return `${out.join("\n")}\n`;
+}
+/** Write styled command help to stderr (or a custom writer). */
+export function writeCommandHelp(text, write = (c) => {
+    process.stderr.write(c);
+}) {
+    write(formatCommandHelp(text));
+}

package/dist/cli.js

@@ -2,6 +2,8 @@ import { createUploadsClient } from "./client.js";
 import { resolveApiUrl, resolveConfig } from "./config.js";
 import { UploadsError } from "./errors.js";
 import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
+import { formatRootHelp, wantsFullHelp } from "./cli-help.js";
+import { colorEnabled, createStyle } from "./cli-style.js";
 import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
@@ -10,75 +12,34 @@ import { runInvite } from "./commands/invite.js";
 import { runAdmin } from "./commands/admin-enrollment.js";
 import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
+import { runCompletion } from "./commands/completion.js";
+import { runLogout, runWhoami } from "./commands/session.js";
 import { packageVersion } from "./package-version.js";
-import { maybeHintUpdate } from "./update-check.js";
-const ROOT_HELP = `uploads — CLI for uploads.sh (GitHub image embeds)
-
-Usage:
-  uploads [globals] <command> [args]
-
-Config (first match wins, per key):
-  CLI flags           --api-url, --token, --workspace
-  environment         UPLOADS_API_URL, UPLOADS_TOKEN, UPLOADS_WORKSPACE
-  --env-file <path>
-  $BUILDINTERNET_CONFIG
-  ~/.config/buildinternet/config
-
-Workspace (within config layers):
-  --workspace, -w     override — global (before command) or per-command (after)
-  UPLOADS_WORKSPACE   env / config file
-  (else inferred from token up_<name>_…, else "default")
-
-Other globals (before command):
-  --api-url <url>     default: https://api.uploads.sh
-  --token <token>     or UPLOADS_TOKEN
-  --env-file <path>
-  --json              JSON on stdout
-  --quiet             Suppress stderr progress and update hints
-  --version, -V       Print package version and exit
-
-Commands:
-  attach <file...>     Attach media to the current PR (stable URLs + managed comment)
-  put <file>          Upload (+ URL + markdown for GitHub)
-  gallery             Create and organize public media galleries
-  comment             Create/update a PR/issue attachments comment (via gh)
-  list                List objects (--meta k=v filters by queryable metadata)
-  find k=v...         List objects matching metadata (alias for list --meta)
-  meta                Get/set an object's queryable metadata
-  delete <key>        Delete object
-  usage               Workspace storage / upload counters
-  reconcile           Rebuild usage ledger from storage
-  purge-expired       Delete objects past retentionDays
-  setup               Inspect/configure advanced CLI settings
-  install             Install the agent skill + register the remote MCP server
-  login               Sign in via browser (or an enrollment code) and save credentials
-  invite              Invite a teammate to a workspace (workspace admin; device login)
-  admin               Site-operator invitation management (ADMIN_TOKEN)
-  config              Show path, init, or set shared config
-  doctor              Health + auth + workspace checks
-  health              API liveness (no auth)
-  mcp                 Serve MCP over stdio (tools mirror the CLI)
-
-Put/list defaults (config file or env):
-  UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
-  UPLOADS_DEFAULT_WIDTH, UPLOADS_NO_GIT
-
-Update hints (stderr, once/day): silence with --quiet / UPLOADS_NO_UPDATE=1 / NO_UPDATE_NOTIFIER=1
-
-Examples:
-  uploads setup
-  uploads setup --token up_default_… --repo myorg/myapp
-  uploads attach ./before.png ./after.png
-  uploads put ./shot.png --ref 42
-  uploads gallery create --title "Release screenshots"
-  uploads doctor
-  uploads --version
-
-Agent/MCP: \`uploads install\` sets up the agent skill and the hosted MCP server
-(https://agents.uploads.sh/mcp, workspace inferred from the token). Run
-\`uploads mcp\` for local stdio, or use createUploadsWorkerFileTools()
-from @buildinternet/uploads/agent on the Worker.
-`;
+import { checkForUpdate, maybeHintUpdate } from "./update-check.js";
+async function writeRootHelp(options = {}) {
+    // Best-effort version check so the help header can show a banner when outdated.
+    // Short timeout; cache still applies (once/day). Never blocks help on network.
+    const update = await checkForUpdate({ timeoutMs: 800 });
+    // Empty token (and no env/config) → first-run auth banner.
+    let needsAuth = true;
+    try {
+        const cfg = resolveConfig({
+            requireToken: false,
+            token: options.token,
+            envFile: options.envFile,
+        });
+        needsAuth = !cfg.token;
+    }
+    catch {
+        needsAuth = true;
+    }
+    process.stderr.write(formatRootHelp({
+        full: options.full,
+        version: update.current,
+        latestVersion: update.updateAvailable ? update.latest : undefined,
+        needsAuth,
+    }));
+}
 function createContext(globals, requireToken, commandArgs) {
     const cmdWorkspace = commandWorkspace(parseCommandArgs(commandArgs).flags);
     const config = resolveConfig({
@@ -191,9 +152,18 @@ export async function runCli(argv) {
             process.stdout.write(`${packageVersion()}\n`);
             return 0;
         }
-        if (!parsed.command) {
-            process.stderr.write(ROOT_HELP);
-            return parsed.help ? 0 : 2;
+        // Root help: bare `uploads`, `--help`/`-h`, or `help` / `help --all`.
+        const isHelpCommand = parsed.command === "help";
+        if (!parsed.command || isHelpCommand) {
+            const helpArgs = isHelpCommand ? parsed.rest.slice(1) : parsed.rest;
+            const full = Boolean(parsed.globals.all) || wantsFullHelp(helpArgs);
+            await writeRootHelp({
+                full,
+                token: parsed.globals.token,
+                envFile: parsed.globals.envFile,
+            });
+            // Explicit help exits 0; bare `uploads` is usage → 2.
+            return parsed.help || isHelpCommand ? 0 : 2;
         }
         const cmdArgs = parsed.rest.slice(1);
         const showHelp = parsed.help || cmdArgs.some(isHelpFlag);
@@ -211,6 +181,19 @@ export async function runCli(argv) {
             case "login":
                 code = await runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
                 break;
+            case "whoami":
+            case "status":
+                code = await runWhoami(cmdArgs, {
+                    json,
+                    envFile: parsed.globals.envFile,
+                    token: parsed.globals.token,
+                    workspace: parsed.globals.workspace,
+                    apiUrl: parsed.globals.apiUrl,
+                }, showHelp);
+                break;
+            case "logout":
+                code = await runLogout(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+                break;
             case "invite":
                 code = await runInvite(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
                 break;
@@ -223,6 +206,10 @@ export async function runCli(argv) {
             case "install":
                 code = await runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
                 break;
+            case "completion":
+            case "completions":
+                code = await runCompletion(cmdArgs, showHelp);
+                break;
             case "attach":
             case "put":
             case "gallery":
@@ -276,9 +263,16 @@ export async function runCli(argv) {
                 }
                 break;
             }
-            default:
-                process.stderr.write(`unknown command: ${parsed.command}\n\n${ROOT_HELP}`);
+            default: {
+                const style = createStyle(colorEnabled(process.stderr));
+                process.stderr.write(`${style.error(`unknown command: ${parsed.command}`)}\n\n`);
+                await writeRootHelp({
+                    full: false,
+                    token: parsed.globals.token,
+                    envFile: parsed.globals.envFile,
+                });
                 return 2;
+            }
         }
         // Best-effort; skipped for mcp, --quiet/--json, and opt-out env vars.
         if (code === 0 && !showHelp) {

package/dist/client.d.ts

@@ -60,6 +60,11 @@ export interface PutResult {
     embedUrl: string | null;
     size: number;
     contentType: string;
+    /**
+     * True when the put overwrote an existing key, or (with dryRun) when a put
+     * at this key would overwrite. Always set by the API for put/dry-run.
+     */
+    replaced?: boolean;
     metadata?: Record<string, string>;
 }
 export interface ListItem {
@@ -282,6 +287,18 @@ export interface MintWorkspaceSummary {
 export declare function listMintWorkspaces(apiUrl: string, accessToken: string): Promise<{
     workspaces: MintWorkspaceSummary[];
 }>;
+export interface CreateWorkspaceResult {
+    name: string;
+    publicBaseUrl: string;
+    selfServe: boolean;
+}
+/**
+ * POST /v1/workspaces — self-serve workspace creation from a device-flow
+ * session (presented as a bearer). Throws `UsageError` with a message tuned
+ * for CLI display: a linked-GitHub requirement gets an actionable pointer,
+ * everything else surfaces the server's message.
+ */
+export declare function createWorkspaceRequest(apiUrl: string, accessToken: string, name: string): Promise<CreateWorkspaceResult>;
 export interface MintTokenResult {
     token: string;
     workspace: string;
@@ -306,6 +323,8 @@ export declare function createWorkspaceInvite(apiUrl: string, accessToken: strin
         status: string;
     };
     acceptUrl?: string;
+    /** Whether the install can send invite emails; absent on older auth workers. */
+    emailConfigured?: boolean;
 }>;
 /**
  * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow

package/dist/client.js

@@ -1,4 +1,5 @@
 import { inferContentType } from "./embed.js";
+import { UsageError } from "./cli-args.js";
 import { UploadsError } from "./errors.js";
 import { buildScreenshotKey } from "./keys.js";
 import { packageVersion } from "./package-version.js";
@@ -112,6 +113,31 @@ export function listMintWorkspaces(apiUrl, accessToken) {
         headers: { Authorization: `Bearer ${accessToken}` },
     });
 }
+/**
+ * POST /v1/workspaces — self-serve workspace creation from a device-flow
+ * session (presented as a bearer). Throws `UsageError` with a message tuned
+ * for CLI display: a linked-GitHub requirement gets an actionable pointer,
+ * everything else surfaces the server's message.
+ */
+export async function createWorkspaceRequest(apiUrl, accessToken, name) {
+    try {
+        const { workspace } = await jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/workspaces`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name }),
+        });
+        return workspace;
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.code === "GITHUB_REQUIRED") {
+            throw new UsageError("creating a workspace requires a linked GitHub account — connect one at https://uploads.sh/account/profile and re-run `uploads login`");
+        }
+        throw new UsageError(err instanceof Error ? err.message : "workspace creation failed");
+    }
+}
 /**
  * POST /me/workspaces/:name/invites — org invitation for a workspace.
  * Requires a Better Auth session bearer (device flow), not a workspace token.
@@ -176,6 +202,9 @@ function mapApiError(status, error, code) {
     if (code === "upload_budget_exceeded") {
         return new UploadsError(error, "UPLOAD_BUDGET", status);
     }
+    if (code === "github_required") {
+        return new UploadsError(error, "GITHUB_REQUIRED", status);
+    }
     return new UploadsError(error, "API_ERROR", status);
 }
 /**
@@ -277,6 +306,7 @@ export function createUploadsClient(config) {
                     embedUrl: resolveEmbedUrl(preview.url, preview.embedUrl),
                     size: body.byteLength,
                     contentType,
+                    replaced: preview.replaced === true,
                 };
             }
             const headers = { "Content-Type": contentType };
@@ -305,6 +335,7 @@ export function createUploadsClient(config) {
                 ...result,
                 url: result.url,
                 embedUrl: resolveEmbedUrl(result.url, result.embedUrl),
+                replaced: result.replaced === true,
             };
         },
         list,

package/dist/commands/admin-enrollment.js

@@ -1,5 +1,6 @@
 import { createEnrollment } from "../client.js";
 import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads admin invite create [options]
 
 Admin-only: create a short-lived invitation for an existing workspace.
@@ -65,7 +66,7 @@ export function parseScopes(raw) {
 export async function runAdmin(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(HELP);
+        writeCommandHelp(HELP);
         return 0;
     }
     if (!["invite", "enrollment"].includes(parsed.positionals[0] ?? "") ||

package/dist/commands/completion.d.ts

@@ -0,0 +1,3 @@
+import { type CompletionShell } from "../cli-catalog.js";
+export declare function generateCompletionScript(shell: CompletionShell): string;
+export declare function runCompletion(args: string[], help?: boolean): Promise<number>;