@buildinternet/uploads 0.9.0 → 0.10.1

package/dist/commands/completion.js

@@ -0,0 +1,284 @@
+import { parseCommandArgs, UsageError } from "../cli-args.js";
+import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
+import { writeCommandHelp } from "../cli-style.js";
+const HELP = `uploads completion <shell>
+
+Print a shell completion script to stdout. Source it or install it so Tab
+completes commands, subcommands, and common flags.
+
+Shells:
+  bash   Bash (complete -F)
+  zsh    Zsh (#compdef)
+  fish   Fish (complete -c)
+
+Examples:
+  # zsh (Oh My Zsh / fpath)
+  uploads completion zsh > ~/.zsh/completions/_uploads
+
+  # bash
+  uploads completion bash > ~/.local/share/bash-completion/completions/uploads
+  # or for the current session:
+  eval "$(uploads completion bash)"
+
+  # fish
+  uploads completion fish > ~/.config/fish/completions/uploads.fish
+`;
+function bashScript() {
+    const cmds = ROOT_COMMANDS.map((c) => c.name).join(" ");
+    const globals = GLOBAL_FLAGS.map((g) => g.flag).join(" ");
+    const putFlags = PUT_LIKE_FLAGS.join(" ");
+    const listFlags = LIST_LIKE_FLAGS.join(" ");
+    const subMaps = ROOT_COMMANDS.filter((c) => c.subcommands?.length).map((c) => {
+        const names = c.subcommands.map((s) => s.name).join(" ");
+        return `    ${c.name}) subs="${names}" ;;`;
+    });
+    // Shell `$var` / `$(…)` must not be JS-escaped (`\$`); only shell `${…}` needs `\${…}`
+    // so the template literal doesn't treat it as interpolation.
+    return `# uploads bash completion — generated by: uploads completion bash
+# shellcheck shell=bash disable=SC2207
+
+_uploads() {
+  local cur prev words cword
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion -n : || return
+  else
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=\${COMP_CWORD}
+  fi
+
+  local -a root_cmds=(${cmds})
+  local -a globals=(${globals})
+  local -a put_flags=(${putFlags})
+  local -a list_flags=(${listFlags})
+
+  # Find the first non-global positional (the subcommand).
+  local cmd="" i=1
+  while [[ $i -lt $cword ]]; do
+    local w="\${words[i]}"
+    case "$w" in
+      --api-url|--token|--workspace|-w|--env-file)
+        i=$((i + 2))
+        continue
+        ;;
+      --json|--quiet|--version|-V|--help|-h|--all)
+        i=$((i + 1))
+        continue
+        ;;
+      -*)
+        i=$((i + 1))
+        continue
+        ;;
+      *)
+        cmd="$w"
+        break
+        ;;
+    esac
+  done
+
+  if [[ -z "$cmd" ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=( $(compgen -W "\${globals[*]}" -- "$cur") )
+    else
+      COMPREPLY=( $(compgen -W "\${root_cmds[*]}" -- "$cur") )
+    fi
+    return
+  fi
+
+  local subs=""
+  case "$cmd" in
+${subMaps.join("\n")}
+  esac
+
+  # Completing the subcommand word (or first arg after command).
+  if [[ "$prev" == "$cmd" && -n "$subs" ]]; then
+    COMPREPLY=( $(compgen -W "$subs" -- "$cur") )
+    return
+  fi
+
+  if [[ "$cur" == -* ]]; then
+    case "$cmd" in
+      put|attach)
+        COMPREPLY=( $(compgen -W "\${put_flags[*]}" -- "$cur") )
+        ;;
+      list|find)
+        COMPREPLY=( $(compgen -W "\${list_flags[*]}" -- "$cur") )
+        ;;
+      *)
+        COMPREPLY=( $(compgen -W "--help -h --workspace -w --json --quiet" -- "$cur") )
+        ;;
+    esac
+    return
+  fi
+
+  # File paths for upload-style commands.
+  case "$cmd" in
+    put|attach)
+      COMPREPLY=( $(compgen -f -- "$cur") )
+      ;;
+  esac
+}
+
+complete -o default -F _uploads uploads
+`;
+}
+function zshScript() {
+    const cmdDescribe = ROOT_COMMANDS.map((c) => {
+        const desc = c.summary.replace(/'/g, "'\\''");
+        return `    '${c.name}:${desc}'`;
+    }).join("\n");
+    const globalArgs = GLOBAL_FLAGS.map((g) => {
+        const desc = g.summary.replace(/'/g, "'\\''");
+        // Short and long flags as separate specs when needed.
+        if (g.flag === "-w")
+            return `    '(-w --workspace)'{-w,--workspace}'[${desc}]:workspace:'`;
+        if (g.flag === "--workspace")
+            return null; // paired with -w
+        if (g.flag === "-V")
+            return `    '(-V --version)'{-V,--version}'[${desc}]'`;
+        if (g.flag === "--version")
+            return null;
+        if (g.flag === "-h")
+            return `    '(-h --help)'{-h,--help}'[${desc}]'`;
+        if (g.flag === "--help")
+            return null;
+        if (g.flag === "--api-url")
+            return `    '--api-url[${desc}]:url:'`;
+        if (g.flag === "--token")
+            return `    '--token[${desc}]:token:'`;
+        if (g.flag === "--env-file")
+            return `    '--env-file[${desc}]:file:_files'`;
+        return `    '${g.flag}[${desc}]'`;
+    })
+        .filter(Boolean)
+        .join("\n");
+    const subCases = ROOT_COMMANDS.filter((c) => c.subcommands?.length)
+        .map((c) => {
+        const lines = c
+            .subcommands.map((s) => {
+            const desc = s.summary.replace(/'/g, "'\\''");
+            return `          '${s.name}:${desc}'`;
+        })
+            .join("\n");
+        return `      ${c.name})
+        local -a subs
+        subs=(
+${lines}
+        )
+        _describe 'subcommand' subs
+        ;;`;
+    })
+        .join("\n");
+    return `#compdef uploads
+# uploads zsh completion — generated by: uploads completion zsh
+
+_uploads() {
+  local -a commands
+  commands=(
+${cmdDescribe}
+  )
+
+  local context state state_descr line
+  typeset -A opt_args
+
+  _arguments -C -s -S \\
+${globalArgs} \\
+    '1:command:->cmds' \\
+    '*::arg:->args'
+
+  case $state in
+    cmds)
+      _describe -t commands 'uploads command' commands
+      ;;
+    args)
+      case $line[1] in
+${subCases}
+      put|attach)
+        _files
+        ;;
+      esac
+      ;;
+  esac
+}
+
+_uploads "$@"
+`;
+}
+function fishScript() {
+    const lines = [
+        `# uploads fish completion — generated by: uploads completion fish`,
+        `complete -c uploads -e`,
+        `complete -c uploads -f`,
+    ];
+    for (const g of GLOBAL_FLAGS) {
+        const short = g.flag.length === 2 && g.flag.startsWith("-") && !g.flag.startsWith("--");
+        if (short) {
+            // Pair handled with long form when possible
+            continue;
+        }
+        const esc = g.summary.replace(/'/g, "\\'");
+        if (g.flag === "--workspace") {
+            lines.push(`complete -c uploads -s w -l workspace -d '${esc}' -r`);
+        }
+        else if (g.flag === "--version") {
+            lines.push(`complete -c uploads -s V -l version -d '${esc}'`);
+        }
+        else if (g.flag === "--help") {
+            lines.push(`complete -c uploads -s h -l help -d '${esc}'`);
+        }
+        else if (g.flag === "--api-url" || g.flag === "--token" || g.flag === "--env-file") {
+            lines.push(`complete -c uploads -l ${g.flag.slice(2)} -d '${esc}' -r`);
+        }
+        else {
+            lines.push(`complete -c uploads -l ${g.flag.slice(2)} -d '${esc}'`);
+        }
+    }
+    for (const c of ROOT_COMMANDS) {
+        const esc = c.summary.replace(/'/g, "\\'");
+        lines.push(`complete -c uploads -n '__fish_use_subcommand' -a '${c.name}' -d '${esc}'`);
+        if (c.subcommands?.length) {
+            for (const s of c.subcommands) {
+                const sEsc = s.summary.replace(/'/g, "\\'");
+                // --all under help is a flag-like token; fish still accepts it as -a
+                lines.push(`complete -c uploads -n '__fish_seen_subcommand_from ${c.name}' -a '${s.name}' -d '${sEsc}'`);
+            }
+        }
+    }
+    for (const flag of PUT_LIKE_FLAGS) {
+        if (!flag.startsWith("--"))
+            continue;
+        lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -l ${flag.slice(2)}`);
+    }
+    for (const flag of LIST_LIKE_FLAGS) {
+        if (!flag.startsWith("--"))
+            continue;
+        lines.push(`complete -c uploads -n '__fish_seen_subcommand_from list find' -l ${flag.slice(2)}`);
+    }
+    // File completion for put/attach
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -F`);
+    return lines.join("\n") + "\n";
+}
+export function generateCompletionScript(shell) {
+    switch (shell) {
+        case "bash":
+            return bashScript();
+        case "zsh":
+            return zshScript();
+        case "fish":
+            return fishScript();
+    }
+}
+export async function runCompletion(args, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help || parsed.positionals.length === 0) {
+        writeCommandHelp(HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    const shell = parsed.positionals[0]?.toLowerCase() ?? "";
+    if (!isCompletionShell(shell)) {
+        throw new UsageError(`unknown shell: ${parsed.positionals[0]} (expected ${COMPLETION_SHELLS.join(", ")})`);
+    }
+    process.stdout.write(generateCompletionScript(shell));
+    return 0;
+}

package/dist/commands/config.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, describeConfigSources, redactToken, resolveConfig, resolveConfigPath, resolvePutDefaults, writeConfigKeys, } from "../config.js";
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
 const CONFIG_HELP = `uploads config — manage shared buildinternet config
 
 Shared file (with github-screenshots and other skills):
@@ -41,7 +42,7 @@ function writeJson(payload) {
 export async function runConfig(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help || parsed.positionals.length === 0) {
-        process.stderr.write(CONFIG_HELP);
+        writeCommandHelp(CONFIG_HELP);
         return 0;
     }
     const sub = parsed.positionals[0];
@@ -57,13 +58,14 @@ export async function runConfig(args, opts, help = false) {
         case "set":
             return runConfigSet(rest, subArgs, opts, help);
         default:
-            process.stderr.write(`unknown config subcommand: ${sub}\n\n${CONFIG_HELP}`);
+            process.stderr.write(`unknown config subcommand: ${sub}\n\n`);
+            writeCommandHelp(CONFIG_HELP);
             return 2;
     }
 }
 async function runConfigPath(args, opts, help) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(`uploads config path\n\nPrint the resolved config file path.\n`);
+        writeCommandHelp(`uploads config path\n\nPrint the resolved config file path.\n`);
         return 0;
     }
     const path = resolveConfigPath({ envFile: opts.envFile });
@@ -76,7 +78,7 @@ async function runConfigPath(args, opts, help) {
 }
 async function runConfigShow(args, opts, help) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(`uploads config show\n\nShow effective settings (token redacted).\n`);
+        writeCommandHelp(`uploads config show\n\nShow effective settings (token redacted).\n`);
         return 0;
     }
     const config = resolveConfig({ envFile: opts.envFile, requireToken: false });
@@ -117,7 +119,7 @@ async function runConfigShow(args, opts, help) {
 async function runConfigInit(args, opts, help) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(`uploads config init [options]
+        writeCommandHelp(`uploads config init [options]
 
 Create or update UPLOADS_* keys in the shared config file.
 
@@ -173,7 +175,7 @@ Examples:
 async function runConfigSet(positionals, args, opts, help) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(`uploads config set <key> <value> [--path <file>] [--force]
+        writeCommandHelp(`uploads config set <key> <value> [--path <file>] [--force]
 
 Examples:
   uploads config set UPLOADS_TOKEN up_default_…
@@ -184,7 +186,7 @@ Examples:
     const key = positionals[0];
     const value = positionals[1];
     if (!key || !value) {
-        process.stderr.write(`uploads config set <key> <value>\n`);
+        writeCommandHelp(`uploads config set <key> <value>\n`);
         return 2;
     }
     if (!VALID_KEYS.has(key)) {

package/dist/commands/install.js

@@ -1,6 +1,7 @@
 import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { resolveConfig } from "../config.js";
 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";
@@ -123,7 +124,7 @@ function printSuccessFooter(steps, signedIn) {
 export async function runInstall(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(INSTALL_HELP);
+        writeCommandHelp(INSTALL_HELP);
         return 0;
     }
     const target = parsed.positionals[0] ?? "all";

package/dist/commands/invite.js

@@ -4,6 +4,7 @@
  */
 import { createWorkspaceInvite, listMintWorkspaces } from "../client.js";
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
 import { defaultDeviceIo, obtainDeviceAccessToken, resolveAuthUrl, } from "./login.js";
 const HELP = `uploads invite create [options]
 
@@ -53,7 +54,7 @@ export function resolveInviteWorkspace(workspaces, requested) {
 export async function runInvite(args, opts, help = false, io = defaultDeviceIo) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(HELP);
+        writeCommandHelp(HELP);
         return 0;
     }
     if (parsed.positionals[0] !== "create") {
@@ -88,13 +89,25 @@ export async function runInvite(args, opts, help = false, io = defaultDeviceIo)
         invitationId: result.invitation.id,
         status: result.invitation.status,
         acceptUrl: result.acceptUrl ?? null,
+        emailConfigured: result.emailConfigured ?? null,
     };
     if (opts.json)
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     else {
         process.stdout.write(`Invited ${email} to ${workspace} as ${role} (${result.invitation.status}).\n`);
+        if (result.emailConfigured === true) {
+            process.stdout.write(`Invitation emailed to ${email}.\n`);
+        }
+        else if (result.emailConfigured === false) {
+            process.stdout.write("Email isn't configured on this install — share the accept link yourself.\n");
+        }
         if (result.acceptUrl) {
-            process.stdout.write(`Accept link (share if email isn't configured):\n  ${result.acceptUrl}\n`);
+            const label = result.emailConfigured === true
+                ? "Accept link (backup)"
+                : result.emailConfigured === false
+                    ? "Accept link"
+                    : "Accept link (share if email isn't configured)";
+            process.stdout.write(`${label}:\n  ${result.acceptUrl}\n`);
         }
         process.stdout.write("They accept, then run: uploads login\n");
     }

package/dist/commands/login.d.ts

@@ -17,6 +17,10 @@ export interface DeviceLoginIo {
     now: () => number;
     openUrl: (url: string) => void;
     write: (text: string) => void;
+    /** Whether the CLI can prompt the user (a real TTY, not a script/CI pipe). */
+    isTTY: boolean;
+    /** Prompt for a new workspace name when the account has zero. */
+    promptWorkspaceName: () => Promise<string>;
 }
 export declare const defaultDeviceIo: DeviceLoginIo;
 /**

package/dist/commands/login.js

@@ -1,10 +1,12 @@
 import { hostname } from "node:os";
+import { createInterface } from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { stdin, stdout } from "node:process";
 import { loadConfigFile, redactToken, resolveConfigPath, writeConfigKeys, workspaceFromToken, } from "../config.js";
-import { createUploadsClient, exchangeEnrollment, listMintWorkspaces, mintWorkspaceToken, requestDeviceCode, requestDeviceToken, } from "../client.js";
+import { createUploadsClient, createWorkspaceRequest, exchangeEnrollment, listMintWorkspaces, mintWorkspaceToken, requestDeviceCode, requestDeviceToken, } from "../client.js";
 import { flagBool, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
 import { parseScopes } from "./admin-enrollment.js";
+import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads login [options]
 
 Sign in and save workspace credentials. With no flags, opens a browser to
@@ -14,6 +16,9 @@ code only if you were given one from before device login (fallback path).
 Options:
   --workspace <name>  Workspace to mint a token for (device flow; required if
                       your account can access more than one)
+  --create            With --workspace: create the workspace first if your
+                      account doesn't have it yet (device flow only) — lets
+                      scripted/agent logins provision without a prompt
   --scopes <list>     Comma-separated scopes (default: files:read,files:write)
   --label <text>      Token label (default: this machine's hostname)
   --auth-url <url>    Auth base (default: https://auth.uploads.sh)
@@ -30,6 +35,7 @@ Options:
 Examples:
   uploads login
   uploads login --workspace acme
+  uploads login --workspace acme --create         # provision if it doesn't exist
   uploads login --code upe_… --force              # fallback: pre-existing invite
   printf '%s' upe_… | uploads login --code-stdin --non-interactive
 `;
@@ -157,6 +163,15 @@ function openUrl(url) {
         // ignore — the URL is printed for manual navigation.
     }
 }
+async function promptWorkspaceName() {
+    const rl = createInterface({ input: stdin, output: process.stderr });
+    try {
+        return (await rl.question("no workspaces yet — enter a name to create one (lowercase, hyphens): ")).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
 export const defaultDeviceIo = {
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     now: () => Date.now(),
@@ -164,6 +179,8 @@ export const defaultDeviceIo = {
     write: (text) => {
         process.stderr.write(text);
     },
+    isTTY: Boolean(stdin.isTTY),
+    promptWorkspaceName,
 };
 /**
  * Browser device-authorization session only (no workspace token mint).
@@ -187,8 +204,11 @@ async function runDeviceLogin(parsed, opts, io) {
     const scopes = parseScopes(flagString(parsed.flags, "--scopes"));
     const label = flagString(parsed.flags, "--label") ?? safeHostname();
     const requestedWorkspace = flagString(parsed.flags, "--workspace");
+    // Make the target explicit: a bare `uploads login` on a self-hosted install
+    // would otherwise silently sign in to the cloud service.
+    io.write(`signing in to ${opts.authUrl} (self-hosted? pass --api-url or set UPLOADS_API_URL)\n\n`);
     const accessToken = await obtainDeviceAccessToken(opts.authUrl, { noOpen: opts.noOpen }, io);
-    const workspace = await resolveMintWorkspace(opts.apiUrl, accessToken, requestedWorkspace);
+    const workspace = await resolveMintWorkspace(opts.apiUrl, accessToken, requestedWorkspace, io, flagBool(parsed.flags, "--create"));
     const minted = await mintWorkspaceToken(opts.apiUrl, accessToken, { workspace, scopes, label });
     return { workspace: minted.workspace, token: minted.token, apiUrl: opts.apiUrl };
 }
@@ -235,18 +255,36 @@ export async function pollForDeviceToken(authUrl, code, io) {
     throw new UsageError("timed out waiting for device authorization");
 }
 /**
- * Pick the workspace to mint for. An explicit --workspace wins; otherwise, if
- * the account can access exactly one workspace, use it — and if it can access
+ * Pick the workspace to mint for. An explicit --workspace wins (with --create,
+ * it's provisioned first when the account doesn't have it); otherwise, if the
+ * account can access exactly one workspace, use it — and if it can access
  * several, require the flag rather than guessing.
  */
-async function resolveMintWorkspace(apiUrl, accessToken, requested) {
-    if (requested)
-        return requested;
+async function resolveMintWorkspace(apiUrl, accessToken, requested, io, create = false) {
+    if (requested) {
+        if (!create)
+            return requested;
+        // Idempotent from the caller's view: an existing membership just mints.
+        const { workspaces } = await listMintWorkspaces(apiUrl, accessToken);
+        if (workspaces.some((w) => w.workspace === requested))
+            return requested;
+        const created = await createWorkspaceRequest(apiUrl, accessToken, requested);
+        io.write(`created workspace "${created.name}" — files will get public URLs under ${created.publicBaseUrl}/\n`);
+        return created.name;
+    }
     const { workspaces } = await listMintWorkspaces(apiUrl, accessToken);
     if (workspaces.length === 1)
         return workspaces[0].workspace;
     if (workspaces.length === 0) {
-        throw new UsageError("your account has no workspace access yet — ask an administrator for an invitation");
+        if (!io.isTTY) {
+            throw new UsageError("your account has no workspace access yet — pass `--workspace <name> --create` to provision one, run `uploads login` interactively, or ask an administrator for an invitation");
+        }
+        const name = (await io.promptWorkspaceName()).trim();
+        if (!name)
+            throw new UsageError("workspace creation cancelled");
+        const created = await createWorkspaceRequest(apiUrl, accessToken, name);
+        io.write(`created workspace "${created.name}" — files will get public URLs under ${created.publicBaseUrl}/\n`);
+        return created.name;
     }
     const names = workspaces.map((w) => w.workspace).join(", ");
     throw new UsageError(`multiple workspaces available (${names}); pass --workspace <name>`);
@@ -254,7 +292,7 @@ async function resolveMintWorkspace(apiUrl, accessToken, requested) {
 export async function runLogin(args, opts, help = false, deviceIo = defaultDeviceIo) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
-        process.stderr.write(HELP);
+        writeCommandHelp(HELP);
         return 0;
     }
     const apiUrl = flagString(parsed.flags, "--api-url") ?? opts.apiUrl ?? "https://api.uploads.sh";
@@ -265,8 +303,12 @@ export async function runLogin(args, opts, help = false, deviceIo = defaultDevic
         throw new UsageError(`credentials already exist in ${path}; use --force to replace them`);
     if (process.env.UPLOADS_TOKEN && !force)
         throw new UsageError("UPLOADS_TOKEN is already set in the environment; unset it or use --force");
+    if (flagBool(parsed.flags, "--create") && !flagString(parsed.flags, "--workspace"))
+        throw new UsageError("--create requires --workspace <name>");
     let result;
     if (hasEnrollmentSource(parsed)) {
+        if (flagBool(parsed.flags, "--create"))
+            throw new UsageError("--create is device-flow only; enrollment codes are workspace-bound");
         const code = await resolveEnrollmentCode(parsed);
         result = await exchangeEnrollment(apiUrl, code);
     }
@@ -312,6 +354,7 @@ export async function runLogin(args, opts, help = false, deviceIo = defaultDevic
     const payload = {
         ok: doctor.ok,
         configPath: path,
+        apiUrl: savedApiUrl,
         workspace: result.workspace,
         token: redactToken(result.token),
         doctor: checked ? doctor : { skipped: true },
@@ -319,8 +362,10 @@ export async function runLogin(args, opts, help = false, deviceIo = defaultDevic
     if (opts.json)
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     else {
-        process.stdout.write(`saved credentials to ${path}\nworkspace: ${result.workspace}\ntoken: ${redactToken(result.token)}\n`);
+        process.stdout.write(`saved credentials to ${path}\napi: ${savedApiUrl}\nworkspace: ${result.workspace}\ntoken: ${redactToken(result.token)}\n`);
         process[doctor.ok ? "stdout" : "stderr"].write(`doctor: ${checked ? (doctor.ok ? "ok" : `failed — ${doctor.error}`) : "skipped"}\n`);
+        if (doctor.ok)
+            process.stdout.write("\nusing a coding agent? run `uploads install` to add the uploads skill + MCP server to Claude Code\n");
     }
     return doctor.ok ? 0 : 1;
 }

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { createMcpServer } from "../mcp/server.js";
 import { serveStdio } from "../mcp/stdio.js";
 import { createUploadsMcpTools } from "../mcp/tools.js";
 import { packageVersion } from "../package-version.js";
+import { writeCommandHelp } from "../cli-style.js";
 const MCP_HELP = `uploads [globals] mcp
 
 Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
@@ -24,7 +25,7 @@ Examples:
 `;
 export async function runMcp(args, opts, help = false) {
     if (help || parseCommandArgs(args).help) {
-        process.stderr.write(MCP_HELP);
+        writeCommandHelp(MCP_HELP);
         return 0;
     }
     const server = createMcpServer({

package/dist/commands/session.d.ts

@@ -0,0 +1,31 @@
+export interface WhoamiReport {
+    signedIn: boolean;
+    workspace: string;
+    workspaceSource: string;
+    workspaceFromToken: string | undefined;
+    token: string;
+    tokenSource: string;
+    /** True when the config file holds UPLOADS_TOKEN. */
+    tokenInConfig: boolean;
+    apiUrl: string;
+    apiUrlSource: string;
+    configPath: string;
+    configExists: boolean;
+}
+export declare function buildWhoamiReport(opts: {
+    envFile?: string;
+    token?: string;
+    workspace?: string;
+    apiUrl?: string;
+}): WhoamiReport;
+export declare function runWhoami(args: string[], opts: {
+    json?: boolean;
+    envFile?: string;
+    token?: string;
+    workspace?: string;
+    apiUrl?: string;
+}, help?: boolean): Promise<number>;
+export declare function runLogout(args: string[], opts: {
+    json?: boolean;
+    envFile?: string;
+}, help?: boolean): Promise<number>;