veodl 1.8.2 → 1.8.3

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to veo. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.8.3
+
+### Added
+
+- Added `veo alias` commands (`list`, `add`, `remove`) to manage custom command names and shortcuts that forward to `veo`.
+- Added `veo uninstall` to remove individual aliases with `-p <name>`, or perform a full interactive/planned purge with `--yes`.
+- Added `veo up` as a short alias for `veo update`.
+
+### Changed
+
+- Streamlined package binary commands to `veo` and `veodl`.
+
 ## 1.8.2
 
 ### Changed

package/README.md

@@ -10,7 +10,7 @@ Automating with an agent? Start with the [agent guide](docs/AGENT_GUIDE.md) for
 
 Requires **Node.js 22+** and npm. Internet access is needed for installation and first-use backend setup.
 
-The npm package is `veodl`; the installed commands are `veo`, `veod`, and `veodl`.
+The npm package is `veodl`; the installed commands are `veo` and `veodl`.
 
 ```bash
 npx veodl "https://example.com/video.mp4"
@@ -21,7 +21,7 @@ Or install globally:
 ```bash
 npm install -g veodl
 veo "https://example.com/video.mp4"
-# or: veod / veodl "https://example.com/video.mp4"
+# or: veodl "https://example.com/video.mp4"
 ```
 
 The first download automatically prepares missing yt-dlp, FFmpeg and FFprobe.
@@ -452,9 +452,11 @@ paths and custom comments are preserved.
   xdg-utils and a file association). The CLI does not wait for the player to close. If the
   opener cannot be launched, a warning is printed and the successful download still exits
   with `0`; later errors inside the detached opener/player are not monitored.
-- After each successful download, veo checks the npm registry at most once per day for a
-  newer version and prints a one-line notice on stderr (never on failure). Disable it with
-  `VEO_NO_UPDATE_CHECK=1`; `VEO_REGISTRY`/`npm_config_registry` are respected.
+- After each successful command, veo checks the npm registry at most once per day for a
+  newer version and prints a one-line notice on stderr (`Update available: veo X
+  (you have Y). Run: veo up`). Help, version and the update commands themselves
+  stay quiet. Disable it with `VEO_NO_UPDATE_CHECK=1`;
+  `VEO_REGISTRY`/`npm_config_registry` are respected.
 - Exit status is `0` on success, `1` on errors, and `130` on cancellation. With several
   URLs, `1` means at least one URL failed.
 
@@ -483,10 +485,17 @@ veo flush             # stop runs, clear temporary downloads and retry jobs
 veo flush --stats     # the same, and reset the statistics
 veo update            # install the latest veo with npm
 veo update --check    # only check for a newer veo
+veo up                # short alias for veo update (also: veo up --check)
 veo upgrade           # alias for veo update
 veo check update      # alias for veo update --check
 veo backend update    # install the newest yt-dlp release
 veo backend reset     # back to the release pinned in this veo version
+veo alias list        # shipped (veo, veodl) plus custom wrappers
+veo alias add veo-dl  # create veo-dl as a wrapper that calls veo
+veo alias remove veo-dl  # delete a custom wrapper
+veo uninstall -p veodl   # delete one alias (veo itself stays installed)
+veo uninstall            # plan the full removal (aliases, package, cache, config)
+veo uninstall --yes      # remove everything
 ```
 
 `veo update` runs `npm install -g veodl@latest` and then removes yt-dlp backend
@@ -495,6 +504,33 @@ never uses a shell on Linux/macOS, passes fixed arguments only, and prints the m
 command on any failure. The registry can be overridden with `VEO_REGISTRY` (or npm's
 `npm_config_registry`) for mirrors and proxies.
 
