@jacebenson/jsn 3.0.6 → 3.1.1

package/skills/servicenow/SKILL.md

@@ -12,114 +12,76 @@ compatibility: |
   Requires jsn CLI (github.com/jacebenson/jsn). Install via:
   npm install -g @jacebenson/jsn
   Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
-  
-  Windows users: Install Node.js first, then the npm command above. If jsn is not
-  in your PATH, the setup command will automatically detect its location and show
-  the correct command path.
 metadata:
   author: jacebenson
-  version: "1.0.0"
+  version: "3.1.1"
   repository: https://github.com/jacebenson/jsn
 ---
 
-# Jace's ServiceNow CLI
+# Jace's ServiceNow CLI (jsn)
 
-Explore and manage ServiceNow instances. Works standalone or with AI agents.
+Explore and manage ServiceNow instances. Interactive paginated pickers with server-side search on all list commands.
 
 ## Discovery
 
-Commands are self-documenting. Use these to learn what's available:
-
 ```bash
-jsn --help                # Root help with all top-level commands
-jsn <command> --help        # Detailed usage, flags, and examples for any command
-jsn dev                     # Shows categorized dev subcommands
+jsn --help                # All commands grouped by domain
+jsn <command> --help      # Flags, subcommands, and examples
 ```
 
+## Interactive Picker
+
+All `list` subcommands use a paginated interactive picker in TTY mode:
+- Arrow through items (10 per page)
+- Type to search (server-side LIKE query)
+- Scroll past last loaded item to load next page
+- Enter to select, Esc to cancel
+- Falls back to table output with `--json`
+
 ## Agent Rules
 
-1. **Output modes** — `--json` when parsing data; `--md` when presenting to humans; `--agent` for automation
+1. **Output modes** — `--json` when parsing data; text when presenting to humans
 2. **Use sys_id for updates** — All update/delete operations require sys_id
 3. **Check auth first** — Run `jsn auth status` before operations
 4. **NEVER logout** — Only run `jsn auth logout` if the user explicitly asks
 5. **Use `--profile <name>`** to target a specific instance, or `jsn profiles use <name>` to change default
-6. **Before using `eval` or `rest`** — Ask yourself: *"Have I checked if there's a more specific jsn command?"* Verify `jsn records --table <name> create` won't work first. Prefer specific over generic over escape hatch over eval.
-7. **CONFIRM before destructive operations** — Always show the user exactly what will be created, updated, or deleted and ask for explicit confirmation before executing. Never run `create`, `update`, `delete`, `set`, or `remove` commands without user approval.
-
-## ⚠️ Destructive Operations Require Confirmation
-
-**jsn does not have a `--confirm` or `--dry-run` flag.** It assumes you mean what you type. This means **YOU** (the agent) are the safety layer.
-
-**Before any write operation, you MUST:**
-
-1. **Show the user what you found** — Run a `list` or `show` command first
-2. **Present the exact command you plan to run** — Include the sys_id, table name, and data
-3. **Wait for explicit approval** — "Proceed? [y/N]" or similar
-
-**Examples of destructive commands that require confirmation:**
-- `jsn records --table <name> create`
-- `jsn records --table <name> update <sys_id>`
-- `jsn records --table <name> delete <sys_id>`
-- `jsn dev updatesets set <name>`
-- `jsn profiles remove <name>`
-- Any `delete`, `update`, `create`, `set`, or `remove` subcommand
-
-**Good pattern:**
-```
-User: "Delete that incident"
-Agent: "Found: INC0010001 'Server down' (sys_id: abc123...)
-       Command: jsn records --table incident delete abc123...
-       Proceed? [y/N]"
-User: "y"
-Agent: [runs command]
-```
-
-**Bad pattern:**
-```
-User: "Delete that incident"
-Agent: [immediately runs jsn records --table incident delete ...]
-```
-
-## ⚠️ AVOID `jsn eval` for Record Creation
-
-**Why:** `jsn eval` runs server-side JavaScript in the global scope. It returns HTTP 200 even when:
-- The insert fails due to ACL violations
-- Mandatory fields are missing
-- The record lands in the wrong scope
-- Logic errors prevent the insert entirely
-
-**The AI trap:** Agents see "success" and assume the record was created. It wasn't.
-
-**Always use instead:** `jsn records --table <name> create` — it returns the created record with sys_id or an explicit validation error.
-
-**Only use `eval` when:** No specific command exists, `records` lacks required fields, and `rest` doesn't work. This is rare.
+6. **Before using `eval` or `rest`** — Ask: *"Is there a more specific jsn command?"* Prefer specific over generic over escape hatch over eval.
+7. **CONFIRM before destructive operations** — Show what will be created/updated/deleted and ask for approval.
 
 ## Command Hierarchy
 
 Pick the most specific tool for the job. **Never default to eval** — it's the last resort:
 
