@phnx-labs/agents-cli 1.22.75 → 1.22.76

package/dist/commands/memory.js

@@ -4,6 +4,7 @@
  * Mirrors the skills surface at list / add / remove / view / sync scale.
  * Canonical storage: ~/.agents/memory/ (project > user > system layering).
  */
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { listMemoryFacts, addMemoryFact, removeMemoryFact, readMemoryFact, ensureUserMemoryDir, getUserMemoryDir, syncMemoryToVersionHome, } from '../lib/memory.js';
@@ -42,8 +43,8 @@ export function registerMemoryCommands(program) {
       Format: MEMORY.md index + one <slug>.md file per fact.
     `,
     });
-    memoryCmd
-        .command('list')
+    withAliases(memoryCmd
+        .command('list'), 'list')
         .description('List memory facts from project, user, and system layers')
         .option('--json', 'Emit machine-readable JSON')
         .action((options) => {
@@ -86,9 +87,8 @@ export function registerMemoryCommands(program) {
             console.log(chalk.gray('  Run: agents memory sync  (or agents sync) to fan out'));
         }
     });
-    memoryCmd
-        .command('remove <name>')
-        .alias('rm')
+    withAliases(memoryCmd
+        .command('remove <name>'), 'remove')
         .description('Remove a user-layer memory fact')
         .action((name) => {
         if (removeMemoryFact(name)) {
@@ -99,8 +99,8 @@ export function registerMemoryCommands(program) {
             process.exit(1);
         }
     });
-    memoryCmd
-        .command('view <name>')
+    withAliases(memoryCmd
+        .command('view <name>'), 'view')
         .description('Print a memory fact (winning layer)')
         .action((name) => {
         const fact = readMemoryFact(name, process.cwd());

package/dist/commands/monitors.js

@@ -8,6 +8,7 @@
  * source instead of a clock.
  */
 import chalk from 'chalk';
+import { withAliases } from '../lib/verbs.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
@@ -1184,8 +1185,8 @@ export function registerMonitorsCommands(program) {
         console.log(chalk.gray('  Re-pin with: agents monitors device ' + name + ' --set <device>'));
     });
     // ─── remove ────────────────────────────────────────────────────────────────────
-    monitorsCmd
-        .command('remove [name]')
+    withAliases(monitorsCmd
+        .command('remove [name]'), 'remove')
         .description('Delete a monitor. Stops watching; past fire history remains on disk.')
         .action(async (name) => {
         if (!name) {

package/dist/commands/open.d.ts

@@ -1,18 +1,31 @@
 /**
- * `agents open` — resolve an `agents://` deep link, and manage the OS handler
- * that routes such links here.
+ * `agents _callback` — the machine-only OS callback for `agents://` deep links.
  *
- *   agents open agents://session/<id>     resume that session in a terminal
- *   agents open register                  register the agents:// scheme with the OS
- *   agents open unregister                remove the handler
- *   agents open status                    report whether the handler is registered
+ *   agents _callback agents://session/<id>    resume that session in a terminal
  *
- * A rendered artifact (plan/report) embeds `agents://session/<id>` in its
- * provenance line; clicking it hands the URL to the OS, which invokes
- * `agents open <url>`. This command parses it (lib/deeplink/url.ts) and hands the
- * session id to the existing resume dispatcher, which resolves the owning host
- * and opens the terminal with the cursor in the input bar. The id is passed as
- * argv, never interpolated into a shell.
+ * This is NOT a user command: humans resume with `agents sessions resume`, and
+ * manage the OS URL-scheme handler with `agents setup url-scheme`. The bare-URL
+ * verb exists only because a rendered artifact (plan/report) embeds
+ * `agents://session/<id>` in its provenance line; clicking it hands the URL to
+ * the OS, which invokes the registered handler — `agents _callback <url>`. This
+ * command parses it (lib/deeplink/url.ts) and hands the session id to the
+ * existing resume dispatcher, which resolves the owning host and opens the
+ * terminal with the cursor in the input bar. The id is passed as argv, never
+ * interpolated into a shell.
+ *
+ * The command is hidden. `open` is kept as a HIDDEN alias so machines whose OS
+ * handler was written by an older CLI (which emitted `agents open <url>`) keep
+ * resolving until `agents setup url-scheme register` re-writes the handler to the
+ * `_callback` verb. Dropping `open` would break every previously-registered link.
  */
 import type { Command } from 'commander';
 export declare function registerOpenCommand(program: Command): void;
+/**
+ * Attach `register` / `unregister` / `status` subcommands that manage the
+ * `agents://` OS URL-scheme handler onto `parent`. One implementation, mounted
+ * both under the hidden `_callback` command (back-compat) and under the visible
+ * `agents setup url-scheme` group.
+ */
+export declare function addUrlSchemeSubcommands(parent: Command, opts?: {
+    hidden?: boolean;
+}): void;

package/dist/commands/open.js

@@ -2,18 +2,32 @@ import chalk from 'chalk';
 import { parseAgentsUrl } from '../lib/deeplink/url.js';
 import { registerAgentsUrlScheme, unregisterAgentsUrlScheme, agentsUrlSchemeStatus, } from '../lib/deeplink/register.js';
 export function registerOpenCommand(program) {
-    const open = program
-        .command('open [url]')
-        .description('Resume a session from an agents:// deep link, or register/unregister/status the OS URL-scheme handler.')
+    const callback = program
+        .command('_callback [url]', { hidden: true })
+        .alias('open')
+        .description('OS callback that resumes a session from an agents:// deep link (machine-only; humans use `agents sessions resume`).')
         .action(async (url) => {
         if (!url) {
-            open.help();
+            callback.help();
             return;
         }
         await handleUrl(url);
     });
-    open
-        .command('register')
+    // Back-compat: `agents open register|unregister|status` still work as HIDDEN
+    // subcommands (muscle memory + docs). The canonical, visible home is
+    // `agents setup url-scheme <verb>`, which reuses the SAME builder below.
+    addUrlSchemeSubcommands(callback, { hidden: true });
+}
+/**
+ * Attach `register` / `unregister` / `status` subcommands that manage the
+ * `agents://` OS URL-scheme handler onto `parent`. One implementation, mounted
+ * both under the hidden `_callback` command (back-compat) and under the visible
+ * `agents setup url-scheme` group.
+ */
+export function addUrlSchemeSubcommands(parent, opts = {}) {
+    const hidden = opts.hidden ?? false;
+    parent
+        .command('register', { hidden })
         .description('Register the agents:// URL scheme with the OS so artifact links resume sessions (idempotent).')
         .action(() => {
         const status = registerAgentsUrlScheme();
@@ -25,15 +39,15 @@ export function registerOpenCommand(program) {
             process.exitCode = 1;
         }
     });
-    open
-        .command('unregister')
+    parent
+        .command('unregister', { hidden })
         .description('Remove the agents:// URL scheme handler.')
         .action(() => {
         const status = unregisterAgentsUrlScheme();
         console.log(chalk.gray(status.detail));
     });
-    open
-        .command('status')
+    parent
+        .command('status', { hidden })
         .description('Report whether the agents:// URL scheme handler is registered.')
         .action(() => {
         const status = agentsUrlSchemeStatus();

package/dist/commands/permissions.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
@@ -44,8 +45,8 @@ When to use:
   - Team sync: share permission sets via 'agents permissions add gh:team/perms'
   - Version isolation: apply stricter permissions to experimental versions
 `);
-    permissionsCmd
-        .command('list [agent]')
+    withAliases(permissionsCmd
+        .command('list [agent]'), 'list')
         .description('Show permission sets in storage or active permissions for an agent version')
         .option('-s, --scope <scope>', 'user (global) or project (repo-specific)', 'user')
         .action(async (agentArg, options) => {
@@ -642,8 +643,8 @@ Examples:
             console.error(chalk.red(`Error: ${err.message}`));
         }
     });
-    permissionsCmd
-        .command('remove [name]')
+    withAliases(permissionsCmd
+        .command('remove [name]'), 'remove')
         .description('Delete a permission set from ~/.agents/permissions/ (interactive picker if no name given)')
         .addHelpText('after', `
 Examples:
@@ -704,8 +705,8 @@ Examples:
             }
         }
     });