+### `veo alias` and `veo uninstall`
+
+The npm package is `veodl`; a global install ships the commands `veo`
+and `veodl`. `veo alias` manages extra command names without reinstalling:
+
+```bash
+veo alias list
+veo alias add veo-dl
+veo alias remove veo-dl
+veo uninstall -p veodl
+```
+
+`add` creates a small wrapper next to the `veo` command found on `PATH` that
+forwards to `veo`, so it survives `veo update`. Names use 2-31 lowercase
+letters, digits or hyphens. `remove` (also `veo alias rm`) deletes the wrapper
+files; `veo` itself can never be removed this way. Removing a shipped name such
+as `veodl` only deletes that shortcut — the next `veo update` recreates it.
+
+`veo uninstall -p <name>` is a shortcut for `veo alias remove <name>`. Bare
+`veo uninstall` removes everything: without flags it only prints the plan
+(package `veodl` with commands veo, veodl, plus custom wrappers, cache
+and config paths); `veo uninstall --yes` deletes all of it — custom wrappers,
+the package with `npm uninstall -g veodl`, veo's cache directory (downloads,
+jobs, backend tools, history, statistics) and the config file. Use
+`--keep-aliases`, `--keep-cache` or `--keep-config` to preserve one part.
+Add `--json` for scripting.
+
 ### `veo flush`
 
 Run `veo flush` to stop active veo runs started with this version, then remove

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "veodl",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "description": "A clean, simple video downloader powered by yt-dlp.",
   "type": "module",
   "bin": {
     "veo": "bin/veo.js",
-    "veod": "bin/veo.js",
     "veodl": "bin/veo.js"
   },
   "files": [

package/src/alias.js

@@ -0,0 +1,258 @@
+import path from 'node:path';
+import { chmod, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { commandOutput } from './output.js';
+import { findOnPath } from './backend.js';
+import { cleanText, readableError } from './utils.js';
+
+export const BUILTIN_ALIASES = ['veo', 'veodl'];
+export const ALIAS_MARKER = 'veo-alias';
+
+export const ALIAS_HELP = `veo alias - manage extra command names for veo
+
+Usage:
+  veo alias                    List command names (same as: veo alias list)
+  veo alias list [--json]      Show veo, veodl plus custom wrappers
+  veo alias add <name> [--force] [--json]
+                               Create <name> as a wrapper that calls veo
+  veo alias remove <name> [--json]   Delete a wrapper (also: veo alias rm)
+  veo alias --help             Show this help
+
+Names use 2-31 lowercase letters, digits or hyphens and start with a letter,
+e.g. veo-dl. The wrapper is created next to the veo command found on PATH and
+simply forwards to veo, so it survives veo updates. Removing veodl only
+removes that shortcut; veo update recreates the shipped names. veo itself can
+never be removed. Use --bin-dir <path> to override the target directory.
+`;
+
+export function validateAliasName(input) {
+  const raw = String(input ?? '').trim();
+  if (!raw) throw new Error('An alias name is required. Use: veo alias add <name>');
+  if (cleanText(raw) !== raw) throw new Error(`Invalid alias name: ${raw}. Use plain text without escapes.`);
+  if (!/^[a-z][a-z0-9-]{1,30}$/.test(raw)) {
+    throw new Error(`Invalid alias name "${raw}". Use 2-31 lowercase letters, digits or hyphens, starting with a letter (e.g. veo-dl).`);
+  }
+  return raw;
+}
+
+export function aliasFiles(binDir, name, platform = process.platform) {
+  if (platform === 'win32') {
+    return [path.join(binDir, name), path.join(binDir, `${name}.cmd`), path.join(binDir, `${name}.ps1`)];
+  }
+  return [path.join(binDir, name)];
+}
+
+function posixWrapper(name) {
+  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
+}
+
+function windowsCmdWrapper(name) {
+  return `@echo off\r\nREM ${ALIAS_MARKER}: ${name}\r\nveo %*\r\n`;
+}
+
+function windowsShWrapper(name) {
+  return `#!/bin/sh\n# ${ALIAS_MARKER}: ${name}\nexec veo "$@"\n`;
+}
+
+function windowsPsWrapper(name) {
+  return `# ${ALIAS_MARKER}: ${name}\nveo @args\n`;
+}
+
+async function exists(file, { statImpl = stat } = {}) {
+  try {
+    const info = await statImpl(file);
+    return info.isFile();
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function isManaged(file, { readFileImpl = readFile } = {}) {
+  try {
+    const text = await readFileImpl(file, 'utf8');
+    return text.slice(0, 4096).includes(ALIAS_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveBinDir({ binDir, platform = process.platform, env = process.env, find = findOnPath } = {}) {
+  if (binDir) return path.resolve(binDir);
+  const found = await find(['veo'], { platform, env });
+  if (!found) {
+    throw new Error('Could not locate the veo command on PATH. Install veo globally (npm install -g veodl) or pass --bin-dir <path>.');
+  }
+  return path.dirname(found);
+}
+
+export async function aliasStatus(name, { binDir, platform = process.platform, ...fs } = {}) {
+  const files = aliasFiles(binDir, name, platform);
+  const present = [];
+  let managed = false;
+  for (const file of files) {
+    if (await exists(file, fs)) {
+      present.push(file);
+      if (await isManaged(file, fs)) managed = true;
+    }
+  }
+  return { name, builtin: BUILTIN_ALIASES.includes(name), present: present.length > 0, managed, paths: present };
+}
+
+function baseNameOf(file, platform) {
+  const base = path.basename(file);
+  if (platform === 'win32') {
+    if (base.toLowerCase().endsWith('.cmd')) return base.slice(0, -4);
+    if (base.toLowerCase().endsWith('.ps1')) return base.slice(0, -4);
+  }
+  return base;
+}
+
+export async function listAliases({ binDir, platform = process.platform, builtins = BUILTIN_ALIASES, readdirImpl = readdir, readFileImpl = readFile, statImpl = stat } = {}) {
+  const resolved = await resolveBinDir({ binDir, platform });
+  const entries = [];
+  for (const name of builtins) {
+    entries.push(await aliasStatus(name, { binDir: resolved, platform, readFileImpl, statImpl }));
+  }
+  const known = new Set(entries.map(entry => entry.name));
+  let files = [];
+  try {
+    files = await readdirImpl(resolved, { withFileTypes: true });
+  } catch (error) {
+    throw new Error(`Cannot list the command directory ${resolved}: ${readableError(error)}`);
+  }
+  for (const entry of files) {
+    if (!entry.isFile()) continue;
+    const full = path.join(resolved, entry.name);
+    let text = '';
+    try {
+      text = String(await readFileImpl(full, 'utf8')).slice(0, 4096);
+    } catch {
+      continue;
+    }
+    if (!text.includes(ALIAS_MARKER)) continue;
+    const base = baseNameOf(entry.name, platform);
+    try {
+      validateAliasName(base);
+    } catch {
+      continue;
+    }
+    if (known.has(base)) {
+      const existing = entries.find(item => item.name === base);
+      if (existing) existing.managed = true;
+      continue;
+    }
+    known.add(base);
+    entries.push({ name: base, builtin: false, present: true, managed: true, paths: [full] });
+  }
+  return { binDir: resolved, aliases: entries.sort((a, b) => a.name.localeCompare(b.name)) };
+}
+
+export async function addAlias(name, { binDir, platform = process.platform, force = false, writeFileImpl = writeFile, statImpl = stat, chmodImpl = chmod, mkdirImpl = mkdir } = {}) {
+  const valid = validateAliasName(name);
+  if (valid === 'veo') throw new Error('veo is already the main command.');
+  const resolved = await resolveBinDir({ binDir, platform });
+  await mkdirImpl(resolved, { recursive: true });
+  const files = aliasFiles(resolved, valid, platform);
+  const present = [];
+  for (const file of files) {
+    if (await exists(file, { statImpl })) present.push(file);
+  }
+  if (present.length && !force) {
+    throw new Error(`${valid} already exists (${present.map(file => path.basename(file)).join(', ')}). Use --force to replace it.`);
+  }
+  for (const file of present) await rm(file, { force: true });
+  if (platform === 'win32') {
+    await writeFileImpl(files[0], windowsShWrapper(valid), { mode: 0o755 });
+    await writeFileImpl(files[1], windowsCmdWrapper(valid));
+    await writeFileImpl(files[2], windowsPsWrapper(valid));
+  } else {
+    await writeFileImpl(files[0], posixWrapper(valid), { mode: 0o755 });
+    try {
+      await chmodImpl(files[0], 0o755);
+    } catch {
+      // Non-POSIX filesystems may ignore modes; the shebang still works.
+    }
+  }
+  return { name: valid, binDir: resolved, paths: aliasFiles(resolved, valid, platform) };
+}
+
+export async function removeAlias(name, { binDir, platform = process.platform, statImpl = stat, rmImpl = rm } = {}) {
+  const valid = validateAliasName(name);
+  if (valid === 'veo') throw new Error('Refusing to remove veo itself. Remove veodl or a custom wrapper instead.');
+  const resolved = await resolveBinDir({ binDir, platform });
+  const status = await aliasStatus(valid, { binDir: resolved, platform, statImpl });
+  if (!status.present) throw new Error(`${valid} is not installed in ${resolved}.`);
+  for (const file of status.paths) await rmImpl(file, { force: true });
+  return { name: valid, binDir: resolved, removed: status.paths, builtin: status.builtin };
+}
+
+function parseAliasArgs(args) {
+  let binDir;
+  let force = false;
+  let json = false;
+  const rest = [];
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index];
+    if (token === '--force') force = true;
+    else if (token === '--json') json = true;
+    else if (token === '--bin-dir') {
+      binDir = args[++index];
+      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
+    } else if (token.startsWith('--bin-dir=')) {
+      binDir = token.slice(10) || undefined;
+      if (!binDir) throw new Error('--bin-dir requires a directory. Run veo alias --help for usage.');
+    } else rest.push(token);
+  }
+  return { binDir, force, json, rest };
+}
+
+export async function aliasMain(args = [], { stdout = process.stdout, stderr = process.stderr, ...options } = {}) {
+  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  const { binDir, force, json, rest } = parseAliasArgs(args);
+  const [command, name, ...extra] = rest;
+  if (!command || command === 'list') {
+    if (name || extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
+    if (command === 'list' && extra.length) throw new Error('Usage: veo alias list [--json] (or veo alias --help)');
+    const result = await listAliases({ ...options, binDir });
+    if (json) {
+      stdout.write(`${JSON.stringify(result)}\n`);
+      return 0;
+    }
+    stdout.write(`Command directory: ${result.binDir}\n`);
+    for (const entry of result.aliases) {
+      const kind = entry.builtin ? 'shipped' : 'custom';
+      const state = entry.present ? (entry.managed ? 'wrapper -> veo' : 'installed') : 'missing';
+      stdout.write(`  ${entry.name} (${kind}, ${state})\n`);
+    }
+    const missing = result.aliases.filter(entry => !entry.present).map(entry => entry.name);
+    if (missing.length) stdout.write(`Missing: ${missing.join(', ')} (veo update recreates shipped names).\n`);
+    return 0;
+  }
+  if (command === '-h' || command === '--help') {
+    stdout.write(ALIAS_HELP);
+    return 0;
+  }
+  if (command === 'add') {
+    if (!name || extra.length) throw new Error('Usage: veo alias add <name> [--force] (or veo alias --help)');
+    const created = await addAlias(name, { ...options, binDir, force });
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'added', ...created })}\n`);
+      return 0;
+    }
+    stdout.write(`Alias installed: ${created.name} -> veo (${created.binDir})\n`);
+    stdout.write(`Run "${created.name} --help" to use it. Remove it with: veo alias remove ${created.name}\n`);
+    return 0;
+  }
+  if (command === 'remove' || command === 'rm' || command === 'uninstall') {
+    if (!name || extra.length) throw new Error('Usage: veo alias remove <name> (or veo alias --help)');
+    const removed = await removeAlias(name, { ...options, binDir });
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'removed', ...removed })}\n`);
+      return 0;
+    }
+    stdout.write(`Alias removed: ${removed.name} (${removed.removed.length} file(s) in ${removed.binDir})\n`);
+    if (removed.builtin) stdout.write('Note: veo update recreates the shipped veodl name.\n');
+    return 0;
+  }
+  throw new Error(`Unknown alias command: ${cleanText(command)}. Use: veo alias list | veo alias add <name> | veo alias remove <name>`);
+}

package/src/cli.js

@@ -66,7 +66,7 @@ Options:
   -h, --help               Show help (also: veo help)
 
 Commands:
-  veo update [--check]     Update veo itself with npm
+  veo update|up [--check]   Update veo itself with npm (up is a short alias)
   veo backend update       Install a newer yt-dlp release (see veo backend --help)
   veo doctor               Diagnose the local setup
   veo flush                Stop veo runs and clear temporary downloads and jobs
@@ -78,6 +78,8 @@ Commands:
   veo inspect <file>        Read media metadata; --check-audio measures audio signal
   veo inspect run <id>     Inspect saved files from a finished run by its id
   veo stop [id]            Stop one run, or every active run
+  veo alias list|add|remove  Manage extra command names (wrappers calling veo)
+  veo uninstall [-p <name>]  Remove one alias, or everything with --yes
   veo version              Show the installed version
   veo config edit|path|profiles|check|show|reset  Manage defaults and named profiles
   veo config edit [--external|--terminal]      Choose the configuration editor
@@ -291,8 +293,28 @@ export async function main(args = process.argv.slice(2), { config } = {}) {
     }
     // The command's own validation reports configuration errors.
   }