-1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn jobs`, etc. — curated views with domain-aware formatting and validation
-2. **`jsn records --table <name>`** — generic CRUD on any table (the workhorse, preferred for record creation)
-3. **`jsn rest`** — raw Table API escape hatch when records command lacks required fields
-4. **`jsn eval`** — ⚠️ **LAST RESORT ONLY** — server-side script execution when no other option exists
-5. **Ask the human** — if none of the above work. Never generate standalone GlideRecord scripts as a fallback.
-
-## JSON Envelope
-
-All commands support `--json`. The envelope structure:
-
-```json
-{
-  "ok": true,
-  "data": [ ... ],
-  "summary": "5 records",
-  "breadcrumbs": [
-    {"action": "show", "cmd": "jsn records --table incident <sys_id>", "description": "View details"}
-  ]
-}
-```
-
-Breadcrumbs suggest next commands — follow them for navigation.
+1. **Specific commands** — `jsn flows`, `jsn rules`, `jsn catalogitems`, etc.
+2. **`jsn records --table <name>`** — generic CRUD on any table
+3. **`jsn rest`** — raw Table API escape hatch
+4. **`jsn eval`** — ⚠️ **LAST RESORT ONLY**
+5. **Ask the human** — if none of the above work
+
+## Key Commands
+
+| Domain | Commands |
+|--------|---------|
+| **Core** | `incidents`, `changes`, `requests`, `tasks` |
+| **Catalog** | `catalogitems list/show/create` — items with variables and flow info |
+| **Automation** | `flows`, `actions`, `rules`, `workflows`, `triggers`, `scheduledjobs` |
+| **Access** | `acls`, `b4rules`, `roles`, `groups`, `users` |
+| **UX** | `forms` (section/element layout), `lists`, `clientscripts`, `uipolicies` |
+| **Data** | `tables`, `columns`, `includes`, `logs`, `properties`, `records` |
+| **Config** | `setup`, `auth`, `profiles`, `updatesets`, `scopes` |
+| **Developer** | `eval`, `rest`, `skill`, `version` |
+
+## Troubleshooting Field Behavior
+
+Check order (priority):
+
+1. **Before-query business rules** — `sys_script` with `when=before`, `action=query`
+   ```bash
+   jsn b4rules list --query "collection=sys_user"
+   ```
+2. **ACLs** — `jsn acls list --query "name=incident"`
+3. **Dictionary overrides** — `jsn records list --table sys_dictionary --query "name=incident^element=caller_id"`
+4. **Client scripts** / **UI policies** — form-level field behavior
 
 ## Configuration
 
@@ -127,11 +89,4 @@ Breadcrumbs suggest next commands — follow them for navigation.
 ~/.config/servicenow/
 ├── config.json               # Profiles and settings
 └── credentials.json          # Auth tokens (fallback)
-
-.servicenow/                  # Per-repo config (optional)
-└── config.json               # Project-specific settings
 ```
-
-**Environment variables:**
-- `SERVICENOW_TOKEN` — Override stored token
-- `SERVICENOW_INSTANCE` — Override instance URL

package/src/app.js

