@buildinternet/uploads 0.10.1 → 0.11.1

package/README.md

@@ -39,7 +39,8 @@ global `uploads` form above.
 
 Commands: `attach`, `put`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
-`logout`, `invite`, `admin`, `config`, `doctor`, `health`, `mcp`, `completion`.
+`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `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:
@@ -57,6 +58,19 @@ newer npm release is available (at most once/day, `~/.cache/uploads/`). Silence
 with `--quiet`, `--json`, `UPLOADS_NO_UPDATE=1`, or `NO_UPDATE_NOTIFIER=1`. Not used
 for `uploads mcp`.
 
+**Telemetry:** the CLI and MCP server send anonymous usage pings (command name,
+version, OS/arch, exit code, duration, optional error code) to
+`POST /v1/telemetry` on the configured API. No arguments, paths, tokens, workspace
+names, or file content. Opt out with `UPLOADS_TELEMETRY_DISABLED=1`,
+`DO_NOT_TRACK=1`, or `uploads telemetry disable`. First interactive run prints a
+one-line notice.
+
+**Diagnostic reports (opt-in):** `uploads report "what broke"` sends a short
+message to the team. Attach a log with `--file ./trace.log`, or pipe:
+`uploads doctor --json 2>&1 | uploads report "doctor failed"`. Never automatic —
+also available as the MCP `report` tool when the user asks to submit feedback.
+Attachments are text-only (max 256 KiB) and stored under an unguessable R2 key.
+
 **Exit codes:** `0` ok, `2` usage/token/file, `3` auth/policy, `4` network, `1` other.
 Failures go to stderr; under `--format json|url|markdown` they also go to stdout so
 piped runs stay self-diagnosing. Prefer JSON `code` over message text. `put --dry-run`
