@jacebenson/jsn 0.0.9 → 0.1.0

package/skills/servicenow/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: servicenow
+description: |
+  Interact with ServiceNow instances via the jsn CLI. Use when working with ServiceNow
+  development, administration, or data exploration. Handles tables, records, business rules,
+  flows, script includes, ACLs, update sets, and more. Triggered by ServiceNow URLs
+  (service-now.com, servicenow.com) or when the user mentions ServiceNow, jsn, servicenow,
+  or related terms like tables, records, business rules, flows, script includes, ACLs,
+  update sets, or encoded queries.
+license: MIT
+compatibility: |
+  Requires jsn CLI (github.com/jacebenson/jsn). Install via:
+  curl -fsSL https://jsn.jace.pro/install | bash
+  Works with Claude Code, OpenCode, Cursor, and agentskills-compatible tools.
+  
+  Windows users: Download from GitHub releases. If jsn is not in your PATH, the setup
+  command will automatically detect its location and show the correct command path
+  (e.g., `.\jsn.exe tables list` instead of `jsn tables list`).
+metadata:
+  author: jacebenson
+  version: "1.0.0"
+  repository: https://github.com/jacebenson/jsn
+---
+
+# Jace's ServiceNow CLI
+
+Explore and manage ServiceNow instances. Works standalone or with AI agents.
+
+## 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
+```
+
+## Agent Rules
+
+1. **Output modes** — `--json` when parsing data; `--md` when presenting to humans; `--agent` for automation
+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.
+
+## 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.
+
+## Configuration
+
+```
+~/.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