-  if (['stats', 'history', 'flush', 'runs', 'inspect', 'stop', 'update', 'upgrade', 'check', 'doctor', 'backend'].includes(args[0])) args = display.remaining;
-  return withOutputSettings(color, () => runMain(args, { config }));
+  if (['stats', 'history', 'flush', 'runs', 'inspect', 'stop', 'update', 'up', 'upgrade', 'check', 'doctor', 'backend', 'alias', 'uninstall'].includes(args[0])) args = display.remaining;
+  const code = await withOutputSettings(color, () => runMain(args, { config }));
+  // One throttled (once per day) update hint after every successful command.
+  // Failures, cancellations, help/version output and the update commands
+  // themselves never trigger it; VEO_NO_UPDATE_CHECK=1 disables it for scripts.
+  if (code === 0 && shouldUpdateNotice(args)) {
+    try {
+      const notice = await maybeUpdateNotice({ currentVersion: await packageVersion() });
+      if (notice) process.stderr.write(`${notice}\n`);
+    } catch {
+      // Informational only: a broken notice must never fail the command.
+    }
+  }
+  return code;
+}
+
+// Help, version and the update commands report versions themselves;
+// anything else earns the daily update hint on success.
+export function shouldUpdateNotice(args = []) {
+  if (args.includes('-h') || args.includes('--help') || args.includes('-v') || args.includes('--version')) return false;
+  if (['update', 'up', 'upgrade', 'check', 'version', 'help'].includes(args[0])) return false;
+  return true;
 }
 
 async function runMain(args, { config }) {
@@ -334,8 +356,9 @@ async function runMain(args, { config }) {
   }
   const { cleanupDownloadCache } = await import('./download-cache.js');
   await cleanupDownloadCache().catch(error => stderr.write(`veo: Could not clean expired local downloads: ${readableError(error)}\n`));
-  // update/upgrade/check subcommands are handled before URL validation.
-  if (['update', 'upgrade', 'check'].includes(args[0])) {
+  // update/upgrade/up/check subcommands are handled before URL validation.
+  if (['update', 'up', 'upgrade', 'check'].includes(args[0])) {
+    if (args[0] === 'up') args = ['update', ...args.slice(1)];
     if (args[0] === 'check' && args[1] !== 'update') {
       stdout.write(UPDATE_HELP);
       return 0;
@@ -364,6 +387,24 @@ async function runMain(args, { config }) {
       return 1;
     }
   }
+  if (args[0] === 'alias') {
+    try {
+      const { aliasMain } = await import('./alias.js');
+      return await aliasMain(args.slice(1));
+    } catch (error) {
+      stderr.write(`veo: ${readableError(error)}\n`);
+      return 1;
+    }
+  }
+  if (args[0] === 'uninstall') {
+    try {
+      const { uninstallMain } = await import('./uninstall.js');
+      return await uninstallMain(args.slice(1));
+    } catch (error) {
+      stderr.write(`veo: ${readableError(error)}\n`);
+      return 1;
+    }
+  }
   const reporter = createReporter();
   const controller = new AbortController();
   const cancel = () => controller.abort();
@@ -438,10 +479,7 @@ async function runMain(args, { config }) {
     const { createStatsRecorder } = await import('./stats.js');
     const { createHistoryRecorder } = await import('./history.js');
     const result = await runJob(options, { download, reporter, signal: controller.signal, openFile, items: retryItems, jobFile: jobFile || undefined, runId: run?.id, recordStats: createStatsRecorder(), recordHistory: createHistoryRecorder() });
-    if (result !== 0) return result;
-    const notice = await maybeUpdateNotice({ currentVersion: await packageVersion() });
-    if (notice) stderr.write(`${notice}\n`);
-    return 0;
+    return result;
   } catch (error) {
     reporter.fail(controller.signal.aborted);
     stderr.write(`veo: ${readableError(error)}\n`);

package/src/doctor.js

@@ -249,7 +249,7 @@ export async function collectChecks({
     }
     if (latest) {
       const newer = compareVersions(latest, version) > 0;
-      push(newer ? 'warn' : 'ok', 'veo version', newer ? `${version} — ${latest} is available (run: veo update)` : `${version} is the latest release`);
+      push(newer ? 'warn' : 'ok', 'veo version', newer ? `${version} — ${latest} is available (run: veo up)` : `${version} is the latest release`);
     }
   }
   return checks;

package/src/output.js

@@ -27,7 +27,7 @@ export function formatOutput(text, stream, enabled = settings.getStore()?.enable
     if (!line.trim() || /\x1b/.test(line)) return line;
     const value = line.trim();
     let role = 'muted';
-    if (/^(?:veo (?:stats|history|runs|stop|doctor|flush|update|backend)\b|veo \d[^ ]* doctor|ID\s+PID\s+STATE|Usage:|Options:|Commands:|Examples:|\d+\. )/.test(value)) role = 'title';
+    if (/^(?:veo (?:stats|history|runs|stop|doctor|flush|update|backend|alias|uninstall)\b|veo \d[^ ]* doctor|ID\s+PID\s+STATE|Usage:|Options:|Commands:|Examples:|\d+\. )/.test(value)) role = 'title';
     if (/^(?:\[?OK\]?\s|Saved:|Flushed:|Stopped\b|Removed\b|Config OK:|Statistics reset|Managed tools are ready)|\bis up to date\b|\bupdated to\b|\binstalled and will be used\b/i.test(value)) role = 'success';
     if (/^(?:\[?FAIL\]?\s|Error:|veo: (?!note:))|Status:\s*(?:failed|cancelled)/i.test(value)) role = 'error';
     if (/Status:\s*saved/.test(value)) role = 'success';

package/src/uninstall.js

@@ -0,0 +1,221 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { rm } from 'node:fs/promises';
+import { commandOutput } from './output.js';
+import { cacheBase, configBase } from './paths.js';
+import { cleanText, readableError } from './utils.js';
+import { removeAlias, validateAliasName, listAliases } from './alias.js';
+
+const PACKAGE = 'veodl';
+
+export const UNINSTALL_HELP = `veo uninstall - remove veo completely or one command alias
+
+Usage:
+  veo uninstall [-p|--prefix <name>] [--json]
+                               Remove one alias (e.g. veo uninstall -p veodl)
+  veo uninstall [--yes] [--keep-cache] [--keep-config] [--keep-aliases] [--json]
+                               Remove everything: aliases, package, cache, config
+  veo uninstall --help         Show this help
+
+With -p/--prefix, only that alias is deleted; veo itself stays installed.
+Without -p, veo prints what would be removed. Add --yes to delete everything:
+custom wrappers created with veo alias add, the ${PACKAGE} package itself
+(commands veo, veodl) with npm, veo's cache directory (downloads, jobs,
+backend tools, history, statistics) and the config file. Use --keep-cache,
+--keep-config or --keep-aliases to preserve one part. The config file is
+deleted by default; its path is shown before and after.
+`;
+
+export function npmUninstallCommand({ platform = process.platform } = {}) {
+  const args = ['uninstall', '-g', PACKAGE];
+  if (platform === 'win32') {
+    return {
+      command: 'cmd.exe',
+      args: ['/d', '/s', '/c', `npm ${args.join(' ')}`],
+      shell: false,
+      windowsVerbatimArguments: true,
+    };
+  }
+  return { command: 'npm', args, shell: false };
+}
+
+export function runNpmUninstall({ spawnImpl = spawn, platform = process.platform, signal, timeoutMs = 600_000 } = {}) {
+  const { command, args, ...spawnOptions } = npmUninstallCommand({ platform });
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { ...spawnOptions, stdio: 'inherit', windowsHide: true, signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs) });
+    child.once('error', reject);
+    child.once('close', resolve);
+  });
+}
+
+function parseUninstallArgs(args) {
+  let prefix;
+  let yes = false;
+  let keepCache = false;
+  let keepConfig = false;
+  let keepAliases = false;
+  let json = false;
+  let binDir;
+  const rest = [];
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index];
+    if (token === '-p' || token === '--prefix') {
+      prefix = args[++index];
+      if (!prefix) throw new Error('--prefix requires an alias name. Use: veo uninstall -p veodl');
+    } else if (token.startsWith('-p=')) {
+      prefix = token.slice(3) || undefined;
+      if (!prefix) throw new Error('--prefix requires an alias name. Use: veo uninstall -p veodl');
+    } else if (token.startsWith('--prefix=')) {
+      prefix = token.slice(9) || undefined;
+      if (!prefix) throw new Error('--prefix requires an alias name. Use: veo uninstall -p veodl');
+    } else if (token === '--yes') yes = true;
+    else if (token === '--purge') {
+      // Deprecated: full cleanup is now the default. Kept so older commands keep working.
+    } else if (token === '--keep-cache') keepCache = true;
+    else if (token === '--keep-config') keepConfig = true;
+    else if (token === '--keep-aliases') keepAliases = true;
+    else if (token === '--json') json = true;
+    else if (token === '--bin-dir') {
+      binDir = args[++index];
+      if (!binDir) throw new Error('--bin-dir requires a directory.');
+    } else if (token.startsWith('--bin-dir=')) {
+      binDir = token.slice(10) || undefined;
+      if (!binDir) throw new Error('--bin-dir requires a directory.');
+    } else rest.push(token);
+  }
+  return { prefix, yes, keepCache, keepConfig, keepAliases, json, binDir, rest };
+}
+
+export async function uninstallMain(args = [], {
+  stdout = process.stdout,
+  stderr = process.stderr,
+  platform = process.platform,
+  env = process.env,
+  spawnImpl = spawn,
+  rmImpl = rm,
+  cacheRoot,
+  configFile,
+  listImpl = listAliases,
+  removeImpl = removeAlias,
+} = {}) {
+  [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  const { prefix, yes, keepCache, keepConfig, keepAliases, json, binDir, rest } = parseUninstallArgs(args);
+  if (rest.includes('-h') || rest.includes('--help')) {
+    stdout.write(UNINSTALL_HELP);
+    return 0;
+  }
+  if (rest.length) throw new Error(`Unknown option for veo uninstall: ${rest.join(' ')}. Use: veo uninstall --help`);
+
+  if (prefix) {
+    if (keepCache || keepConfig || keepAliases) throw new Error('--keep-* cannot be combined with --prefix. Remove one alias or uninstall veo itself.');
+    const valid = validateAliasName(prefix);
+    const removed = await removeImpl(valid, { binDir, platform, env });
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'removed', ...removed })}\n`);
+      return 0;
+    }
+    stdout.write(`Alias removed: ${removed.name} (${removed.removed.length} file(s) in ${removed.binDir})\n`);
+    if (removed.builtin) stdout.write('Note: veo update recreates the shipped veodl name.\n');
+    return 0;
+  }
+
+  const cache = cacheRoot || cacheBase({ platform, env });
+  const config = configFile || path.join(configBase({ platform, env }), 'config.json');
+  const manual = `npm uninstall -g ${PACKAGE}`;
+
+  // Custom wrappers first so the plan names them; npm removes veo/veodl itself.
+  let customAliases = [];
+  let aliasDir = binDir ? path.resolve(binDir) : null;
+  try {
+    const listed = await listImpl({ binDir: binDir || undefined, platform, env });
+    aliasDir = listed.binDir;
+    customAliases = listed.aliases.filter(entry => entry.present && entry.managed && !entry.builtin).map(entry => entry.name);
+  } catch {
+    // No bin directory (e.g. running from source without a global install):
+    // npm uninstall still works, alias cleanup is reported as skipped.
+  }
+
+  if (!yes) {
+    if (json) {
+      stdout.write(`${JSON.stringify({ status: 'planned', package: PACKAGE, manual, aliases: customAliases, binDir: aliasDir, cache, config })}\n`);
+      return 0;
+    }
+    stdout.write(`This removes everything: the ${PACKAGE} package with npm (commands veo, veodl).\n`);
+    if (!keepAliases) {
+      stdout.write(customAliases.length
+        ? `Custom wrappers to delete: ${customAliases.join(', ')} (${aliasDir})\n`
+        : `Custom wrappers: none found${aliasDir ? ` (${aliasDir})` : ''}.\n`);
+    }
+    if (!keepCache) stdout.write(`Cache to delete: ${cache}\n`);
+    if (!keepConfig) stdout.write(`Config to delete: ${config}\n`);
+    if (keepCache || keepConfig || keepAliases) {
+      const kept = [
+        keepAliases && 'aliases',
+        keepCache && 'cache',
+        keepConfig && 'config',
+      ].filter(Boolean).join(', ');
+      stdout.write(`Kept: ${kept}.\n`);
+    }
+    const keepFlags = `${keepAliases ? ' --keep-aliases' : ''}${keepCache ? ' --keep-cache' : ''}${keepConfig ? ' --keep-config' : ''}`;
+    stdout.write(`Run with --yes to proceed: veo uninstall --yes${keepFlags}\n`);
+    stdout.write(`Manual command: ${manual}\n`);
+    return 0;
+  }
+
+  let code;
+  try {
+    stdout.write(`Uninstalling ${PACKAGE} with npm…\n`);
+    code = await runNpmUninstall({ spawnImpl, platform, signal: AbortSignal.timeout(600_000) });
+  } catch (error) {
+    const reason = error.code === 'ENOENT' ? 'npm was not found. Install Node.js/npm, or uninstall manually.' : `Could not run npm: ${readableError(error)}`;
+    stderr.write(`veo: ${reason}\nManual command: ${manual}\n`);
+    return 1;
+  }
+  if (code !== 0) {
+    stderr.write(`veo: npm exited with code ${code}. Uninstall manually with: ${manual}\n`);
+    return 1;
+  }
+
+  const removedAliases = [];
+  if (!keepAliases) {
+    for (const name of customAliases) {
+      try {
+        await removeImpl(name, { binDir: aliasDir, platform, env });
+        removedAliases.push(name);
+      } catch (error) {
+        stderr.write(`veo: removed the package but could not delete alias ${name}: ${readableError(error)}\n`);
+        return 1;
+      }
+    }
+  }
+  let cacheDeleted = false;
+  if (!keepCache) {
+    try {
+      await rmImpl(cache, { recursive: true, force: true });
+      cacheDeleted = true;
+    } catch (error) {
+      stderr.write(`veo: removed the package but could not delete the cache ${cache}: ${readableError(error)}\n`);
+      return 1;
+    }
+  }
+  let configDeleted = false;
+  if (!keepConfig) {
+    try {
+      await rmImpl(config, { force: true });
+      configDeleted = true;
+    } catch (error) {
+      stderr.write(`veo: removed the package but could not delete the config ${config}: ${readableError(error)}\n`);
+      return 1;
+    }
+  }
+  if (json) {
+    stdout.write(`${JSON.stringify({ status: 'uninstalled', package: PACKAGE, aliases: removedAliases, binDir: aliasDir, cacheDeleted, cache, configDeleted, config })}\n`);
+    return 0;
+  }
+  stdout.write(`veo uninstalled (${PACKAGE}).`);
+  if (!keepAliases) stdout.write(removedAliases.length ? ` Aliases deleted: ${removedAliases.join(', ')}.` : ' No custom wrappers found.');
+  stdout.write(cacheDeleted ? ` Cache deleted: ${cache}.` : ` Cache kept: ${cache}.`);
+  stdout.write(configDeleted ? ` Config deleted: ${config}.` : ` Config kept: ${config}.`);
+  stdout.write('\n');
+  return 0;
+}

package/src/updater.js

@@ -17,6 +17,7 @@ export const UPDATE_HELP = `veo update - keep veo current
 Usage:
   veo update               Install the latest version with npm
   veo update --check       Only check whether a newer version exists