@@ -114,7 +128,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`, `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).
+`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`, `get_metadata`, `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`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `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"] }
@@ -122,7 +136,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. 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.
+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 (including `get_metadata` / `set_metadata` / `find_files`) 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 skills + 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
 
@@ -159,4 +173,4 @@ pnpm pack:check   # verify the npm tarball contents
 
 Maintainer release instructions: [`docs/releasing.md`](../../docs/releasing.md).
 
-Agent-oriented usage: [`skills/uploads-cli/SKILL.md`](../../skills/uploads-cli/SKILL.md). REST details: [`docs/api.md`](../../docs/api.md).
+Agent-oriented usage: [`skills/uploads-cli/SKILL.md`](../../skills/uploads-cli/SKILL.md) (full CLI reference) and [`skills/github-screenshots/SKILL.md`](../../skills/github-screenshots/SKILL.md) (visuals into PRs/issues). REST details: [`docs/api.md`](../../docs/api.md).

package/dist/async.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Run `fn` over `values` with bounded concurrency, preserving input order
+ * in the returned array. Used by multi-file attach (and similar fan-outs).
+ */
+export declare function mapBounded<T, R>(values: readonly T[], concurrency: number, fn: (value: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/async.js

@@ -0,0 +1,21 @@
+/**
+ * Run `fn` over `values` with bounded concurrency, preserving input order
+ * in the returned array. Used by multi-file attach (and similar fan-outs).
+ */
+export async function mapBounded(values, concurrency, fn) {
+    if (values.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, values.length));
+    const result = Array.from({ length: values.length });
+    let next = 0;
+    async function worker() {
+        for (;;) {
+            const index = next++;
+            if (index >= values.length)
+                return;
+            result[index] = await fn(values[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, worker));
+    return result;
+}

package/dist/cli-catalog.js

@@ -59,7 +59,7 @@ export const ROOT_COMMANDS = [
     },
     {
         name: "put",
-        usage: "put <file>",
+        usage: "put <file...>",
         summary: "Upload (+ URL + markdown for GitHub)",
         essential: true,
     },
@@ -110,12 +110,12 @@ export const ROOT_COMMANDS = [
     { name: "setup", summary: "Inspect/configure advanced CLI settings" },
     {
         name: "install",
-        summary: "Install the agent skill + register the remote MCP server",
+        summary: "Install the agent skills + register the remote MCP server",
         essential: true,
         subcommands: [
-            { name: "skill", summary: "Install the agent skill only" },
+            { name: "skill", summary: "Install the agent skills only" },
             { name: "mcp", summary: "Register the remote MCP server only" },
-            { name: "all", summary: "Install skill and MCP (default)" },
+            { name: "all", summary: "Install skills and MCP (default)" },
         ],
     },
     {
@@ -154,6 +154,20 @@ export const ROOT_COMMANDS = [
             { name: "set", summary: "Set one UPLOADS_* key" },
         ],
     },
+    {
+        name: "telemetry",
+        summary: "Manage anonymous usage telemetry (status / enable / disable)",
+        subcommands: [
+            { name: "status", summary: "Show whether telemetry is enabled" },
+            { name: "enable", summary: "Enable anonymous usage telemetry" },
+            { name: "disable", summary: "Disable anonymous usage telemetry" },
+        ],
+    },
+    {
+        name: "report",
+        usage: "report [message]",
+        summary: "Send a diagnostic report (optional log attachment; explicit opt-in)",
+    },
     {
         name: "doctor",
         summary: "Health + auth + workspace checks",

package/dist/cli-help.js

@@ -147,7 +147,7 @@ ${section(style, "Examples:")}
   ${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")}
+${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up the agent skills 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.")}

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { createUploadsClient } from "./client.js";
-import { resolveApiUrl, resolveConfig } from "./config.js";
+import { DEFAULT_API_URL, 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";
@@ -14,8 +14,11 @@ 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 { runTelemetry } from "./commands/telemetry.js";
+import { runReport } from "./commands/report.js";
 import { packageVersion } from "./package-version.js";
 import { checkForUpdate, maybeHintUpdate } from "./update-check.js";
+import { errorCodeFromUnknown, maybeShowFirstRunNotice, recordEvent, telemetryCommandName, } from "./telemetry.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.
@@ -144,10 +147,47 @@ function usageHint(argv) {
     }
 }
 export async function runCli(argv) {
+    const telemetryStart = Date.now();
+    const telemetryCmd = telemetryCommandName(argv);
+    // Prefer --api-url from argv early so every exit path can pass it to telemetry.
+    let apiUrl = DEFAULT_API_URL;
+    try {
+        apiUrl = resolveApiUrl(parseArgv(argv).globals);
+    }
+    catch {
+        // Usage errors while parsing globals fall through to the main try/catch.
+    }
+    const skipTelemetry = argv.includes("--version") ||
+        argv.includes("-V") ||
+        telemetryCmd === "telemetry" ||
+        telemetryCmd.startsWith("telemetry ") ||
+        // Report is itself a deliberate submit; skip the automatic usage ping.
+        telemetryCmd === "report";
+    // One-time notice for interactive humans (never MCP / json / quiet).
+    if (!skipTelemetry) {
+        const wantsQuiet = argv.includes("--json") || argv.includes("--quiet") || argv[2] === "mcp";
+        maybeShowFirstRunNotice({ interactive: wantsQuiet ? false : undefined });
+    }
+    const flushTelemetry = (code, err) => {
+        if (skipTelemetry)
+            return;
+        // Long-lived MCP process: per-tool events come from the MCP server; skip
+        // a process-level "mcp" ping so we don't double-count or hang exit.
+        if (telemetryCmd === "mcp")
+            return;
+        recordEvent({
+            surface: "cli",
+            command: telemetryCmd,
+            exitCode: code,
+            durationMs: Date.now() - telemetryStart,
+            errorCode: err !== undefined ? errorCodeFromUnknown(err) : undefined,
+        }, { apiUrl });
+    };
     try {
         const parsed = parseArgv(argv);
         const json = parsed.globals.json ?? false;
         const quiet = parsed.globals.quiet ?? false;
+        apiUrl = resolveApiUrl(parsed.globals);
         if (parsed.globals.version) {
             process.stdout.write(`${packageVersion()}\n`);
             return 0;
@@ -163,14 +203,16 @@ export async function runCli(argv) {
                 envFile: parsed.globals.envFile,
             });
             // Explicit help exits 0; bare `uploads` is usage → 2.
-            return parsed.help || isHelpCommand ? 0 : 2;
+            const code = parsed.help || isHelpCommand ? 0 : 2;
+            flushTelemetry(code);
+            return code;
         }
         const cmdArgs = parsed.rest.slice(1);
         const showHelp = parsed.help || cmdArgs.some(isHelpFlag);
         let code;
         switch (parsed.command) {
             case "health":
-                code = await runHealth({ apiUrl: resolveApiUrl(parsed.globals), json }, cmdArgs, showHelp);
+                code = await runHealth({ apiUrl, json }, cmdArgs, showHelp);
                 break;
             case "config":
                 code = await runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
@@ -179,7 +221,7 @@ export async function runCli(argv) {
                 code = await runSetup(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
                 break;
             case "login":
-                code = await runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                code = await runLogin(cmdArgs, { json, apiUrl }, showHelp);
                 break;
             case "whoami":
             case "status":
@@ -195,10 +237,16 @@ export async function runCli(argv) {
                 code = await runLogout(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
                 break;
             case "invite":
-                code = await runInvite(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                code = await runInvite(cmdArgs, { json, apiUrl }, showHelp);
                 break;
             case "admin":
-                code = await runAdmin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                code = await runAdmin(cmdArgs, { json, apiUrl }, showHelp);
+                break;
+            case "telemetry":
+                code = await runTelemetry(cmdArgs, { json, apiUrl }, showHelp);
+                break;
+            case "report":
+                code = await runReport(cmdArgs, { json, apiUrl }, showHelp);
                 break;
             case "mcp":
                 code = await runMcp(cmdArgs, { globals: parsed.globals }, showHelp);
@@ -271,6 +319,7 @@ export async function runCli(argv) {
                     token: parsed.globals.token,
                     envFile: parsed.globals.envFile,
                 });
+                flushTelemetry(2);
                 return 2;
             }
         }
@@ -278,6 +327,7 @@ export async function runCli(argv) {
         if (code === 0 && !showHelp) {
             await maybeHintUpdate({ quiet: quiet || json, command: parsed.command });
         }
+        flushTelemetry(code);
         return code;
     }
     catch (err) {
@@ -285,6 +335,8 @@ export async function runCli(argv) {
         errorOut(err, format);
         if (err instanceof UsageError && format !== "json")
             usageHint(argv);
-        return exitCode(err);
+        const code = exitCode(err);
+        flushTelemetry(code, err);
+        return code;
     }
 }

package/dist/commands/install.js

@@ -4,22 +4,24 @@ import { execRunner } from "../github-gh.js";
 import { writeCommandHelp } from "../cli-style.js";
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
 const SKILL_SOURCE = "buildinternet/uploads";
-const SKILL_NAME = "uploads-cli";
-const INSTALL_HELP = `uploads install — set up agent integrations (skill + remote MCP)
+const SKILL_NAMES = ["uploads-cli", "github-screenshots"];
+const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP)
 