@@ -109,7 +109,7 @@ export class App {
 
     const scopeFormatted = `[${scope}]`;
 
-    process.stderr.write('# Use `jsn updateset use` or `jsn scope use` to change scope/updateset\n');
+    process.stderr.write('# Use `jsn dev scopes` to change scope, `jsn dev 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`;

package/src/auth.js

@@ -1,19 +1,59 @@
 // OAuth 2.0 with PKCE authentication
+// Credentials are stored in the OS keyring (shared with Go version via libsecret/secret-tool)
+// Falls back to file-based storage when keyring is unavailable.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import readline from 'node:readline';
+import { execSync } from 'node:child_process';
 import { globalConfigDir, normalizeInstanceURL } from './config.js';
 import { errAuth } from './errors.js';
 
+// ─── PKCE state persistence (shared with Go version) ───
+
+function pkceStatePath(instance) {
+  const dir = path.join(globalConfigDir(), 'pkce');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const filename = instance.replace(/:\/\//g, '_').replace(/\//g, '_').replace(/:/g, '_') + '.json';
+  return path.join(dir, filename);
+}
+
+function savePKCEState(instance, pkce) {
+  const filePath = pkceStatePath(instance);
+  fs.writeFileSync(filePath, JSON.stringify(pkce, null, 2), { mode: 0o600 });
+}
+
+function loadPKCEState(instance) {
+  try {
+    const data = fs.readFileSync(pkceStatePath(instance), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+
+function removePKCEState(instance) {
+  try {
+    fs.unlinkSync(pkceStatePath(instance));
+  } catch {
+    // ignore
+  }
+}
+
 const DEFAULT_OAUTH_CLIENT_ID = '543e5655f77746a28228c6009a599dfb';
 const REDIRECT_URI = '/sdk-oauth.do';
 
+// Keychain constants — same as Go version (internal/auth/store.go)
+const KEYRING_SERVICE = 'servicenow-cli';
+const KEYRING_ATTR_SERVICE = 'service';
+const KEYRING_ATTR_USERNAME = 'username';
+
 function credentialsPath(instance) {
   const dir = path.join(globalConfigDir(), 'credentials');
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const filename = Buffer.from(instance).toString('base64url') + '.json';
+  // Match Go's filename encoding: replace :// and / and : with _
+  const filename = instance.replace(/:\/\//g, '_').replace(/\//g, '_').replace(/:/g, '_') + '.json';
   return path.join(dir, filename);
 }
 
@@ -37,10 +77,66 @@ function buildAuthURL(instanceURL, clientID, pkce) {
   u.searchParams.set('code_challenge', pkce.code_challenge);
   u.searchParams.set('code_challenge_method', 'S256');
   u.searchParams.set('scope', 'openid');
+  u.searchParams.set('approval_prompt', 'force');
   return u.toString();
 }
 
+// ─── Keyring via secret-tool (libsecret, same backend as Go's go-keyring) ───
+
+function keyringLookup(instance) {
+  try {
+    const result = execSync(
+      `secret-tool lookup ${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${instance}"`,
+      { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' }
+    );
+    const trimmed = result.trim();
+    if (!trimmed) return null;
+    const parsed = JSON.parse(trimmed);
+    // Normalize field names from Go's format to Node.js format
+    return {
+      auth_method: parsed.auth_method || 'oauth',
+      access_token: parsed.access_token || parsed.AccessToken || '',
+      refresh_token: parsed.refresh_token || parsed.RefreshToken || '',
+      expires_at: parsed.expires_at || parsed.ExpiresAt || 0,
+      created_at: parsed.created_at || parsed.CreatedAt || 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function keyringStore(instance, creds) {
+  try {
+    execSync(
+      `secret-tool store --label="Password for '${instance}' on '${KEYRING_SERVICE}'" ` +
+      `${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${instance}"`,
+      { stdio: ['pipe', 'ignore', 'ignore'], input: JSON.stringify(creds) }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function keyringDelete(instance) {
+  try {
+    execSync(
+      `secret-tool clear ${KEYRING_ATTR_SERVICE} ${KEYRING_SERVICE} ${KEYRING_ATTR_USERNAME} "${instance}"`,
+      { stdio: 'ignore' }
+    );
+  } catch {
+    // ignore
+  }
+}
+
+// ─── File-based storage (fallback) ───
+
 function loadCredentials(instance) {
+  // Try keyring first (shared with Go version)
+  const keyringCreds = keyringLookup(instance);
+  if (keyringCreds) return keyringCreds;
+
+  // Fall back to file-based storage
   try {
     const data = fs.readFileSync(credentialsPath(instance), 'utf-8');
     return JSON.parse(data);
@@ -50,10 +146,14 @@ function loadCredentials(instance) {
 }
 
 function saveCredentials(instance, creds) {
-  fs.writeFileSync(credentialsPath(instance), JSON.stringify(creds, null, 2), { mode: 0o600 });
+  // Try keyring first, fall back to file
+  if (!keyringStore(instance, creds)) {
+    fs.writeFileSync(credentialsPath(instance), JSON.stringify(creds, null, 2), { mode: 0o600 });
+  }
 }
 
 function deleteCredentials(instance) {
+  keyringDelete(instance);
   try {
     fs.unlinkSync(credentialsPath(instance));
   } catch {
@@ -210,6 +310,43 @@ export class AuthManager {
     return newCreds;
   }
 
+  /**
+   * Build an OAuth authorization URL and persist PKCE state for later use.
+   * After calling this, the user can visit the URL in a browser and then
+   * call loginWithCode() with the resulting authorization code.
+   */
+  buildAuthURL(instanceURL) {
+    instanceURL = normalizeInstanceURL(instanceURL);
+    const clientID = getOAuthClientID();
+    const pkce = generatePKCE();
+    savePKCEState(instanceURL, pkce);
+    return buildAuthURL(instanceURL, clientID, pkce);
+  }
+
+  /**
+   * Complete login using an authorization code obtained from a prior buildAuthURL() call.
+   * The PKCE state must have been saved by an earlier buildAuthURL() call.
+   */
+  async loginWithCode(instanceURL, code) {
+    instanceURL = normalizeInstanceURL(instanceURL);
+    const clientID = getOAuthClientID();
+    const pkce = loadPKCEState(instanceURL);
+    if (!pkce) {
+      throw errAuth(
+        `No pending login session for ${instanceURL}.\n\n` +
+        'Run without --code first to generate one:\n' +
+        `  jsn auth login ${instanceURL} --print-url\n\n` +
+        'This generates the PKCE challenge and saves it. Then call:\n' +
+        `  jsn auth login ${instanceURL} --code CODE`
+      );
+    }
+    removePKCEState(instanceURL);
+
+    const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
+    saveCredentials(instanceURL, newCreds);
+    return newCreds;
+  }
+
   async exchangeCode(instanceURL, clientID, code, pkce) {
     const tokenURL = `${instanceURL.replace(/\/$/, '')}/oauth_token.do`;
     const body = new URLSearchParams();

package/src/cli.js

@@ -5,6 +5,7 @@ import { hideBin } from 'yargs/helpers';
 import process from 'node:process';
 import { loadConfig, getEffectiveInstance } from './config.js';
 import { App } from './app.js';
+import { renderHelp } from './help.js';
 
 // Command modules
 import { setupCmd } from './commands/setup.js';
@@ -22,6 +23,7 @@ import { groupRolesCmd } from './commands/grouproles.js';
 import { ticketsCmd } from './commands/tickets.js';
 import { versionCmd } from './commands/version.js';
 import { devCmd } from './commands/dev.js';
+import { skillCmd } from './commands/skill.js';
 
 function wrap(handler) {
   return async (argv) => {
@@ -84,7 +86,7 @@ export const cli = yargs(hideBin(process.argv))
     type: 'boolean',
     global: true,
   })
-  .middleware((argv) => {
+  .middleware(async (argv) => {
     // Determine format from flags
     let format = 'auto';
     if (argv.json) format = 'json';
@@ -103,7 +105,7 @@ export const cli = yargs(hideBin(process.argv))
 
     // Check auth for non-auth commands
     const cmd = argv._[0];
-    const skipAuth = ['help', 'version', 'setup', 'auth', undefined].includes(cmd);
+    const skipAuth = ['help', 'version', 'setup', 'auth', 'profiles', 'profile', 'skill', undefined].includes(cmd);
     if (!skipAuth) {
       const instance = getEffectiveInstance(cfg);
       if (!argv.app.auth.isAuthenticated() && instance) {
@@ -114,9 +116,9 @@ export const cli = yargs(hideBin(process.argv))
       }
     }
 
-    // Print context header for interactive terminals
-    if (!['help', 'version', 'completion'].includes(cmd)) {
-      argv.app.printContextHeader();
+    // Print context header for interactive terminals (at the TOP, before command output)
+    if (!['help', 'version', 'completion', 'skill'].includes(cmd)) {
+      await argv.app.printContextHeader();
     }
   })
   .command(setupCmd(wrap))
@@ -133,10 +135,20 @@ export const cli = yargs(hideBin(process.argv))
   .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)
-  .epilogue('LEARN MORE\n  Use "jsn <command> --help" for more information about a command.');
+  .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') {
+      process.stdout.write(renderHelp());
+      process.exit(0);
+    }
+    process.stderr.write(`Error: ${msg}\n`);
+    process.exit(1);
+  });

package/src/commands/_ticket.js

@@ -2,14 +2,14 @@
 // Used by incidents, changes, requests, tasks, and most dev subcommands
 
 import { getStringField, formatRecordForDisplay, buildQuerySuffix } from '../helpers.js';
-import { select } from '@inquirer/prompts';
+import search from '@inquirer/search';
 import { isTTY, FormatAuto } from '../output.js';
 
 export function buildTicketCommands(table, displayName, alias, defaultColumns, stateMap, iconFn, wrap) {
   return {
     command: `${displayName} [subcommand]`,
     aliases: [table, alias],
-    describe: `Manage ${displayName}`,
+    describe: `Manage ${displayName} (e.g. "${displayName} list --query priority=1")`,
     builder: (yargs) => {
       return yargs
         .command({
@@ -70,9 +70,13 @@ export function buildTicketCommands(table, displayName, alias, defaultColumns, s
 
               let selectedNumber;
               try {
-                selectedNumber = await select({
+                selectedNumber = await search({
                   message: `Select a ${displayName.slice(0, -1)}:`,
-                  choices,
+                  source: async (input) => {
+                    if (!input) return choices;
+                    const term = input.toLowerCase();
+                    return choices.filter(c => c.name.toLowerCase().includes(term));
+                  },
                 });
               } catch (err) {
                 if (err.name === 'ExitPromptError' || (err.message && err.message.includes('force closed'))) {

package/src/commands/auth.js

@@ -1,61 +1,211 @@
 import { getEffectiveInstance, normalizeInstanceURL } from '../config.js';
+import { errUsage } from '../errors.js';
+import process from 'node:process';
 
 export function authCmd(wrap) {
   return {
     command: 'auth <subcommand>',
-    describe: 'Manage authentication',
+    describe: 'Manage OAuth authentication',
     builder: (yargs) => {
       return yargs
         .command({
           command: 'login [instance]',
-          describe: 'Authenticate with a ServiceNow instance',
+          describe: 'Authenticate with a ServiceNow instance via OAuth',
+          builder: (sub) => sub
+            .option('code', {
+              describe: 'Authorization code from browser (bypasses interactive prompt)',
+              type: 'string',
+            })
+            .option('print-url', {
+              describe: 'Print the OAuth URL and exit (saves PKCE state for --code)',
+              type: 'boolean',
+            }),
           handler: wrap(async (argv, app) => {
-            const instance = argv.instance ? normalizeInstanceURL(argv.instance) : getEffectiveInstance(app.config);
-            if (!instance) {
-              throw new Error('No instance configured. Set via --instance or run: jsn setup');
+            let instanceURL;
+            if (argv.instance) {
+              // Check if it's a profile name first
+              const profiles = app.config.profiles || {};
+              if (profiles[argv.instance] && profiles[argv.instance].instance_url) {
+                instanceURL = normalizeInstanceURL(profiles[argv.instance].instance_url);
+              } else {
+                instanceURL = normalizeInstanceURL(argv.instance);
+              }
+            } else {
+              instanceURL = getEffectiveInstance(app.config);
+              if (!instanceURL) {
+                // Try interactive profile picker
+                const profileNames = Object.keys(app.config.profiles || {});
+                if (profileNames.length > 0 && app.isInteractive()) {
+                  const { search } = await import('@inquirer/prompts');
+                  const choices = profileNames.map(name => ({
+                    name: `${name} — ${app.config.profiles[name].instance_url}`,
+                    value: name,
+                  }));
+                  const selected = await search({
+                    message: 'Select a profile:',
+                    source: (input) => {
+                      const filter = (input || '').toLowerCase();
+                      return choices.filter(c => c.name.toLowerCase().includes(filter));
+                    },
+                  });
+                  instanceURL = normalizeInstanceURL(app.config.profiles[selected].instance_url);
+                } else {
+                  throw errUsage(`Instance URL required.
+
+Examples:
+  jsn auth login https://dev12345.service-now.com
+  jsn auth login dev373698
+  jsn auth login https://acme.service-now.com
+
+Find your instance URL in your browser's address bar when logged into ServiceNow.`);
+                }
+              }
+            }
+
+            // --print-url: just print the URL and exit
+            if (argv.printUrl) {
+              const authURL = app.auth.buildAuthURL(instanceURL);
+              console.log(authURL);
+              return;
+            }
+
+            // --code: exchange the provided authorization code directly
+            if (argv.code) {
+              await app.auth.loginWithCode(instanceURL, argv.code);
+            } else {
+              // Interactive: full OAuth flow with browser + prompt
+              await app.auth.login(instanceURL);
             }
-            await app.auth.login(instance);
-            app.ok({ authenticated: true, instance }, { summary: `Authenticated with ${instance}` });
+
+            // Verify auth by fetching current user
+            let username = '';
+            try {
+              if (!app.sdk) {
+                const { SDKClient } = await import('../sdk.js');
+                app.sdk = new SDKClient(instanceURL, app.auth);
+              }
+              const user = await app.sdk.getCurrentUser();
+              username = user?.user_name || user?.name || '';
+            } catch {
+              // Non-fatal — token is saved, just couldn't verify
+            }
+
+            // Save to profiles
+            const profileName = instanceURL.replace(/https?:\/\//, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '-');
+            if (!app.config.profiles) {
+              app.config.profiles = {};
+            }
+            app.config.profiles[profileName] = {
+              instance_url: instanceURL,
+              auth_method: 'oauth',
+              username: username || undefined,
+            };
+
+            // Set as default if this is the first one
+            const setDefault = !app.config.instanceURL && !app.config.defaultProfile;
+            if (setDefault) {
+              app.config.instanceURL = instanceURL;
+              app.config.defaultProfile = profileName;
+            }
+
+            const { saveConfig } = await import('../config.js');
+            saveConfig(app.config);
+
+            const result = {
+              authenticated: true,
+              instance: instanceURL,
+              username: username || undefined,
+              default: setDefault || undefined,
+            };
+            const summary = username
+              ? `✓ Authenticated to ${instanceURL} as ${username}`
+              : `✓ Authenticated to ${instanceURL}`;
+            app.ok(result, { summary });
           }),
         })
         .command({
-          command: 'logout',
-          describe: 'Remove stored credentials',
-          handler: wrap(async (_argv, app) => {
-            const instance = getEffectiveInstance(app.config);
-            if (!instance) {
-              throw new Error('No instance configured');
+          command: 'logout [instance]',
+          describe: 'Remove stored OAuth credentials',
+          handler: wrap(async (argv, app) => {
+            let instanceURL;
+            if (argv.instance) {
+              instanceURL = normalizeInstanceURL(argv.instance);
+            } else {
+              instanceURL = getEffectiveInstance(app.config);
+              if (!instanceURL) {
+                throw errUsage(`No instance specified.
+
+Examples:
+  jsn auth logout
+  jsn auth logout https://dev12345.service-now.com`);
+              }
             }
-            app.auth.logout(instance);
-            app.ok({ logged_out: true, instance }, { summary: `Logged out from ${instance}` });
+            app.auth.logout(instanceURL);
+            app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
           }),
         })
         .command({
           command: 'status',
-          describe: 'Show authentication status',
+          describe: 'Show detailed authentication status',
           handler: wrap(async (_argv, app) => {
-            const instance = getEffectiveInstance(app.config);
-            if (!instance) {
-              app.ok({ authenticated: false, instance: null }, { summary: 'No instance configured' });
-              return;
+            const defaultInstance = getEffectiveInstance(app.config);
+
+            // Check environment auth
+            const envToken = process.env.SERVICENOW_OAUTH_TOKEN || '';
+
+            const profiles = [];
+            for (const [name, profile] of Object.entries(app.config.profiles || {})) {
+              const isAuth = app.auth.isAuthenticatedFor(profile.instance_url);
+              profiles.push({
+                name,
+                instance: profile.instance_url,
+                authenticated: isAuth,
+                default: profile.instance_url === defaultInstance,
+              });
             }
-            const isAuth = app.auth.isAuthenticatedFor(instance);
-            app.ok({ authenticated: isAuth, instance }, { summary: isAuth ? `Authenticated with ${instance}` : `Not authenticated with ${instance}` });
+
+            app.ok({
+              default_instance: defaultInstance,
+              authenticated: app.auth.isAuthenticated(),
+              environment_auth: envToken ? true : undefined,
+              profiles,
+            }, { summary: `${profiles.length} profile(s)` });
           }),
         })
         .command({
-          command: 'refresh',
-          describe: 'Refresh OAuth token',
-          handler: wrap(async (_argv, app) => {
-            const instance = getEffectiveInstance(app.config);
-            if (!instance) {
-              throw new Error('No instance configured');
+          command: 'refresh [instance]',
+          describe: 'Refresh OAuth token for an instance',
+          handler: wrap(async (argv, app) => {
+            let instanceURL;
+            if (argv.instance) {
+              // Check if it's a profile name or URL
+              const profiles = app.config.profiles || {};
+              if (profiles[argv.instance] && profiles[argv.instance].instance_url) {
+                instanceURL = normalizeInstanceURL(profiles[argv.instance].instance_url);
+              } else {
+                instanceURL = normalizeInstanceURL(argv.instance);
+              }
+            } else {
+              instanceURL = getEffectiveInstance(app.config);
+              if (!instanceURL) {
+                throw errUsage(`No instance specified and no default configured.
+
+Examples:
+  jsn auth refresh
+  jsn auth refresh https://dev12345.service-now.com
+  jsn auth refresh dev12345`);
+              }
             }
-            await app.auth.refreshToken(instance, await app.auth.getCredentialsFor(instance));
-            app.ok({ refreshed: true, instance }, { summary: `Token refreshed for ${instance}` });
-          }),
-        })
 
+            const creds = await app.auth.getCredentialsFor(instanceURL);
+            const refreshed = await app.auth.refreshToken(instanceURL, creds);
+            app.ok({
+              refreshed: true,
+              instance: instanceURL,
+              expires_at: refreshed.expires_at,
+            }, { summary: `✓ Token refreshed for ${instanceURL}` });
+          }),
+        });
     },
     handler: () => {},
   };