+  veo up                   Short alias for veo update (also: veo up --check)
   veo upgrade              Alias for veo update
   veo check update         Alias for veo update --check
 
@@ -95,7 +96,7 @@ export async function maybeUpdateNotice({
   try {
     latest = await fetchLatestVersion({ fetchImpl, registry, timeoutMs });
     if (compareVersions(latest, currentVersion) > 0) {
-      message = `Update available: veo ${latest} (you have ${currentVersion}). Run: veo update`;
+      message = `Update available: veo ${latest} (you have ${currentVersion}). Run: veo up`;
     }
   } catch {
     latest = null; // Unreachable registry still consumes the throttle interval.
@@ -158,7 +159,7 @@ export async function packageVersion() {
 }
 
 /**
- * Implements `veo update [--check]`, `veo upgrade`, and `veo check update`.
+ * Implements `veo update [--check]`, `veo up`, `veo upgrade`, and `veo check update`.
  * Returns the process exit code. Deps are injectable for tests.
  */
 export async function updateMain(args, {
@@ -174,6 +175,7 @@ export async function updateMain(args, {
   activeBackend,
 } = {}) {
   [args, stdout, stderr] = commandOutput(args, stdout, stderr);
+  if (args[0] === 'up') args = ['update', ...args.slice(1)];
   current = current ?? await packageVersion();
   const isCheckCommand = args[0] === 'check';
   const rest = isCheckCommand ? args.slice(2) : args.slice(1);
@@ -194,7 +196,7 @@ export async function updateMain(args, {
   }
   const newer = compareVersions(latest, current) > 0;
   if (checkOnly) {
-    stdout.write(newer ? `Update available: veo ${latest} (you have ${current}). Run: veo update\n` : `${currentText} is up to date.\n`);
+    stdout.write(newer ? `Update available: veo ${latest} (you have ${current}). Run: veo up\n` : `${currentText} is up to date.\n`);
     return 0;
   }
   if (newer) {