-Installs the uploads-cli agent skill and registers the hosted MCP server
-with Claude Code. The remote MCP endpoint infers your workspace from the
-bearer token, so only the token is needed.
+Installs the github-screenshots and uploads-cli agent skills and registers
+the hosted MCP server with Claude Code. The remote MCP endpoint infers your
+workspace from the bearer token, so only the token is needed.
 
 Usage:
   uploads install [skill|mcp|all]     (default: all)
 
 What it does:
-  skill   Agent skill (via npx skills) — when to host files / embed in PRs
+  skill   Agent skills (via npx skills) — github-screenshots: visuals into
+          PRs/issues; uploads-cli: full CLI reference
   mcp     Hosted MCP server in Claude Code — put, list, attach, galleries
 
 What runs under the hood:
-  skill   npx -y skills add ${SKILL_SOURCE} --skill ${SKILL_NAME} -g -y -a '*'
+  skill   npx -y skills add ${SKILL_SOURCE} --skill <name> -g -y -a '*'
+          (once per skill: ${SKILL_NAMES.join(", ")})
   mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
             --header "Authorization: Bearer <token>"
 
@@ -57,9 +59,9 @@ function runStep(run, command) {
         return { command, ok: false, error: hint };
     }
 }
-function skillCommand() {
+function skillCommand(skill) {
     // -g global, -y non-interactive, -a '*' every agent (skips the multi-select TUI)
-    return ["npx", "-y", "skills", "add", SKILL_SOURCE, "--skill", SKILL_NAME, "-g", "-y", "-a", "*"];
+    return ["npx", "-y", "skills", "add", SKILL_SOURCE, "--skill", skill, "-g", "-y", "-a", "*"];
 }
 function mcpCommand(name, url, bearer) {
     return [
@@ -142,10 +144,14 @@ export async function runInstall(args, opts, help = false) {
     const redact = redactor(token);
     const results = {};
     if (target === "skill" || target === "all") {
-        const command = skillCommand();
         if (human)
-            process.stdout.write("Installing skill…\n");
-        results.skill = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
+            process.stdout.write("Installing skills…\n");
+        for (const skill of SKILL_NAMES) {
+            const command = skillCommand(skill);
+            results[`skill:${skill}`] = dryRun
+                ? { command, ok: true, skipped: "dry-run" }
+                : runStep(run, command);
+        }
     }
     if (target === "mcp" || target === "all") {
         if (!dryRun && !token) {
@@ -179,14 +185,26 @@ export async function runInstall(args, opts, help = false) {
         return failed ? 1 : 0;
     }
     printHumanSteps(results, redact, verbose);
+    const skillResults = Object.entries(results)
+        .filter(([step]) => step.startsWith("skill:"))
+        .map(([, r]) => r);
+    const skillsOk = skillResults.length > 0 && skillResults.every((r) => r.ok);
+    const skillsFailed = skillResults.some((r) => !r.ok);
     if (!failed && !dryRun) {
-        printSuccessFooter(Object.keys(results), signedIn);
+        const stepLabels = [
+            ...new Set(Object.keys(results).map((k) => (k.startsWith("skill:") ? "skills" : k))),
+        ];
+        printSuccessFooter(stepLabels, signedIn);
     }
-    else if (failed && !dryRun && results.skill?.ok && results.mcp && !results.mcp.ok) {
+    else if (failed && !dryRun && skillsOk && results.mcp && !results.mcp.ok) {
         const next = results.mcp.skipped === "sign-in"
             ? "Sign in with `uploads login`, then re-run `uploads install mcp`."
             : "Fix the MCP step above, then re-run `uploads install mcp`.";
-        process.stdout.write(`\nSkill is installed. ${next}\n`);
+        process.stdout.write(`\nSkills are installed. ${next}\n`);
+    }
+    else if (failed && !dryRun && skillsFailed) {
+        // Mixed or total skill failure used to print only per-step lines (#191).
+        process.stdout.write("\nSkill install incomplete. Fix the errors above, then re-run `uploads install skill`.\n");
     }
     return failed ? 1 : 0;
 }

package/dist/commands/mcp.js

@@ -1,4 +1,5 @@
 import { parseCommandArgs } from "../cli-args.js";
+import { resolveApiUrl } from "../config.js";
 import { createMcpServer } from "../mcp/server.js";
 import { serveStdio } from "../mcp/stdio.js";
 import { createUploadsMcpTools } from "../mcp/tools.js";
@@ -31,6 +32,7 @@ export async function runMcp(args, opts, help = false) {
     const server = createMcpServer({
         serverInfo: { name: "uploads", version: packageVersion() },
         tools: createUploadsMcpTools({ globals: opts.globals }),
+        apiUrl: resolveApiUrl(opts.globals),
     });
     await serveStdio(server);
     return 0;

package/dist/commands/report.d.ts

@@ -0,0 +1,4 @@
+export declare function runReport(args: string[], opts?: {
+    json?: boolean;
+    apiUrl?: string;
+}, help?: boolean): Promise<number>;

package/dist/commands/report.js

@@ -0,0 +1,164 @@
+/**
+ * `uploads report` — explicit opt-in diagnostic message (+ optional log).
+ */
+import { createInterface } from "node:readline/promises";
+import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson } from "../io.js";
+import { attachmentFromText, buildReportPayload, loadReportAttachment, MAX_REPORT_ATTACHMENT_BYTES, MAX_REPORT_MESSAGE, parseReportType, reportFallbackHint, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
+const REPORT_HELP = `uploads report [message] — send a diagnostic report (explicit opt-in)
+
+Nothing is sent unless you run this (or the MCP report tool).
+
+Options:
+  --file <path>         Attach a text log/trace (max 256 KiB)
+  --type <t>            bug | error | idea | other (default: other)
+  --contact <value>     Optional email/handle for follow-up
+  --command <name>      Command that failed (e.g. put) — no args/paths
+  --error-code <code>   Optional UploadsError code (e.g. KEY_POLICY)
+  --dry-run             Print the payload without sending
+  --json                JSON on stdout
+
+Examples:
+  uploads report "put fails with KEY_POLICY on custom prefixes"
+  uploads report --type bug --file ./trace.log "crash during optimize"
+  uploads doctor --json 2>&1 | uploads report "doctor failed"
+`;
+/**
+ * Bound stdin read. Stops once maxBytes is exceeded (returns what was read
+ * plus a flag so callers can reject oversized input).
+ */
+async function readStdinBounded(maxBytes) {
+    const chunks = [];
+    let total = 0;
+    let exceeded = false;
+    for await (const chunk of process.stdin) {
+        const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+        total += buf.byteLength;
+        if (total > maxBytes) {
+            exceeded = true;
+            const keep = maxBytes - (total - buf.byteLength);
+            if (keep > 0)
+                chunks.push(buf.subarray(0, keep));
+            break; // stop reading; peer close drains the rest
+        }
+        chunks.push(buf);
+    }
+    return { text: Buffer.concat(chunks).toString("utf8"), exceeded };
+}
+export async function runReport(args, opts = {}, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(REPORT_HELP);
+        return 0;
+    }
+    const typeFlag = flagString(parsed.flags, "--type");
+    if (typeFlag && !parseReportType(typeFlag)) {
+        throw new UsageError(`--type must be one of: ${REPORT_TYPES.join(", ")}`);
+    }
+    const type = parseReportType(typeFlag) ?? "other";
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    const json = opts.json || flagBool(parsed.flags, "--json");
+    const filePath = flagString(parsed.flags, "--file");
+    const positional = parsed.positionals.length > 0 ? parsed.positionals.join(" ") : undefined;
+    const hasPositional = Boolean(positional?.trim());
+    const stdinIsPipe = !process.stdin.isTTY;
+    // Only consume stdin when we still need a message or a piped attachment.
+    // Skip when --file already supplies the log and a positional message exists.
+    const needStdinAsMessage = stdinIsPipe && !hasPositional;
+    const needStdinAsAttachment = stdinIsPipe && hasPositional && !filePath;
+    let piped = "";
+    let pipedExceeded = false;
+    if (needStdinAsMessage || needStdinAsAttachment) {
+        const max = needStdinAsAttachment ? MAX_REPORT_ATTACHMENT_BYTES : MAX_REPORT_MESSAGE + 1; // +1 so we can detect "too long"
+        const result = await readStdinBounded(max);
+        piped = result.text;
+        pipedExceeded = result.exceeded;
+    }
+    const pipedTrimmed = piped.trim();
+    let raw = null;
+    if (hasPositional)
+        raw = positional;
+    else if (pipedTrimmed)
+        raw = pipedTrimmed;
+    else if (process.stdin.isTTY) {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            const answer = await rl.question("What's going wrong? (blank to cancel)\n> ");
+            raw = answer.trim() || null;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    if (raw === null) {
+        if (json)
+            await writeJson({ ok: false, cancelled: true });
+        else
+            process.stderr.write("Cancelled — no report sent.\n");
+        return 0;
+    }
+    if (needStdinAsMessage && (pipedExceeded || raw.length > MAX_REPORT_MESSAGE)) {
+        throw new UsageError('piped input is too long for the message — use: `… | uploads report "summary"`');
+    }
+    const validated = validateReportMessage(raw);
+    if (!validated.ok)
+        throw new UsageError(validated.error);
+    let attachment;
+    try {
+        if (filePath)
+            attachment = loadReportAttachment(filePath);
+        else if (needStdinAsAttachment && pipedTrimmed) {
+            if (pipedExceeded) {
+                throw new Error(`attachment exceeds ${MAX_REPORT_ATTACHMENT_BYTES} bytes`);
+            }
+            attachment = attachmentFromText(piped, "stdin.log");
+        }
+    }
+    catch (err) {
+        throw new UsageError(err instanceof Error ? err.message : String(err));
+    }
+    const payload = buildReportPayload(validated.message, {
+        type,
+        contact: flagString(parsed.flags, "--contact")?.trim() || undefined,
+        surface: "cli",
+        command: flagString(parsed.flags, "--command"),
+        errorCode: flagString(parsed.flags, "--error-code"),
+        attachment,
+    });
+    if (dryRun) {
+        const preview = {
+            ...payload,
+            attachment: payload.attachment
+                ? {
+                    filename: payload.attachment.filename,
+                    contentType: payload.attachment.contentType,
+                    bytes: new TextEncoder().encode(payload.attachment.body).byteLength,
+                    body: "[omitted in dry-run]",
+                }
+                : undefined,
+        };
+        if (json)
+            await writeJson({ dryRun: true, payload: preview });
+        else
+            process.stdout.write(`[dry-run] would POST:\n${JSON.stringify(preview, null, 2)}\n`);
+        return 0;
+    }
+    const result = await submitReport(payload, { apiUrl: opts.apiUrl });
+    if (result.ok) {
+        if (json) {
+            await writeJson({ ok: true, id: result.id, hasAttachment: result.hasAttachment });
+        }
+        else {
+            process.stdout.write(`Thanks — report received (id: ${result.id}${result.hasAttachment ? ", with attachment" : ""})\n`);
+        }
+        return 0;
+    }
+    if (json)
+        await writeJson({ ok: false, error: result.error });
+    else {
+        process.stderr.write(`error: couldn't send report: ${result.error}\n`);
+        process.stderr.write(`hint: ${reportFallbackHint()}\n`);
+    }
+    return 1;
+}

package/dist/commands/telemetry.d.ts

@@ -0,0 +1,4 @@
+export declare function runTelemetry(args: string[], opts?: {
+    json?: boolean;
+    apiUrl?: string;
+}, help?: boolean): Promise<number>;

package/dist/commands/telemetry.js

@@ -0,0 +1,91 @@
+/**
+ * `uploads telemetry` — status / enable / disable for anonymous usage pings.
+ */
+import { flagBool, parseCommandArgs } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson } from "../io.js";
+import { setTelemetryEnabled, telemetryStatus, defaultTelemetryDataDir } from "../telemetry.js";
+const TELEMETRY_HELP = `uploads telemetry — manage anonymous usage telemetry
+
+Subcommands:
+  status     Show whether telemetry is enabled and where events go
+  enable     Enable anonymous usage telemetry
+  disable    Disable anonymous usage telemetry
+
+What is collected (when enabled):
+  command name, CLI version, OS/arch, runtime, exit code, duration,
+  client kind/agent, anonymous id, optional allowlisted error code.
+  Never arguments, paths, tokens, workspace names, or file content.
+
+Opt out without this command:
+  UPLOADS_TELEMETRY_DISABLED=1
+  DO_NOT_TRACK=1
+
+Examples:
+  uploads telemetry status
+  uploads telemetry status --json
+  uploads telemetry disable
+  uploads telemetry enable
+`;
+export async function runTelemetry(args, opts = {}, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help || parsed.positionals.length === 0) {
+        writeCommandHelp(TELEMETRY_HELP);
+        return 0;
+    }
+    const sub = parsed.positionals[0];
+    const json = opts.json || flagBool(parsed.flags, "--json");
+    switch (sub) {
+        case "status": {
+            const s = telemetryStatus({ apiUrl: opts.apiUrl });
+            if (json) {
+                await writeJson({
+                    enabled: s.enabled,
+                    reason: s.reason ?? null,
+                    anonId: s.anonId,
+                    clientKind: s.clientKind,
+                    agentName: s.agentName ?? null,
+                    endpoint: s.endpoint,
+                    dataDir: defaultTelemetryDataDir(),
+                });
+                return 0;
+            }
+            process.stdout.write(`Telemetry: ${s.enabled ? "enabled" : "disabled"}\n`);
+            if (!s.enabled && s.reason)
+                process.stdout.write(`Reason:    ${s.reason}\n`);
+            process.stdout.write(`Anon ID:   ${s.anonId}\n`);
+            process.stdout.write(`Kind:      ${s.clientKind}${s.agentName ? ` (${s.agentName})` : ""}\n`);
+            process.stdout.write(`Endpoint:  ${s.endpoint}\n`);
+            process.stdout.write("\nAnonymous non-PII usage only (no paths, tokens, or content).\n");
+            process.stdout.write("See `uploads telemetry --help` for what is sent and how to opt out.\n");
+            return 0;
+        }
+        case "enable": {
+            setTelemetryEnabled(true);
+            const s = telemetryStatus({ apiUrl: opts.apiUrl });
+            if (json) {
+                await writeJson({ enabled: s.enabled, reason: s.reason ?? null });
+            }
+            else if (s.enabled) {
+                process.stdout.write("Telemetry enabled.\n");
+            }
+            else {
+                process.stdout.write(`Telemetry still disabled (${s.reason ?? "opt-out active"}).\n`);
+                process.stdout.write("Cleared the local disable file; env opt-outs still apply.\n");
+            }
+            return 0;
+        }
+        case "disable": {
+            setTelemetryEnabled(false);
+            if (json)
+                await writeJson({ enabled: false });
+            else
+                process.stdout.write("Telemetry disabled.\n");
+            return 0;
+        }
+        default:
+            process.stderr.write(`error: unknown telemetry subcommand: ${sub}\n`);
+            process.stderr.write("hint: uploads telemetry --help\n");
+            return 2;
+    }
+}