@uplift-beyond/upex 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uplift Beyond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,328 @@
-# Temporary Holding Version
+# ⚡ upex: Personal File Shortcut Manager
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A professional Node.js CLI tool that lets you register named aliases for folder paths and instantly open them in the file explorer or a specified IDE/app.
+
+## Installation
+
+```bash
+npm i -g @uplift-beyond/upex
+```
+
+From source:
+
+```bash
+npm install
+
+# Link globally so you can use "upex" anywhere
+npm link
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `upex add <name> [path]` | Register a folder shortcut (defaults to current directory) |
+| `upex add <name> <app> --app` | Register an app shortcut (the path is the executable) |
+| `upex add <name> "<command>" --cmd` | Register a command line (runs in a terminal window) |
+| `upex add <name> <url> --url` | Register a URL shortcut (opens in the browser) |
+| `upex add <name> [path] --tag a,b` | Attach tags while registering |
+| `upex` | Open the interactive shortcut selector and choose shortcut/app |
+| `upex --app <app>` | Open the interactive selector with a preselected app |
+| `upex <name>` | Open shortcut in Explorer / default app (or launch stored app/URL) |
+| `upex <name> <app>` | Open in a specific app (vscode, cmd, open, or a custom app) |
+| `upex <name>/<sub>` | Open (or `cd` via the wrapper) a folder inside a shortcut, e.g. `upex web/src` |
+| `upex -` / `upex last` | Reopen the most recently used shortcut |
+| `upex go <name> [start...]` | Print the path (cd via shell wrapper); extra args run as a command in the folder |
+| `upex cmd <name> [count] [start]` | Open N terminals, optionally running a start command |
+| `upex run <name> [script]` | Run a package.json script in a terminal (lists scripts if none given) |
+| `upex tag <name> [tags...]` | List all tags, show/add tags, or remove with `-r` / `--clear` |
+| `upex open <tag>` | Open every shortcut carrying a tag |
+| `upex ws [name\|add\|rm] ...` | Open or manage workspaces (sets of shortcut+app pairs) |
+| `upex export [file]` | Export shortcuts + config as a JSON bundle (stdout if no file) |
+| `upex import <file> [--replace]` | Import a bundle (merge by default) |
+| `upex list [tag] [--git]` | Show all saved shortcuts (filter by tag; `--git` adds a branch column) |
+| `upex remove <name>` | Delete a saved shortcut |
+| `upex rename <old> <new>` | Rename a shortcut |
+| `upex edit <name> [path]` | Update a shortcut's path (defaults to cwd) |
+| `upex edit <name> --opener <app>` | Open this shortcut in `<app>` by default (`--no-opener` clears; also on `add`) |
+| `upex copy <name>` | Copy shortcut path to clipboard |
+| `upex app [alias] [command]` | Manage custom openers (list / add / `--remove`) |
+| `upex check [--prune]` | Report broken paths (`--prune` removes them) |
+| `upex doctor` | Check the store, openers, shell wrapper and completion |
+| `upex ui [--port <n>] [--no-open]` | Manage shortcuts and workspaces in the browser |
+| `upex completion [shell]` | Print a shell completion script (bash/zsh/fish/powershell) |
+| `upex setup [cmd]` | Shell integration; `setup cmd` installs the cmd.exe wrapper |
+| `upex help` | Show all available commands |
+
+## Supported Apps
+
+| Alias | App |
+|---|---|
+| `vscode` / `code` | VS Code |
+| `webstorm` | WebStorm |
+| `cmd` | Command Prompt (Windows) / Terminal |
+| `claude` | Terminal running Claude Code (`claude`) |
+| `finder` / `explorer` | System File Manager (reveals a file shortcut) |
+| `open` | OS default handler (opens a file in its default app) |
+| `copy` | Copy the path to the clipboard |
+
+Add your own openers with `upex app`:
+
+```bash
+upex app cursor cursor          # register "cursor" -> the cursor command
+upex webapp cursor              # open a shortcut in Cursor
+upex app                        # list custom apps
+upex app cursor --remove        # remove one
+```
+
+## Examples
+
+```bash
+# Save current directory as "myproject"
+upex add myproject
+
+# Save a specific path
+upex add webapp /Users/me/projects/webapp
+
+# Open in file explorer
+upex webapp
+
+# Open in VS Code
+upex webapp vscode
+
+# Open in Command Prompt (Windows, cwd set to path)
+upex webapp cmd
+
+# Fuzzy matching works: "webap" resolves to "webapp"
+upex webap vscode
+
+# Register an app shortcut (the path is the executable, --app is a flag)
+upex add chrome "C:\Program Files\Google\Chrome\Application\chrome.exe" --app
+upex chrome          # launches Chrome
+
+# Register a command line; it runs in a new terminal window (starts in your home folder)
+upex add dev "cd /d E:\projects\app && npm run dev" --cmd
+upex dev
+
+# Save a file (opens in its default app; "explorer" reveals it in its folder)
+upex add notes "E:\docs\notes.md"
+upex notes           # opens notes.md
+upex notes explorer  # reveals it in Explorer
+
+# Open a shortcut in 3 terminal windows
+upex cmd webapp 3
+
+# Open a terminal at webapp and run "claude" in it (window stays open)
+upex cmd webapp claude
+
+# Two terminals, each running "dir"
+upex cmd webapp 2 dir
+
+# cd into a shortcut (with the shell wrapper from `upex setup`)
+upex go webapp
+
+# cd into a shortcut and run a command there
+upex go webapp npm run dev
+
+# Open the interactive selector
+upex
+
+# List all shortcuts
+upex list
+
+# Check for broken paths
+upex check
+```
+
+## Tags & Groups
+
+Attach tags to organize shortcuts, filter the list, and open a whole group at once.
+
+```bash
+upex add webapp --tag work,web     # tag while adding
+upex tag webapp ci                 # add a tag later
+upex tag webapp -r web             # remove a tag (--clear drops all)
+upex tag                           # list every tag with counts
+upex list work                     # only #work shortcuts
+upex open work                     # open every #work shortcut in its default opener
+```
+
+## Workspaces
+
+A workspace is a named set of shortcut+app pairs opened together, e.g. code + a terminal + a browser tab.
+
+```bash
+upex ws add dev webapp vscode      # webapp in VS Code
+upex ws add dev webapp cmd         # ...and a terminal
+upex ws add dev docs open          # ...and a URL/file shortcut in its default opener
+upex ws                            # list workspaces
+upex ws dev                        # open the whole workspace
+upex ws rm dev webapp              # drop one entry (omit the shortcut to delete the workspace)
+```
+
+A `cmd` entry accepts the same `[count] [start...]` tail as `upex cmd`, so a workspace can boot a terminal straight into a command (flags pass through):
+
+```bash
+upex ws add dev webapp cmd claude --model sonnet   # terminal running claude
+upex ws add dev webapp cmd 2 npm run dev           # two terminals running "npm run dev"
+```
+
+## URL Shortcuts, run & last
+
+```bash
+upex add gh github.com --url       # bare hosts get https:// automatically
+upex gh                            # opens in the browser
+
+upex run webapp                    # list package.json scripts (npm/pnpm/yarn/bun auto-detected)
+upex run webapp dev                # open a terminal running "<pm> run dev" at webapp
+
+upex -                             # reopen the most recently used shortcut (alias: upex last)
+```
+
+## Backup & Sync
+
+`export` writes a JSON bundle of your shortcuts and config; `import` merges it back (or `--replace`).
+
+```bash
+upex export ~/upex-backup.json     # or omit the file to print to stdout
+upex import ~/upex-backup.json     # merge (incoming wins on name clash)
+upex import backup.json --replace  # replace everything
+```
+
+`upex list --git` adds a column with each folder's current git branch (yellow `branch*` when the working tree is dirty, `--` when it isn't a repo). It's off by default.
+
+## Interactive Mode
+
+Run `upex` with no arguments to open the interactive selector. Shortcuts are ordered by frecency (most-used and most-recent first).
+
+- `Up` / `Down` -- move through shortcuts
+- `Left` / `Right` -- change the selected app (starts on the shortcut's default opener)
+- `Ctrl+Up` / `Ctrl+Down` -- terminal count when a terminal opener (cmd, claude) is selected
+- `Tab` -- cycle the Shortcuts (folders), Apps (app + URL shortcuts) and Workspaces views (Enter opens the whole workspace, `Ctrl+D` deletes it)
+- `Enter` -- open the selected shortcut in the selected app
+- Type -- fuzzy-filter the list
+- `Ctrl+A` -- add a shortcut for the current directory
+- `Ctrl+E` -- edit the selected shortcut's path
+- `Ctrl+R` -- rename the selected shortcut
+- `Ctrl+D` -- delete the selected shortcut (confirm with `y`)
+- `Esc` -- cancel
+
+## Web UI
+
+Run `upex ui` to open a local page (default `http://127.0.0.1:4545`, a free port if that one is busy) where you can add, edit, rename, tag, delete, copy and open shortcuts, set a default opener, open terminals with a window count and start command, build, reorder and rename workspaces, and remove missing paths. Lists sort by most used (or A to Z) and re-check paths when you come back to the page. Folders, apps (app, command and URL shortcuts) and workspaces each get their own tab. Press `/` to search, `n` for a new shortcut or app. Stop it with `Ctrl+C`.
+
+It only listens on 127.0.0.1 and every request needs a token that is new each run, so other sites can't use it. With `--no-open`, open the link it prints (it carries the token).
+
+## Shell Completion
+
+Enable tab-completion of command and shortcut names:
+
+```bash
+# bash / zsh (add to ~/.bashrc or ~/.zshrc)
+eval "$(upex completion bash)"
+
+# PowerShell (add to $PROFILE)
+upex completion powershell | Out-String | Invoke-Expression
+```
+
+## Shell Integration (cd support)
+
+Because a Node.js process can't change your shell's directory, add this wrapper function for instant `cd` behavior:
+
+### Bash / Zsh (`~/.bashrc` or `~/.zshrc`)
+
+```bash
+upex() {
+  if [ "$1" = "go" ] && [ -n "$2" ]; then
+    if result=$(command upex go "$2" 2>/dev/null) && cd "$result"; then
+      shift 2
+      [ $# -eq 0 ] || "$@"
+      return
+    fi
+  fi
+  if [ "$1" != "" ] && [ "$2" = "" ] && result=$(command upex __resolve "$1" 2>/dev/null); then
+    cd "$result"
+  else
+    command upex "$@"
+  fi
+}
+```
+
+### Command Prompt (cmd.exe)
+
+```cmd
+upex setup cmd
+```
+
+Installs an `upex.bat` wrapper next to the npm shim. `.bat` beats `.cmd` in PATHEXT resolution, and a `cd` inside a batch file persists in the parent shell, so `upex go <name>` and bare `upex <name>` cd directly. `upex go <name> <command...>` cds and then runs the command in that folder (e.g. `upex go webapp npm run dev`). Works immediately, no profile or restart needed.
+
+### PowerShell (`$PROFILE`)
+
+```powershell
+function upex {
+  if ($args.Count -ge 2 -and $args[0] -eq 'go') {
+    $result = & upex.ps1 go $args[1] 2>$null
+    if ($LASTEXITCODE -eq 0 -and $result) {
+      Set-Location $result
+      $rest = @($args | Select-Object -Skip 2)
+      if ($rest.Count) { Invoke-Expression ($rest -join ' ') }
+      return
+    }
+  }
+  if ($args.Count -eq 1) {
+    $result = & upex.ps1 __resolve $args[0] 2>$null
+    if ($LASTEXITCODE -eq 0 -and $result) {
+      Set-Location $result
+      return
+    }
+  }
+  & upex.ps1 @args
+}
+```
+
+## Storage
+
+Shortcuts are stored in `~/.upex/links.json` and created automatically on first use.
+
+Each entry is an object with optional fields:
+
+```json
+{
+  "webapp": { "path": "E:\\projects\\webapp", "opener": "vscode", "uses": 12, "lastUsed": 1752710400000 },
+  "chrome": { "app": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" }
+}
+```
+
+`opener` is the default opener for `upex <name>` (set with `--opener`). `uses` / `lastUsed` are written automatically and drive the interactive selector's frecency ordering.
+
+Legacy string entries (`"name": "/path"`) are auto-migrated on read.
+
+Config is stored in `~/.upex/config.json`, including custom openers under `apps`:
+
+```json
+{
+  "apps": { "cursor": "cursor", "sublime": "C:\\...\\sublime_text.exe" }
+}
+```
+
+### WebStorm on Windows (without `setx`)
+
+If `upex <name> webstorm` does not find WebStorm, add this file:
+
+```json
+{
+  "webstormPath": "C:\\Program Files\\JetBrains\\WebStorm\\bin\\webstorm64.exe"
+}
+```
+
+Then run:
+
+```bash
+upex <name> webstorm
+```
+
+`setx` is only a Windows command for writing environment variables permanently; it is optional now.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/bin/upex.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { createProgram } from '../src/index.js';
+import { StoreError } from '../src/store.js';
+import * as ui from '../src/ui.js';
+
+// Shorthand: `upex -` reopens the most recently used shortcut.
+const argv = process.argv.slice();
+if (argv[2] === '-') argv[2] = 'last';
+
+const program = createProgram();
+program.parseAsync(argv).catch((err) => {
+  if (!(err instanceof StoreError)) throw err;
+  ui.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,38 @@
-{
-  "name": "@uplift-beyond/upex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@uplift-beyond/upex",
+  "version": "1.5.0",
+  "description": "A personal file shortcut manager: register named aliases for folder paths and instantly open them.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "upex": "./bin/upex.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "keywords": [
+    "cli",
+    "shortcuts",
+    "file-manager",
+    "developer-tools"
+  ],
+  "author": "uplift-beyond.de",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JennyTheGem/upex.git"
+  },
+  "homepage": "https://github.com/JennyTheGem/upex#readme",
+  "bugs": "https://github.com/JennyTheGem/upex/issues",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "fuse.js": "^7.3.0"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,87 @@
+/**
+ * add.js -- Register a new shortcut
+ * Usage: upex add <name> [path]        folder shortcut (defaults to cwd)
+ *        upex add <name> <app> --app   app shortcut (the path IS the executable)
+ *        upex add <name> "<line>" --cmd  command line, run in a terminal window
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { setLink, linkExists, nameError } from '../store.js';
+import { withOpener } from './edit.js';
+import * as ui from '../ui.js';
+
+// "work,personal" -> ["work", "personal"]; undefined -> undefined (leave field off).
+export function parseTags(value) {
+  if (!value) return undefined;
+  const tags = value.split(',').map(t => t.trim()).filter(Boolean);
+  return tags.length ? tags : undefined;
+}
+
+export function registerAdd(program) {
+  program
+    .command('add <name> [target]')
+    .description('Register a shortcut (folder, or an app with --app, a command line with --cmd, or a URL with --url)')
+    .summary('Register a folder, app (--app), command (--cmd) or URL (--url)')
+    .option('--app', 'Treat <target> as an application to launch')
+    .option('--url', 'Treat <target> as a URL to open in the browser')
+    .option('--cmd', 'Treat <target> as a command line to run in a terminal window')
+    .option('-t, --tag <tags>', 'Comma-separated tags to attach')
+    .option('-o, --opener <app>', 'Open this folder shortcut in <app> by default')
+    .action((name, targetPath, options) => {
+      if (options.opener && (options.app || options.url || options.cmd)) {
+        ui.error('A default opener only applies to folder shortcuts.');
+        process.exit(1);
+      }
+
+      const bad = nameError(name);
+      if (bad) {
+        ui.error(bad);
+        process.exit(1);
+      }
+
+      if (linkExists(name)) {
+        ui.warn(`"${name}" already exists. Use "upex edit ${name}" to update.`);
+        return;
+      }
+
+      const tags = parseTags(options.tag);
+
+      // URL shortcut: the positional is a URL, opened in the browser.
+      if (options.url) {
+        if (!targetPath) {
+          ui.error('Provide the URL: upex add <name> <url> --url');
+          process.exit(1);
+        }
+        setLink(name, { url: targetPath, ...(tags && { tags }) });
+        ui.success(`Added: ${name} --> ${targetPath}`);
+        return;
+      }
+
+      // App shortcut: the positional is the executable/command, stored raw.
+      // --cmd: a command line run in a terminal window instead.
+      if (options.app || options.cmd) {
+        if (!targetPath) {
+          ui.error(options.cmd
+            ? 'Provide the command line in quotes: upex add <name> "<command>" --cmd'
+            : 'Provide the app path or command: upex add <name> <app> --app');
+          process.exit(1);
+        }
+        setLink(name, { app: targetPath, ...(options.cmd && { terminal: true }), ...(tags && { tags }) });
+        ui.success(`Added: ${name} --> ${targetPath}`);
+        return;
+      }
+
+      // Folder shortcut (defaults to cwd).
+      const resolved = targetPath ? path.resolve(targetPath) : process.cwd();
+      if (!fs.existsSync(resolved)) {
+        ui.error(`Path does not exist: ${resolved}`);
+        process.exit(1);
+      }
+      let entry = { path: resolved, ...(tags && { tags }) };
+      if (options.opener) entry = withOpener(entry, options.opener);
+      if (!entry) process.exit(1);
+      setLink(name, entry);
+      ui.success(`Added: ${name} --> ${resolved}`);
+    });
+}

package/src/commands/app.js

@@ -0,0 +1,58 @@
+/**
+ * app.js -- Manage user-defined openers stored in ~/.upex/config.json.
+ * Usage: upex app                     -- list custom apps
+ *        upex app <alias> <command>   -- add/update a custom app
+ *        upex app <alias> --remove    -- remove a custom app
+ */
+
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../store.js';
+import * as ui from '../ui.js';
+
+export function registerApp(program) {
+  program
+    .command('app [alias] [command]')
+    .description('Manage custom openers (e.g. "upex app cursor cursor")')
+    .option('--remove', 'Remove the named custom app')
+    .action((alias, command, options) => {
+      const config = loadConfig();
+      const apps = config.apps && typeof config.apps === 'object' ? config.apps : {};
+
+      // No alias: list what's defined.
+      if (!alias) {
+        const entries = Object.entries(apps);
+        if (entries.length === 0) {
+          ui.info('No custom apps. Add one: upex app <alias> <command>');
+          return;
+        }
+        ui.heading('Custom Apps');
+        ui.table(
+          [[chalk.bold('ALIAS'), chalk.bold('COMMAND')], ...entries.map(([a, c]) => [chalk.bold(a), c])],
+          { header: true },
+        );
+        ui.blank();
+        return;
+      }
+
+      if (options.remove) {
+        if (!Object.hasOwn(apps, alias)) {
+          ui.error(`No custom app named "${alias}".`);
+          return;
+        }
+        delete apps[alias];
+        saveConfig({ ...config, apps });
+        ui.success(`Removed custom app: ${alias}`);
+        return;
+      }
+
+      if (!command) {
+        ui.error('Provide a command: upex app <alias> <command>');
+        return;
+      }
+
+      apps[alias] = command;
+      saveConfig({ ...config, apps });
+      ui.success(`Saved custom app: ${alias} --> ${command}`);
+      ui.dim(`Use it: upex <shortcut> ${alias}`);
+    });
+}

package/src/commands/check.js

@@ -0,0 +1,70 @@
+/**
+ * check.js -- Scan shortcuts and report broken paths.
+ * Usage: upex check
+ */
+
+import fs from 'node:fs';
+import chalk from 'chalk';
+import { loadLinks, saveLinks, pruneBroken } from '../store.js';
+import * as ui from '../ui.js';
+
+export function registerCheck(program) {
+  program
+    .command('check')
+    .description('Scan all shortcuts and report broken paths')
+    .option('--prune', 'Remove shortcuts whose folder path no longer exists')
+    .action((options) => {
+      const links = loadLinks();
+      const entries = Object.entries(links);
+
+      if (entries.length === 0) {
+        ui.info('No shortcuts saved.');
+        return;
+      }
+
+      ui.heading('Health Check');
+
+      let brokenCount = 0;
+
+      const rows = [
+        [chalk.bold('NAME'), chalk.bold('PATH'), chalk.bold('STATUS')],
+        ...entries.map(([name, entry]) => {
+          const filepath = entry.path;
+          if (!filepath) {
+            // App-only shortcut, no path to check
+            return [
+              chalk.bold(name),
+              chalk.dim('(app only)'),
+              ui.tag.skip,
+            ];
+          }
+          const exists = fs.existsSync(filepath);
+          if (!exists) brokenCount++;
+          return [
+            chalk.bold(name),
+            exists ? filepath : chalk.dim(filepath),
+            exists ? ui.tag.ok : ui.tag.fail,
+          ];
+        }),
+      ];
+
+      ui.table(rows, { header: true });
+      ui.blank();
+      ui.separator();
+
+      if (brokenCount === 0) {
+        ui.success(`All ${entries.length} shortcut${entries.length === 1 ? '' : 's'} valid.`);
+      } else if (options.prune) {
+        const { kept, removed } = pruneBroken(links);
+        saveLinks(kept);
+        ui.warn(`Pruned ${removed.length} broken shortcut${removed.length === 1 ? '' : 's'}.`);
+        if (removed.length) ui.dim(`Removed: ${removed.join(', ')}`);
+      } else {
+        ui.warn(
+          `${brokenCount} broken / ${entries.length} total.`
+        );
+        ui.dim(`Use "upex check --prune" to remove them, or "upex edit <name> <path>" to fix.`);
+      }
+      ui.blank();
+    });
+}

package/src/commands/cmd.js

@@ -0,0 +1,26 @@
+/**
+ * cmd.js -- Open a shortcut in N terminal windows, optionally running a command.
+ * Usage: upex cmd <name> [count] [start command...]
+ *   upex cmd velora            -- one window at velora
+ *   upex cmd velora 2          -- two windows
+ *   upex cmd velora claude     -- one window running "claude"
+ *   upex cmd velora 2 dir      -- two windows each running "dir"
+ */
+
+import { handleOpen } from './open.js';
+
+export function registerCmd(program) {
+  program
+    .command('cmd <name> [count] [start...]')
+    .description('Open a shortcut in N terminal windows, optionally running a start command')
+    .summary('Open N terminals, optionally running a command')
+    // Let flags after the shortcut (e.g. "claude --model x") pass through as the start command.
+    .enablePositionalOptions()
+    .passThroughOptions()
+    .allowUnknownOption()
+    .action((name, count, start = []) => {
+      // A non-numeric "count" is really the first word of the start command.
+      if (count && !/^\d+$/.test(count)) [count, start] = [1, [count, ...start]];
+      return handleOpen(name, 'cmd', Number(count) || 1, start.join(' '));
+    });
+}