-    permissionsCmd
-        .command('view [name]')
+    withAliases(permissionsCmd
+        .command('view [name]'), 'view')
         .description('Read the allow and deny rules for a stored permission set')
         .addHelpText('after', `
 Examples:

package/dist/commands/plugins.js

@@ -7,6 +7,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import { homeDir } from '../lib/platform/index.js';
 import { input } from '@inquirer/prompts';
@@ -86,8 +87,8 @@ When to use:
     // flag to the parent for `plugins list --json`, dropping it from the subcommand.)
     pluginsCmd.action(runList);
     // agents plugins list
-    pluginsCmd
-        .command('list')
+    withAliases(pluginsCmd
+        .command('list'), 'list')
         .description('Show plugins in a table with sync status across agent versions')
         .option('--json', 'Emit machine-readable JSON')
         .action(runList);
@@ -127,10 +128,10 @@ When to use:
             .description(`Redirects to 'agents repo ${verb}' — marketplaces follow repos`)
             .action(marketplaceRedirect(verb));
     }
-    // agents plugins info [name]
-    pluginsCmd
-        .command('info [name]')
-        .alias('view')
+    // agents plugins view [name]
+    withAliases(pluginsCmd
+        .command('view [name]'), 'view')
+        .alias('info')
         .description('Show plugin metadata, resources, and installation status across agent versions')
         .addHelpText('after', `
 Examples:
@@ -150,8 +151,8 @@ Examples:
                 return;
             }
             if (!isInteractiveTerminal()) {
-                requireInteractiveSelection('Picking a plugin for `agents plugins info`', [
-                    'agents plugins info <name>',
+                requireInteractiveSelection('Picking a plugin for `agents plugins view`', [
+                    'agents plugins view <name>',
                     'agents plugins  # to see installed plugins',
                 ]);
             }
@@ -375,8 +376,8 @@ Examples:
         }
     });
     // agents plugins remove [name]
