@buildinternet/uploads 0.8.0 → 0.10.0

package/README.md

@@ -25,10 +25,11 @@ uploads put ./capture-2026-…Z.png --pr 123 --name hero.png   # clean leaf, sta
 uploads put ./shot.png --pr 123 --name hero.png --dry-run --format url  # preview URL, no upload
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
-uploads put ./shot.png --meta app=myapp --meta page=settings   # queryable custom metadata
-uploads meta get screenshots/myapp/42/shot.png
-uploads meta set screenshots/myapp/42/shot.png page=onboarding --delete device
-uploads find app=myapp page=settings                            # or: list --meta app=myapp
+# custom metadata (queryable): page URL, in-app path, which surface
+uploads put ./shot.png --meta url=https://app.example/settings --meta path=/settings --meta app=web
+uploads meta get screenshots/myapp/42/shot.webp
+uploads meta set screenshots/myapp/42/shot.webp path=/onboarding --delete url
+uploads find app=web path=/settings                             # or: list --meta app=web
 uploads doctor
 ```
 
@@ -37,10 +38,19 @@ up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
 Commands: `attach`, `put`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
-`reconcile`, `purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`.
+`reconcile`, `purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`,
+`completion`.
+
+**Help:** bare `uploads` / `uploads help` / `--help` shows essentials; use
+`uploads help --all` (or `--help --all`) for the full command list. Per-command:
+`uploads <cmd> --help`.
+
+**Shell completion:** `uploads completion bash|zsh|fish` prints a script to
+stdout. Example (zsh): `uploads completion zsh > ~/.zsh/completions/_uploads`.
 
 **Globals (before the command):** `--api-url`, `--token`, `--workspace` / `-w`,
-`--env-file`, `--json`, `--quiet`, `--version` / `-V`, `-h` / `--help`.
+`--env-file`, `--json`, `--quiet`, `--version` / `-V`, `-h` / `--help`, `--all`
+(with root help).
 
 **Update hints:** after a successful run the CLI may print one stderr line when a
 newer npm release is available (at most once/day, `~/.cache/uploads/`). Silence
@@ -65,7 +75,13 @@ use `gh/…`. Workspaces may restrict put/sign to those roots via
 **Image optimization:** by default, still images are re-encoded to WebP (long edge
 capped, high quality) before upload so GitHub embeds stay small, and **EXIF is
 stripped**. Pass `--keep-exif` / `UPLOADS_KEEP_EXIF=1` to preserve image metadata, or
-`--no-optimize` / `UPLOADS_NO_OPTIMIZE=1` to upload originals unchanged.
+`--no-optimize` / `UPLOADS_NO_OPTIMIZE=1` to upload originals unchanged. Optimize
+notes print human sizes (e.g. `411.5 KB → 94.2 KB`).
+
+**Re-upload / hot-swap:** the same key overwrites in place with no prompt (stable
+`--pr` / `attach` paths). Human mode notes `>> replaced existing object (same URL)`;
+JSON includes `replaced`. Preview with `--dry-run` (reports _would replace_ when
+the key already exists).
 
 **Frames (opt-in):** `--frame phone|browser|iphone-16-pro` composites chrome
 **before** optimize. `phone`/`browser` are procedural; `iphone-16-pro` fetches
@@ -98,7 +114,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `set_metadata` and `find_files` mirror `uploads meta set` and `uploads find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -106,7 +122,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. `uploads install` registers the skill + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skill + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-args.d.ts