@@ -118,7 +118,7 @@ export class App {
 
     const scopeFormatted = `[${scope}]`;
 
-    process.stderr.write('# Use `jsn dev scopes` to change scope, `jsn dev updatesets set` to change updateset\n');
+    process.stderr.write('# Use `jsn scopes` to change scope, `jsn updatesets set` to change updateset\n');
     process.stderr.write('PROFILE   USER      [SCOPE]           UPDATE SET\n');
 
     const profileStr = `]8;;${instanceLink}\x07${String(this.context.profileName).padEnd(9)}]8;;\x07`;
@@ -144,12 +144,12 @@ export class App {
           '┃  manual surgery, one change at a time. Avoid the mess. ┃\n' +
           '┃                                                        ┃\n' +
           '┃  Create a named update set now:                        ┃\n' +
-          '┃    jsn dev updatesets create --name "My Feature"       ┃\n' +
+          '┃    jsn updatesets create --name "My Feature"       ┃\n' +
           '┃                                                        ┃\n' +
           '┃  Or switch to a scoped scope first:                    ┃\n' +
-          '┃    jsn dev scopes list                                 ┃\n' +
+          '┃    jsn scopes list                                 ┃\n' +
           '┃                                                        ┃\n' +
-          '┃  (Run jsn dev updatesets yolo to silence this check)    ┃\n' +
+          '┃  (Run jsn updatesets yolo to silence this check)    ┃\n' +
           '┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛\x1b[0m\n'
         );
       } else {
@@ -160,7 +160,7 @@ export class App {
           '  ⚠  Default update set in scope [' + scope + ']\n' +
           '  Changes are contained to this scope, but a named\n' +
           '  update set is still recommended for tracking.\n' +
-          '  (Run \x1b[1mjsn dev updatesets yolo\x1b[22m to silence this warning)\n' +
+          '  (Run \x1b[1mjsn updatesets yolo\x1b[22m to silence this warning)\n' +
           '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' +
           '\x1b[0m' // reset
         );

package/src/cli.js

@@ -27,6 +27,33 @@ import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
 
+// Dev subcommands promoted to root level for progressive disclosure
+import {
+  actionsCmd, includesCmd, rulesCmd,
+  clientScriptsCmd, uiActionsCmd, uiPoliciesCmd,
+  tablesCmd, columnsCmd, importCmd,
+  spPagesCmd, spWidgetsCmd, uiPagesCmd, appMenuCmd,
+  aclsCmd, rolesCmd, propertiesCmd,
+  relationshipsCmd, appmodulesCmd, listcontrolsCmd, viewsCmd,
+  privilegesCmd, securitytypesCmd, uxscriptsCmd, aliasesCmd,
+  catalogscriptsCmd, cataloguipoliciesCmd,
+  scriptactionsCmd, scheduledjobsCmd, asyncrulesCmd, triggersCmd,
+  workflowsCmd, decisiontablesCmd, assignmentsCmd,
+  emailCmd,
+  restmessageCmd, restmethodsCmd, soapmessagesCmd, soapfunctionsCmd,
+  uimacrosCmd, uxlistsCmd, uxapplicabilityCmd,
+} from './commands/dev/_simple.js';
+import { flowsCmd } from './commands/dev/flows.js';
+import { formsCmd } from './commands/dev/forms.js';
+import { listsCmd } from './commands/dev/lists.js';
+import { updateSetsCmd } from './commands/dev/updatesets.js';
+import { scopesCmd } from './commands/dev/scopes.js';
+import { evalCmd } from './commands/dev/eval.js';
+import { restCmd } from './commands/dev/rest.js';
+import { logsCmd } from './commands/dev/logs.js';
+import { scrapiCmd } from './commands/dev/scrapi.js';
+import { b4rulesCmd } from './commands/dev/b4rules.js';
+
 function wrap(handler) {
   return async (argv) => {
     try {
@@ -37,179 +64,259 @@ function wrap(handler) {
       }
       await handler(argv, app);
     } catch (err) {
-      const app = argv.app;
-      if (app) {
-        app.err(err);
-      } else {
-        process.stderr.write(`Error: ${err.message || err}\n`);
+      if (err.code === 'not_found') {
+        const id = argv._.slice(1).join(' ') || argv.id || argv.name || argv.sysID || '';
+        process.stderr.write(`Error (${err.code}): ${err.message}\n`);
+        if (id) {
+          process.stderr.write(`\nHint: The identifier "${id}" was not found. Check the name or sys_id.\n`);
+        }
+        process.exit(1);
       }
+      if (err.code === 'usage') {
+        process.stderr.write(`Error (usage): ${err.message}\n`);
+        process.exit(2);
+      }
+      if (err.code === 'system_error') {
+        process.stderr.write(`Error (system): ${err.message}\n`);
+        process.exit(3);
+      }
+      process.stderr.write(`Error: ${err.message}\n`);
       process.exit(1);
     }
   };
 }
 
-export const cli = yargs(hideBin(process.argv))
-  .scriptName('jsn')
-  .usage('Usage: $0 <command> [options]')
-  .option('instance', {
-    describe: 'ServiceNow instance URL (e.g., https://dev12345.service-now.com)',
-    type: 'string',
-    global: true,
-  })
-  .option('profile', {
-    alias: 'p',
-    describe: 'Configuration profile to use',
-    type: 'string',
-    global: true,
-  })
-  .option('format', {
-    describe: 'Output format: auto, json, markdown, styled, quiet',
-    type: 'string',
-    global: true,
-  })
-  .option('json', {
-    describe: 'Output in JSON format',
-    type: 'boolean',
-    global: true,
-  })
-  .option('quiet', {
-    alias: 'q',
-    describe: 'Output only data, no envelope',
-    type: 'boolean',
-    global: true,
-  })
-  .option('styled', {
-    describe: 'Force styled output',
-    type: 'boolean',
-    global: true,
-  })
-  .option('markdown', {
-    describe: 'Output in Markdown format',
-    type: 'boolean',
-    global: true,
-  })
-  .option('no-skill-check', {
-    describe: 'Skip the automatic skill version check',
-    type: 'boolean',
-    global: true,
-  })
-  .middleware(async (argv) => {
-    // Determine format from flags
-    let format = 'auto';
-    if (argv.json) format = 'json';
-    else if (argv.quiet) format = 'quiet';
-    else if (argv.styled) format = 'styled';
-    else if (argv.markdown) format = 'markdown';
-    else if (argv.format) format = argv.format;
-
-    const cfg = loadConfig({
-      instance: argv.instance,
-      profile: argv.profile,
-      format,
-    });
-
-    argv.app = new App(cfg);
+export function buildCLI() {
+  const cfg = loadConfig();
+  const app = new App(cfg);
 
-    // Check auth for non-auth commands
-    const cmd = argv._[0];
-    const skipAuth = ['help', 'version', 'setup', 'auth', 'profiles', 'profile', 'skill', undefined].includes(cmd);
-    if (!skipAuth) {
-      const instance = getEffectiveInstance(cfg);
-      if (!argv.app.auth.isAuthenticated() && instance) {
-        process.stderr.write(`\n⚠️  Not authenticated to ${instance}\n\n`);
-        process.stderr.write('To get started, run:\n');
-        process.stderr.write('  jsn setup           # Interactive setup\n');
-        process.stderr.write(`  jsn auth login ${instance}   # Login to instance\n\n`);
-      }
-    }
+  // Resolve instance once
+  let effectiveInstance;
+  try {
+    effectiveInstance = getEffectiveInstance(cfg);
+  } catch {
+    effectiveInstance = null;
+  }
 
-    // Read-only profile check — block mutation commands on read-only profiles
-    const activeProfileName = cfg.activeProfile || cfg.defaultProfile;
-    if (activeProfileName && cfg.profiles[activeProfileName] && cfg.profiles[activeProfileName].read_only) {
-      const skipReadOnlyCheck = ['help', 'version', 'setup', 'auth', 'profiles', 'profile', 'skill', undefined].includes(cmd);
-      if (!skipReadOnlyCheck && isMutationCommand(argv)) {
-        process.stderr.write(`\n🔒 Profile "${activeProfileName}" is read-only.\n`);
-        process.stderr.write(`  Mutation commands are disabled on this profile.\n`);
-        const nonReadOnlyProfiles = Object.entries(cfg.profiles || {})
-          .filter(([n, p]) => n !== activeProfileName && !p.read_only)
-          .map(([n]) => n);
-        if (nonReadOnlyProfiles.length > 0) {
-          process.stderr.write(`  Switch to a writable profile:  jsn profiles use ${nonReadOnlyProfiles[0]}\n`);
+  return yargs(hideBin(process.argv))
+    .scriptName('jsn')
+    .usage('Usage: jsn <command> [options]')
+    .middleware([
+      // Attach App instance to every command
+      (argv) => {
+        argv.app = app;
+        argv._profile = cfg.profiles || {};
+      },
+    ])
+    .options({
+      instance: {
+        type: 'string',
+        description: 'ServiceNow instance URL',
+        alias: 'i',
+      },
+      profile: {
+        type: 'string',
+        description: 'Configuration profile to use',
+        alias: 'p',
+      },
+      format: {
+        type: 'string',
+        description: 'Output format: auto, json, markdown, styled, quiet',
+        choices: ['auto', 'json', 'markdown', 'styled', 'quiet'],
+      },
+      json: {
+        type: 'boolean',
+        description: 'Output in JSON format (shortcut for --format=json)',
+      },
+      quiet: {
+        type: 'boolean',
+        description: 'Output only data, no envelope (shortcut for --format=quiet)',
+        alias: 'q',
+      },
+      styled: {
+        type: 'boolean',
+        description: 'Force styled output even when piped',
+      },
+      markdown: {
+        type: 'boolean',
+        description: 'Output in Markdown table format',
+      },
+    })
+    .middleware([
+      // Apply format option overrides
+      (argv) => {
+        if (argv.json) argv.format = 'json';
+        if (argv.quiet) argv.format = 'quiet';
+        if (argv.styled) argv.format = 'styled';
+        if (argv.markdown) argv.format = 'markdown';
+        if (argv.format) {
+          app.output.setFormatByName(argv.format);
         }
-        process.stderr.write('\n');
-        process.exit(1);
+        if (argv.instance) {
+          app._overrideInstance = argv.instance;
+        }
+      },
+      // Guard mutation commands when no instance configured
+      (argv) => {
+        const cmd = (argv._[0] || '').toString();
+        if (!cmd || ['help', 'version', 'completion', 'setup', 'auth', 'profiles', 'skill'].includes(cmd)) {
+          return;
+        }
+        // Check for --instance override
+        if (argv.instance) {
+          app._overrideInstance = argv.instance;
+        }
+        // Determine if this is a mutation
+        const subcommand = (argv._[1] || '').toString();
+        const isMutation = isMutationCommand(cmd, subcommand);
+        if (isMutation) {
+          app.requireInstance();
+        }
+      },
+    ])
+    .middleware(async (argv) => {
+      // Override instance for this command run
+      if (argv._overrideInstance) {
+        app.setEffectiveInstance(argv._overrideInstance);
       }
-    }
 
-    // Auto-check skill on every command (fire-and-forget, non-blocking)
-    // Skipped under --json, --quiet, --no-skill-check, or env var
-    const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
-      || process.env.JSN_NO_SKILL_CHECK === '1'
-      || argv['no-skill-check']
-      || argv.json
-      || argv.quiet;
-    if (!skipSkillCheck) {
-      // Fire check but don't await — it runs in background
-      checkSkill().then(result => {
-        if (result && !result.current && result.error) {
-          process.stderr.write(`\n⚠ ${result.error}\n\n`);
-        }
-      }).catch(() => {});
-    }
+      const cmd = (argv._[0] || '').toString();
 
-    // Print context header for interactive terminals (at the TOP, before command output)
-    if (!['help', 'version', 'completion', 'skill'].includes(cmd)) {
-      await argv.app.printContextHeader(argv);
-    }
-  })
-  .command(setupCmd(wrap))
-  .command(authCmd(wrap))
-  .command(profilesCmd(wrap))
-  .command(recordsCmd(wrap))
-  .command(catalogCmd(wrap))
-  .command(incidentsCmd(wrap))
-  .command(changesCmd(wrap))
-  .command(requestsCmd(wrap))
-  .command(tasksCmd(wrap))
-  .command(usersCmd(wrap))
-  .command(groupsCmd(wrap))
-  .command(groupMembersCmd(wrap))
-  .command(groupRolesCmd(wrap))
-  .command(ticketsCmd(wrap))
-  .command(devCmd(wrap))
-  .command(skillCmd(wrap))
-  .command(versionCmd(wrap))
-  .demandCommand(1, 'You must specify a command')
-  .help('help', 'Show help')
-  .version(false)
-  .strictCommands()
-  .strictOptions(false)
-  .fail((msg, err) => {
-    if (err) throw err;
-    // No command given → show custom grouped help instead of yargs error
-    if (msg === 'You must specify a command') {
-      // Check if --profile/-p was used without a value — show profile info instead
-      const raw = process.argv.slice(2);
-      const hasLoneProfile = raw.some((a, i, arr) => {
-        if (a !== '--profile' && a !== '-p') return false;
-        const next = arr[i + 1];
-        return !next || next.startsWith('-');
-      });
-      if (hasLoneProfile) {
-        const cfg = loadConfig();
-        const activeName = cfg.activeProfile || cfg.defaultProfile;
-        process.stdout.write('Profiles:\n');
-        for (const [name, p] of Object.entries(cfg.profiles || {})) {
-          const marker = name === activeName ? ' *' : '  ';
-          process.stdout.write(`  ${marker} ${name.padEnd(20)} ${p.instance_url || ''}\n`);
+      // Auto-check skill on every command (fire-and-forget, non-blocking)
+      const skipSkillCheck = ['help', 'version', 'completion', 'skill'].includes(cmd)
+        || process.env.JSN_NO_SKILL_CHECK === '1'
+        || argv['no-skill-check']
+        || argv.json
+        || argv.quiet;
+      if (!skipSkillCheck) {
+        checkSkill().then(result => {
+          if (result && !result.current && result.error) {
+            process.stderr.write(`\n⚠ ${result.error}\n\n`);
+          }
+        }).catch(() => {});
+      }
+
+      // Print context header for interactive terminals
+      if (!['help', 'version', 'completion', 'skill'].includes(cmd)) {
+        await argv.app.printContextHeader(argv);
+      }
+    })
+    // CONFIGURATION
+    .command(setupCmd(wrap))
+    .command(authCmd(wrap))
+    .command(profilesCmd(wrap))
+    .command(updateSetsCmd(wrap))
+    .command(scopesCmd(wrap))
+    // CORE
+    .command(incidentsCmd(wrap))
+    .command(changesCmd(wrap))
+    .command(requestsCmd(wrap))
+    .command(tasksCmd(wrap))
+    .command(catalogCmd(wrap))
+    // AUTOMATION — Async
+    .command(flowsCmd(wrap))
+    .command(actionsCmd(wrap))
+    .command(scriptactionsCmd(wrap))
+    .command(scheduledjobsCmd(wrap))
+    .command(asyncrulesCmd(wrap))
+    .command(triggersCmd(wrap))
+    // AUTOMATION — In Memory
+    .command(rulesCmd(wrap))
+    .command(workflowsCmd(wrap))
+    .command(decisiontablesCmd(wrap))
+    .command(assignmentsCmd(wrap))
+    // AUTOMATION — Inbound
+    .command(scrapiCmd(wrap))
+    .command(emailCmd(wrap))
+    // AUTOMATION — Outbound
+    .command(restmessageCmd(wrap))
+    .command(restmethodsCmd(wrap))
+    .command(soapmessagesCmd(wrap))
+    .command(soapfunctionsCmd(wrap))
+    // ACCESS
+    .command(aclsCmd(wrap))
+    .command(b4rulesCmd(wrap))
+    .command(rolesCmd(wrap))
+    .command(privilegesCmd(wrap))
+    .command(securitytypesCmd(wrap))
+    .command(aliasesCmd(wrap))
+    .command(groupsCmd(wrap))
+    .command(groupMembersCmd(wrap))
+    .command(groupRolesCmd(wrap))
+    .command(usersCmd(wrap))
+    // USER EXPERIENCE — Shared
+    .command(formsCmd(wrap))
+    .command(listsCmd(wrap))
+    .command(clientScriptsCmd(wrap))
+    .command(uiPoliciesCmd(wrap))
+    .command(uiActionsCmd(wrap))
+    .command(viewsCmd(wrap))
+    .command(catalogscriptsCmd(wrap))
+    .command(cataloguipoliciesCmd(wrap))
+    // USER EXPERIENCE — Core UI
+    .command(uiPagesCmd(wrap))
+    .command(uimacrosCmd(wrap))
+    .command(listcontrolsCmd(wrap))
+    // USER EXPERIENCE — Service Portal
+    .command(spPagesCmd(wrap))
+    .command(spWidgetsCmd(wrap))
+    // USER EXPERIENCE — Next Experience
+    .command(uxscriptsCmd(wrap))
+    .command(uxlistsCmd(wrap))
+    .command(uxapplicabilityCmd(wrap))
+    // USER EXPERIENCE — Navigation
+    .command(appMenuCmd(wrap))
+    .command(appmodulesCmd(wrap))
+    // DATA — DB Schema
+    .command(tablesCmd(wrap))
+    .command(columnsCmd(wrap))
+    .command(relationshipsCmd(wrap))
+    // DATA — Shared Code, Transforms, Logs
+    .command(includesCmd(wrap))
+    .command(importCmd(wrap))
+    .command(logsCmd(wrap))
+    .command(propertiesCmd(wrap))
+    // DATA
+    .command(recordsCmd(wrap))
+    .command(ticketsCmd(wrap))
+    // DEVELOPER
+    .command(evalCmd(wrap))
+    .command(restCmd(wrap))
+    .command(skillCmd(wrap))
+    .command(versionCmd(wrap))
+    // Legacy
+    .command(devCmd(wrap))
+    .demandCommand(1, 'You must specify a command')
+    .help('help', 'Show help')
+    .version(false)
+    .strictCommands()
+    .strictOptions(false)
+    .fail((msg, err) => {
+      if (err) throw err;
+      if (msg === 'You must specify a command') {
+        const raw = process.argv.slice(2);
+        const hasLoneProfile = raw.some((a, i, arr) => {
+          if (a !== '--profile' && a !== '-p') return false;
+          const next = arr[i + 1];
+          return !next || next.startsWith('-');
+        });
+        if (hasLoneProfile) {
+          const cfg = loadConfig();
+          const activeName = cfg.activeProfile || cfg.defaultProfile;
+          process.stdout.write('Profiles:\n');
+          for (const [name, p] of Object.entries(cfg.profiles || {})) {
+            const isActive = name === activeName;
+            process.stdout.write(`  ${isActive ? '*' : ' '} ${name}  → ${p.instance_url || '(no url)'}\n`);
+          }
+          process.exit(0);
         }
-        process.stdout.write('\nUsage: jsn --profile <name> <command>\n');
-        process.stdout.write('       jsn profiles use <name>\n');
+        process.stdout.write(renderHelp() + '\n');
         process.exit(0);
       }
-      process.stdout.write(renderHelp());
-      process.exit(0);
-    }
-    process.stderr.write(`Error: ${msg}\n`);
-    process.exit(1);
-  });
+      process.stderr.write(msg + '\n');
+      process.exit(1);
+    });
+}
+
+// Run if invoked directly (bin/jsn.js calls cli.parse())
+export const cli = buildCLI();