-    pluginsCmd
-        .command('remove [name]')
+    withAliases(pluginsCmd
+        .command('remove [name]'), 'remove')
         .description('Unsync a plugin from all agent versions and optionally delete its source directory')
         .option('--keep-source', 'Keep the directory at ~/.agents/plugins/<name> (only unsync from agents)')
         .addHelpText('after', `
@@ -493,22 +494,25 @@ Examples:
             console.log(chalk.gray(`Kept source at ${formatPath(pluginRoot)}`));
         }
     });
-    // agents plugins install <spec>
+    // agents plugins add <spec>
     pluginsCmd
-        .command('install <spec>')
-        .alias('add')
+        .command('add <spec>')
+        .alias('install')
         .description('Install a plugin from a git URL or local path (format: name@source or source)')
         .option('--allow-exec-surfaces', 'Allow installing plugins that ship executable surfaces')
         .addHelpText('after', `
 Examples:
   # Install from a git URL
-  agents plugins install my-plugin@https://github.com/user/my-plugin.git
+  agents plugins add my-plugin@https://github.com/user/my-plugin.git
 
   # Install from a local path
-  agents plugins install /path/to/plugin
+  agents plugins add /path/to/plugin
 
   # Named install from a local path
-  agents plugins install rush-toolkit@~/Projects/rush-toolkit
+  agents plugins add rush-toolkit@~/Projects/rush-toolkit
+
+  # 'install' is kept as an alias
+  agents plugins install /path/to/plugin
 `)
         .action(async (spec, options) => {
         console.log(chalk.gray(`Installing plugin from: ${spec}`));
@@ -545,7 +549,7 @@ Examples:
         const missingDeps = checkPluginDependencies(plugin.manifest);
         if (missingDeps.length > 0) {
             console.log(chalk.yellow(`Warning: missing dependencies: ${missingDeps.join(', ')}`));
-            console.log(chalk.gray('Install them with: agents plugins install <name>@<source>'));
+            console.log(chalk.gray('Install them with: agents plugins add <name>@<source>'));
         }
         // Prompt for userConfig fields
         if (plugin.manifest.userConfig && plugin.manifest.userConfig.length > 0 && isInteractiveTerminal()) {

package/dist/commands/route.js

@@ -9,7 +9,8 @@
  * invoking a router to route a task is a separate ticket.
  */
 import chalk from 'chalk';
-import { listRouters, readRouter, writeRouter, deleteRouter, routerExists, routerSource, routersDir, validateRouter, } from '../lib/routers.js';
+import { withAliases } from '../lib/verbs.js';
+import { listRouters, readRouter, writeRouter, deleteRouter, renameRouter, routerExists, routerSource, routersDir, validateRouter, } from '../lib/routers.js';
 import { MODEL_TIERS, isTierToken } from '../lib/model-tiers.js';
 import { die } from '../lib/format.js';
 import { setHelpSections } from '../lib/help.js';
@@ -89,11 +90,12 @@ function printRouterDetail(router) {
 export function registerRouteCommands(program) {
     const routeCmd = program
         .command('route')
+        .alias('routes')
         .description('Named routers -- reusable, task-typed allowlists of harnesses x models/tiers x linked accounts.');
     setHelpSections(routeCmd, {
         examples: `
       # Create a router scoped to two harnesses, capped at a tier
-      agents route create research --harness gemini,kimi --tier cheap,default
+      agents route add research --harness gemini,kimi --tier cheap,default
 
       # Narrow one harness's model set
       agents route allow research kimi kimi-k2
@@ -102,8 +104,9 @@ export function registerRouteCommands(program) {
       agents route link-account research gemini personal
       agents route link-account research kimi work
 
-      # Inspect it
-      agents route show research
+      # Inspect, rename, remove it
+      agents route view research
+      agents route rename research deep-research
       agents route list --json
     `,
         notes: `
@@ -112,12 +115,16 @@ export function registerRouteCommands(program) {
       outside its declared harness/model/tier allowlist or linked accounts.
 
       Routers are a layered resource (project > user > system, like commands,
-      skills, and profiles) but 'agents route create'/'allow'/'link-account'
+      skills, and profiles) but 'agents route add'/'allow'/'link-account'
       always write to the user layer (~/.agents/routers/<name>.yml).
+
+      The older verb names still work as aliases: 'create' for 'add',
+      'show' for 'view'.
     `,
     });
     routeCmd
-        .command('create <name>')
+        .command('add <name>')
+        .alias('create')
         .description('Create a named router with an initial harness + tier allowlist.')
         .option('--harness <list>', 'Comma-separated harness ids to allow, e.g. gemini,kimi')
         .option('--tier <list>', 'Comma-separated tier tokens applied to every listed harness, e.g. cheap,default')
@@ -127,7 +134,7 @@ export function registerRouteCommands(program) {
             die(`Router '${name}' already exists. Use 'agents route allow ${name} <harness> <model|tier>...' to edit it.`);
         }
         if (!opts.harness) {
-            die("Missing --harness. Example: agents route create research --harness gemini,kimi --tier cheap,default");
+            die("Missing --harness. Example: agents route add research --harness gemini,kimi --tier cheap,default");
         }
         const harnesses = opts.harness.split(',').map((h) => h.trim()).filter(Boolean);
         const tiers = (opts.tier ?? '').split(',').map((t) => t.trim()).filter(Boolean);
@@ -145,8 +152,8 @@ export function registerRouteCommands(program) {
         writeRouter(router);
         console.log(chalk.green(`+ created router "${name}"`) + chalk.gray(`   (${path.join(routersDir(), `${name}.yml`)})`));
     });
-    routeCmd
-        .command('list')
+    withAliases(routeCmd
+        .command('list'), 'list')
         .description('List every configured router.')
         .option('--json', 'Emit machine-readable JSON')
         .action((opts) => {
@@ -163,15 +170,14 @@ export function registerRouteCommands(program) {
         }
         if (routers.length === 0) {
             console.log(chalk.gray('No routers configured.'));
-            console.log(chalk.gray('Try: agents route create research --harness gemini,kimi --tier cheap,default'));
+            console.log(chalk.gray('Try: agents route add research --harness gemini,kimi --tier cheap,default'));
             return;
         }
         for (const router of routers)
             console.log(renderRouterRow(router));
     });
-    routeCmd
-        .command('show <name>')
-        .alias('view')
+    withAliases(routeCmd
+        .command('view <name>'), 'view')
         .description("Show a router's harness/model/account allowlist, weights, and hijack flag.")
         .option('--json', 'Emit machine-readable JSON')
         .action((name, opts) => {
@@ -242,9 +248,20 @@ export function registerRouteCommands(program) {
         writeRouter(router);
         console.log(chalk.green(`Router '${name}': unlinked ${harness} account '${account}'`));
     });
-    routeCmd
-        .command('remove <name>')
-        .alias('rm')
+    withAliases(routeCmd
+        .command('rename <old-name> <new-name>'), 'rename')
+        .description('Rename a router, preserving every field (allowlists, weights, accounts, hijack). Errors on a name collision.')
+        .action((oldName, newName) => {
+        try {
+            renameRouter(oldName, newName);
+            console.log(chalk.green(`Router '${oldName}' renamed to '${newName}'.`));
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    withAliases(routeCmd
+        .command('remove <name>'), 'remove')
         .description('Remove a router.')
         .action((name) => {
         const source = routerSource(name);

package/dist/commands/rules.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -57,8 +58,8 @@ Project rules & @-imports:
   For rules that need to work across all agents, inline the content rather than using
   @-imports — the second group will load '@path/to/file.md' as a literal string.
 `);
-    rulesCmd
-        .command('list [agent]')
+    withAliases(rulesCmd
+        .command('list [agent]'), 'list')
         .description('Show which rule files are installed. Pass agent@version to see a specific version.')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .action(async (agentArg, options) => {
@@ -364,8 +365,8 @@ Examples:
             process.exit(1);
         }
     });