@@ -7,6 +7,8 @@ export interface GlobalFlags {
     quiet?: boolean;
     /** `--version` / `-V` — print package version and exit. */
     version?: boolean;
+    /** `--all` — with root help, show the full command list. */
+    all?: boolean;
 }
 export interface ParsedArgv {
     globals: GlobalFlags;

package/dist/cli-args.js

@@ -33,6 +33,11 @@ export function parseArgv(argv) {
             i++;
             continue;
         }
+        if (arg === "--all") {
+            globals.all = true;
+            i++;
+            continue;
+        }
         if (VALUE_GLOBALS.has(arg)) {
             const value = args[i + 1];
             if (!value || value.startsWith("-")) {

package/dist/cli-brand.d.ts

@@ -0,0 +1,89 @@
+/**
+ * uploads.sh brand tokens + terminal chevron mark for root help.
+ * Colors mirror packages/ui/src/tokens.css; geometry from Brand.tsx / favicon.
+ */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Design tokens from packages/ui (dark scheme). */
+export declare const BRAND: {
+    readonly bg: {
+        readonly r: 10;
+        readonly g: 10;
+        readonly b: 11;
+    };
+    readonly panel: {
+        readonly r: 18;
+        readonly g: 18;
+        readonly b: 20;
+    };
+    readonly line: {
+        readonly r: 35;
+        readonly g: 35;
+        readonly b: 39;
+    };
+    readonly fg: {
+        readonly r: 236;
+        readonly g: 236;
+        readonly b: 234;
+    };
+    readonly body: {
+        readonly r: 179;
+        readonly g: 179;
+        readonly b: 173;
+    };
+    readonly muted: {
+        readonly r: 138;
+        readonly g: 138;
+        readonly b: 131;
+    };
+    readonly accent: {
+        readonly r: 194;
+        readonly g: 126;
+        readonly b: 255;
+    };
+    readonly green: {
+        readonly r: 143;
+        readonly g: 174;
+        readonly b: 98;
+    };
+    readonly red: {
+        readonly r: 217;
+        readonly g: 138;
+        readonly b: 156;
+    };
+};
+export declare function mixRgb(a: Rgb, b: Rgb, t: number): Rgb;
+export declare function accentAt(opacity: number, over?: Rgb): Rgb;
+/** Deep-copy the thin chevron opacity grid. */
+export declare function rasterizeMark(): (number | null)[][];
+/**
+ * Half-block render of the mark (▀/▄/█). Two pixel rows → one terminal row.
+ */
+export declare function renderBrandMarkLines(options?: {
+    color?: boolean;
+}): string[];
+/** Default CLI tagline. */
+export declare const DEFAULT_TAGLINE = "GitHub screenshot + recording uploads for agents";
+/**
+ * Brand lockup:
+ *   [mark]  uploads.sh
+ *   [mark]  GitHub screenshot + recording uploads for agents
+ *   [mark]  v0.9.0
+ */
+export declare function formatBrandHeader(options?: {
+    color?: boolean;
+    label?: string;
+    tagline?: string;
+    version?: string;
+}): string;
+export declare function formatUpdateBanner(options: {
+    current: string;
+    latest: string;
+    color?: boolean;
+}): string;
+export declare function formatAuthBanner(options?: {
+    color?: boolean;
+}): string;

package/dist/cli-brand.js

@@ -0,0 +1,166 @@
+/**
+ * uploads.sh brand tokens + terminal chevron mark for root help.
+ * Colors mirror packages/ui/src/tokens.css; geometry from Brand.tsx / favicon.
+ */
+/** Design tokens from packages/ui (dark scheme). */
+export const BRAND = {
+    bg: { r: 0x0a, g: 0x0a, b: 0x0b },
+    panel: { r: 0x12, g: 0x12, b: 0x14 },
+    line: { r: 0x23, g: 0x23, b: 0x27 },
+    fg: { r: 0xec, g: 0xec, b: 0xea },
+    body: { r: 0xb3, g: 0xb3, b: 0xad },
+    muted: { r: 0x8a, g: 0x8a, b: 0x83 },
+    accent: { r: 0xc2, g: 0x7e, b: 0xff },
+    green: { r: 0x8f, g: 0xae, b: 0x62 },
+    red: { r: 0xd9, g: 0x8a, b: 0x9c },
+};
+export function mixRgb(a, b, t) {
+    const u = Math.min(1, Math.max(0, t));
+    return {
+        r: Math.round(a.r * u + b.r * (1 - u)),
+        g: Math.round(a.g * u + b.g * (1 - u)),
+        b: Math.round(a.b * u + b.b * (1 - u)),
+    };
+}
+export function accentAt(opacity, over = BRAND.panel) {
+    return mixRgb(BRAND.accent, over, opacity);
+}
+/**
+ * Thin stacked chevrons (1-cell stroke, 5×9) with brand opacities 1 / 0.55 / 0.28.
+ * Mirrors the three fading Λ shapes from the favicon without fat 4×4 fills.
+ */
+const THIN_CHEVRON = (() => {
+    const rows = ["  #  ", " # # ", "#   #", "  #  ", " # # ", "#   #", "  #  ", " # # ", "#   #"];
+    const opacities = [1, 1, 1, 0.55, 0.55, 0.55, 0.28, 0.28, 0.28];
+    return rows.map((row, y) => [...row].map((ch) => (ch === "#" ? opacities[y] : null)));
+})();
+/** Deep-copy the thin chevron opacity grid. */
+export function rasterizeMark() {
+    return THIN_CHEVRON.map((row) => row.slice());
+}
+function cellColor(v) {
+    if (v === null || v <= 0)
+        return null;
+    return accentAt(v);
+}
+function ansiFg(c) {
+    return `\u001b[38;2;${c.r};${c.g};${c.b}m`;
+}
+function ansiBg(c) {
+    return `\u001b[48;2;${c.r};${c.g};${c.b}m`;
+}
+const ANSI_RESET = "\u001b[0m";
+/**
+ * Half-block render of the mark (▀/▄/█). Two pixel rows → one terminal row.
+ */
+export function renderBrandMarkLines(options = {}) {
+    const grid = rasterizeMark();
+    const color = options.color ?? false;
+    const height = grid.length;
+    const width = grid[0]?.length ?? 0;
+    const lines = [];
+    for (let y = 0; y < height; y += 2) {
+        let line = "";
+        for (let x = 0; x < width; x++) {
+            const top = grid[y]?.[x] ?? null;
+            const bot = grid[y + 1]?.[x] ?? null;
+            const tc = cellColor(top);
+            const bc = cellColor(bot);
+            if (!color) {
+                const strength = Math.max(top ?? 0, bot ?? 0);
+                if (strength <= 0)
+                    line += " ";
+                else if (top && bot)
+                    line += strength >= 0.8 ? "█" : strength >= 0.4 ? "▓" : "░";
+                else if (top)
+                    line += "▀";
+                else
+                    line += "▄";
+                continue;
+            }
+            if (tc && bc) {
+                if (top === bot)
+                    line += ansiFg(tc) + "█" + ANSI_RESET;
+                else
+                    line += ansiFg(tc) + ansiBg(bc) + "▀" + ANSI_RESET;
+            }
+            else if (tc)
+                line += ansiFg(tc) + "▀" + ANSI_RESET;
+            else if (bc)
+                line += ansiFg(bc) + "▄" + ANSI_RESET;
+            else
+                line += " ";
+        }
+        lines.push(line.replace(/\s+$/, ""));
+    }
+    return lines;
+}
+/** Default CLI tagline. */
+export const DEFAULT_TAGLINE = "GitHub screenshot + recording uploads for agents";
+/**
+ * Brand lockup:
+ *   [mark]  uploads.sh
+ *   [mark]  GitHub screenshot + recording uploads for agents
+ *   [mark]  v0.9.0
+ */
+export function formatBrandHeader(options = {}) {
+    const color = options.color ?? false;
+    const label = options.label ?? "uploads.sh";
+    const tagline = options.tagline ?? DEFAULT_TAGLINE;
+    const markLines = renderBrandMarkLines({ color });
+    const markWidth = Math.max(...markLines.map((l) => visibleWidth(l)), 1);
+    const gap = "  ";
+    const paint = (text, rgb, bold = false) => color
+        ? `${bold ? "\u001b[1m" : ""}\u001b[38;2;${rgb.r};${rgb.g};${rgb.b}m${text}\u001b[0m`
+        : text;
+    const extras = [
+        paint(label, BRAND.fg, true),
+        paint(tagline, BRAND.muted),
+        options.version ? paint(`v${options.version}`, BRAND.muted) : "",
+    ];
+    const out = [];
+    const rows = Math.max(markLines.length, extras.filter(Boolean).length);
+    for (let i = 0; i < rows; i++) {
+        const mark = (markLines[i] ?? "").padEnd(markWidth, " ");
+        const extra = extras[i] ? gap + extras[i] : "";
+        out.push(mark + extra);
+    }
+    return out.join("\n") + "\n";
+}
+/** Strip CSI sequences for display-width (ESC is matched as \x1b for the linter). */
+function visibleWidth(s) {
+    // eslint-disable-next-line no-control-regex -- intentional: strip ANSI CSI
+    return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+function boxLines(lines, options = {}) {
+    const color = options.color ?? false;
+    const tone = options.tone ?? BRAND.accent;
+    const width = Math.max(...lines.map((l) => l.length), 1) + 4;
+    const bar = "─".repeat(width);
+    const pad = (s) => s.padEnd(width - 2);
+    if (!color) {
+        return [`┌${bar}┐`, ...lines.map((l) => `│  ${pad(l)}│`), `└${bar}┘`, ""].join("\n");
+    }
+    const edge = (s) => `\u001b[38;2;${tone.r};${tone.g};${tone.b}m${s}\u001b[0m`;
+    const title = (s) => `\u001b[1m\u001b[38;2;${tone.r};${tone.g};${tone.b}m${s}\u001b[0m`;
+    const cmd = (s) => `\u001b[1m\u001b[38;2;${BRAND.fg.r};${BRAND.fg.g};${BRAND.fg.b}m${s}\u001b[0m`;
+    const muted = (s) => `\u001b[38;2;${BRAND.muted.r};${BRAND.muted.g};${BRAND.muted.b}m${s}\u001b[0m`;
+    return [
+        edge(`┌${bar}┐`),
+        ...lines.map((l, i) => {
+            const body = i === 0 ? title(pad(l)) : i === 1 ? cmd(pad(l)) : muted(pad(l));
+            return `${edge("│  ")}${body}${edge("│")}`;
+        }),
+        edge(`└${bar}┘`),
+        "",
+    ].join("\n");
+}
+export function formatUpdateBanner(options) {
+    return boxLines([`Update available  ${options.current} → ${options.latest}`, `npm i -g @buildinternet/uploads`], { color: options.color, tone: BRAND.accent });
+}
+export function formatAuthBanner(options = {}) {
+    return boxLines(["Sign in via browser", "uploads login"], {
+        color: options.color,
+        tone: BRAND.red,
+    });
+}

package/dist/cli-catalog.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared CLI surface for help text and shell completions.
+ * Keep in sync when adding root commands or nested subcommands.
+ */
+export interface CatalogCommand {
+    /** Root command name (no args). */
+    name: string;
+    summary: string;
+    /** Shown in help left column when set (e.g. `put <file>`). */
+    usage?: string;
+    /** Included in the short essentials help. */
+    essential?: boolean;
+    subcommands?: readonly {
+        name: string;
+        summary: string;
+    }[];
+}
+/** Global flags accepted before the subcommand. */
+export declare const GLOBAL_FLAGS: readonly {
+    flag: string;
+    summary: string;
+}[];
+/** Common flags for put/attach (file-oriented commands). */
+export declare const PUT_LIKE_FLAGS: readonly string[];
+export declare const LIST_LIKE_FLAGS: readonly string[];
+export declare const ROOT_COMMANDS: readonly CatalogCommand[];
+export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+export declare function isCompletionShell(value: string): value is CompletionShell;
+export declare function rootCommandNames(): string[];
+/** Also accept plural alias for the completion command. */
+export declare const COMPLETION_ALIASES: readonly ["completion", "completions"];

package/dist/cli-catalog.js

@@ -0,0 +1,187 @@
+/**
+ * Shared CLI surface for help text and shell completions.
+ * Keep in sync when adding root commands or nested subcommands.
+ */
+/** Global flags accepted before the subcommand. */
+export const GLOBAL_FLAGS = [
+    { flag: "--api-url", summary: "API base URL" },
+    { flag: "--token", summary: "Bearer token" },
+    { flag: "--workspace", summary: "Workspace name" },
+    { flag: "-w", summary: "Workspace name (short)" },
+    { flag: "--env-file", summary: "Load env from file" },
+    { flag: "--json", summary: "JSON on stdout" },
+    { flag: "--quiet", summary: "Suppress stderr progress" },
+    { flag: "--version", summary: "Print package version" },
+    { flag: "-V", summary: "Print package version (short)" },
+    { flag: "--help", summary: "Show help" },
+    { flag: "-h", summary: "Show help (short)" },
+    { flag: "--all", summary: "Full root help listing" },
+];
+/** Common flags for put/attach (file-oriented commands). */
+export const PUT_LIKE_FLAGS = [
+    "--destination",
+    "--prefix",
+    "--repo",
+    "--ref",
+    "--pr",
+    "--issue",
+    "--comment",
+    "--no-comment",
+    "--format",
+    "--dry-run",
+    "--name",
+    "--no-optimize",
+    "--frame",
+    "--frame-url",
+    "--gallery",
+    "--meta",
+    "--workspace",
+    "-w",
+    "--help",
+    "-h",
+];
+export const LIST_LIKE_FLAGS = [
+    "--prefix",
+    "--limit",
+    "--cursor",
+    "--meta",
+    "--workspace",
+    "-w",
+    "--help",
+    "-h",
+];
+export const ROOT_COMMANDS = [
+    {
+        name: "attach",
+        usage: "attach <file...>",
+        summary: "Attach media to the current PR (stable URLs + managed comment)",
+        essential: true,
+    },
+    {
+        name: "put",
+        usage: "put <file>",
+        summary: "Upload (+ URL + markdown for GitHub)",
+        essential: true,
+    },
+    {
+        name: "gallery",
+        summary: "Create and organize public media galleries",
+        subcommands: [
+            { name: "create", summary: "Create a gallery" },
+            { name: "show", summary: "Show a gallery" },
+            { name: "list", summary: "List galleries" },
+            { name: "delete", summary: "Delete a gallery record" },
+            { name: "add", summary: "Add objects to a gallery" },
+            { name: "link", summary: "Link a gallery to a GitHub issue/PR" },
+            { name: "unlink", summary: "Unlink a gallery from GitHub" },
+        ],
+    },
+    {
+        name: "comment",
+        summary: "Create/update a PR/issue attachments comment (via gh)",
+    },
+    {
+        name: "list",
+        summary: "List objects (--meta k=v filters by queryable metadata)",
+        essential: true,
+    },
+    {
+        name: "find",
+        usage: "find k=v...",
+        summary: "List objects matching metadata (alias for list --meta)",
+    },
+    {
+        name: "meta",
+        summary: "Get/set an object's queryable metadata",
+        subcommands: [
+            { name: "get", summary: "Show metadata for an object" },
+            { name: "set", summary: "Merge-set and/or delete metadata pairs" },
+        ],
+    },
+    {
+        name: "delete",
+        usage: "delete <key>",
+        summary: "Delete object",
+        essential: true,
+    },
+    { name: "usage", summary: "Workspace storage / upload counters" },
+    { name: "reconcile", summary: "Rebuild usage ledger from storage" },
+    { name: "purge-expired", summary: "Delete objects past retentionDays" },
+    { name: "setup", summary: "Inspect/configure advanced CLI settings" },
+    {
+        name: "install",
+        summary: "Install the agent skill + register the remote MCP server",
+        essential: true,
+        subcommands: [
+            { name: "skill", summary: "Install the agent skill only" },
+            { name: "mcp", summary: "Register the remote MCP server only" },
+            { name: "all", summary: "Install skill and MCP (default)" },
+        ],
+    },
+    {
+        name: "login",
+        summary: "Sign in via browser (or an enrollment code) and save credentials",
+        essential: true,
+    },
+    {
+        name: "whoami",
+        summary: "Show active workspace and token (alias: status)",
+        essential: true,
+    },
+    {
+        name: "logout",
+        summary: "Remove the saved UPLOADS_TOKEN from the config file",
+    },
+    {
+        name: "invite",
+        summary: "Invite a teammate to a workspace (workspace admin; device login)",
+    },
+    {
+        name: "admin",
+        summary: "Site-operator invitation management (ADMIN_TOKEN)",
+        subcommands: [
+            { name: "invite", summary: "Create a workspace invitation" },
+            { name: "enrollment", summary: "Legacy alias for invite" },
+        ],
+    },
+    {
+        name: "config",
+        summary: "Show path, init, or set shared config",
+        subcommands: [
+            { name: "path", summary: "Print config file path" },
+            { name: "show", summary: "Show effective settings" },
+            { name: "init", summary: "Create or update UPLOADS_* keys" },
+            { name: "set", summary: "Set one UPLOADS_* key" },
+        ],
+    },
+    {
+        name: "doctor",
+        summary: "Health + auth + workspace checks",
+        essential: true,
+    },
+    { name: "health", summary: "API liveness (no auth)" },
+    { name: "mcp", summary: "Serve MCP over stdio (tools mirror the CLI)" },
+    {
+        name: "help",
+        summary: "Show this help (essentials; use --all for the full list)",
+        subcommands: [{ name: "--all", summary: "Full command list and config" }],
+    },
+    {
+        name: "completion",
+        summary: "Print shell completion script (bash, zsh, or fish)",
+        subcommands: [
+            { name: "bash", summary: "Bash completion script" },
+            { name: "zsh", summary: "Zsh completion script" },
+            { name: "fish", summary: "Fish completion script" },
+        ],
+    },
+];
+export const COMPLETION_SHELLS = ["bash", "zsh", "fish"];
+export function isCompletionShell(value) {
+    return COMPLETION_SHELLS.includes(value);
+}
+export function rootCommandNames() {
+    return ROOT_COMMANDS.map((c) => c.name);
+}
+/** Also accept plural alias for the completion command. */
+export const COMPLETION_ALIASES = ["completion", "completions"];

package/dist/cli-help.d.ts

@@ -0,0 +1,26 @@
+import { type CliStyle } from "./cli-style.js";
+export interface RootHelpOptions {
+    /** Full command list + config layers. Default: curated essentials. */
+    full?: boolean;
+    /** Force color on/off; default is TTY + env detection on stderr. */
+    color?: boolean;
+    style?: CliStyle;
+    /** Include pixel brand mark in the header (default true). */
+    brandMark?: boolean;
+    /** Override package version shown in the header. */
+    version?: string;
+    /** When set, show a noticeable update banner under the header. */
+    latestVersion?: string;
+    /**
+     * When true, show a loud "not signed in" banner at the very top with
+     * `uploads login`. Callers should set this when no token is configured.
+     */
+    needsAuth?: boolean;
+}
+/**
+ * Root help text. Default is a short essentials view; pass `full: true` for
+ * the complete command + config dump (`uploads help --all`).
+ */
+export declare function formatRootHelp(options?: RootHelpOptions): string;
+/** True when argv for the `help` command requests the full listing. */
+export declare function wantsFullHelp(args: string[]): boolean;