-    rulesCmd
-        .command('view [agent]')
+    withAliases(rulesCmd
+        .command('view [agent]'), 'view')
         .description('Read the full content of a rule file with markdown rendering')
         .option('-s, --scope <scope>', 'user (global) or project (repo-specific)', 'user')
         .addHelpText('after', `
@@ -446,8 +447,8 @@ Examples:
         const filePath = instr?.path || '';
         await displayContent(content, `${agentLabel(agentId)} Rules (${scope})`, filePath);
     });
-    rulesCmd
-        .command('remove [agent]')
+    withAliases(rulesCmd
+        .command('remove [agent]'), 'remove')
         .description('Delete user-level rule files for an agent or version')
         .addHelpText('after', `
 Examples:
@@ -605,10 +606,4 @@ Examples:
             process.exit(1);
         }
     });
-    rulesCmd
-        .command('show [agent]', { hidden: true })
-        .action(async (agentArg) => {
-        console.log(chalk.yellow('Deprecated: Use "agents rules view" instead of "agents rules show"\n'));
-        await rulesCmd.commands.find((c) => c.name() === 'view')?.parseAsync(['view', ...(agentArg ? [agentArg] : [])], { from: 'user' });
-    });
 }

package/dist/commands/sessions-share.js

@@ -68,7 +68,7 @@ export function registerSessionsShareCommand(sessionsCmd) {
         examples: `# Share a session — prints an unlisted, redacted link
 agents sessions share a1b2c3d4
 
-# Put it in your public gallery at share.agents-cli.sh/<you>
+# Put it in your public gallery at share.getrush.ai/<you>
 agents sessions share a1b2c3d4 --public --label "How the retry bug got fixed"
 
 # Keep the model's reasoning in collapsible sections

package/dist/commands/setup-watchdog.js

@@ -10,7 +10,7 @@ export async function runWatchdogSetupWizard() {
     const devices = [...new Set([...Object.keys(registry), machineId()].map(normalizeHost))].sort();
     const enabled = new Set(devices.filter((device) => getConfigValue('watchdog.enabled', { device }).value === true));
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        requireInteractiveSelection('watchdog devices', ['agents watchdog on', 'agents watchdog on --device <device>']);
+        requireInteractiveSelection('watchdog devices', ['agents watchdog enable', 'agents watchdog enable --device <device>']);
     }
     try {
         const { checkbox } = await import('@inquirer/prompts');
@@ -25,7 +25,7 @@ export async function runWatchdogSetupWizard() {
                 setConfigValue('watchdog.enabled', on);
                 continue;
             }
-            const launch = getCliLaunch(['watchdog', on ? 'on' : 'off', '--device', device]);
+            const launch = getCliLaunch(['watchdog', on ? 'enable' : 'disable', '--device', device]);
             const result = spawnSync(launch.command, launch.args, { stdio: 'inherit', env: process.env });
             if ((result.status ?? 1) !== 0)
                 throw new Error(`Could not configure watchdog on ${device}`);

package/dist/commands/setup.js

@@ -29,6 +29,7 @@ import { registerSetupWatchdogCommand, runWatchdogSetupWizard } from './setup-wa
 import { hasMintedSetupToken } from '../lib/auth-mint.js';
 import { registerAliasCommand } from './alias.js';
 import { registerBetaCommands } from './beta.js';
+import { addUrlSchemeSubcommands } from './open.js';
 import { runPreferencesStep } from './setup-preferences.js';
 import { getConfiguredDefaultProfileName, getProfile, getAutoDetectedProfile, isProfileLaunchableHere } from '../lib/browser/profiles.js';
 import { listInstalledBrowsers } from '../lib/browser/chrome.js';
@@ -228,7 +229,7 @@ export async function runSetup(program, options = {}) {
             console.log(chalk.gray('Registered the agents:// URL scheme (artifact session deep links).'));
     }
     catch {
-        // non-fatal — the user can run `agents open register` later.
+        // non-fatal — the user can run `agents setup url-scheme register` later.
     }
     if (options.suppressFooter)
         return;
@@ -382,6 +383,26 @@ export function registerSetupCommand(program) {
     registerSetupWatchdogCommand(setupCmd);
     registerAliasCommand(setupCmd);
     registerBetaCommands(setupCmd);
+    // `agents setup url-scheme register|unregister|status` — the canonical, visible
+    // home for the agents:// OS handler that routes artifact deep links to the
+    // machine-only `agents _callback` verb. Reuses the same builder the hidden
+    // `agents open` back-compat subcommands mount.
+    const urlScheme = setupCmd
+        .command('url-scheme')
+        .description('Register/unregister/status the agents:// OS URL-scheme handler for artifact session deep links.');
+    addUrlSchemeSubcommands(urlScheme, { hidden: false });
+    setHelpSections(urlScheme, {
+        examples: `
+      # Register the handler so agents:// links in rendered artifacts resume sessions
+      agents setup url-scheme register
+
+      # Check whether the handler is registered on this machine
+      agents setup url-scheme status
+
+      # Remove the handler
+      agents setup url-scheme unregister
+    `,
+    });
     setupCmd.command('status')
         .description('Show setup readiness for core, browser, computer, secrets, accounts, fleet, share, watchdog, and preferences.')
         .option('--json', 'print machine-readable JSON')