JSN - ServiceNow CLI

A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.

Installation

npm (recommended — cross-platform)

npm install -g @jacebenson/jsn

No compilation needed. Works on macOS, Linux, and Windows with Node.js 18+.

Note: As of v0.1.0, the latest dist-tag points to the Node.js implementation. This is the version you get with npm install -g @jacebenson/jsn.

Quick Start

# Interactive setup
jsn setup

# Check auth status
jsn auth status

# List incidents
jsn incidents

# Check for updates
jsn version --check

What's New in v0.1.0

Full feature parity — 128 tests, lint clean:

| Feature | Status | |---------|--------| | Incident management (CRUD) | ✅ | | Change request management (CRUD) | ✅ | | Service catalog requests (with attachments + variables) | ✅ | | Catalog tasks, generic tickets | ✅ | | User management (CRUD) | ✅ | | Group management (CRUD) | ✅ | | Group memberships and roles | ✅ | | Generic Table API (jsn records) | ✅ | | OAuth PKCE with keychain (shared auth store) | ✅ | | Bot/CI/CD auth flags (--code, --print-url) | ✅ | | Dev commands: flows, actions, includes, rules, ACLs, etc. | ✅ | | Script execution (jsn dev eval) via OAuth session flow | ✅ | | Interactive search-as-you-type pickers | ✅ | | Output formats: JSON, styled, markdown, quiet | ✅ | | Enriched requests show with attachments + variables | ✅ | | Categorized help system (CORE, DATA, DEV, CONFIG) | ✅ |

New Commands

• jsn version --check — Check npm registry for newer versions
• jsn skill — Manage the jsn AI agent skill file (for Hermes, Claude Code, etc.)
  • jsn skill show — Display the bundled skill
  • jsn skill fetch — Download latest skill from GitHub
  • jsn skill path — Show skill file locations
  • jsn skill install — Download + save to Hermes skills directory

Configuration

JSN uses a layered configuration system:

| Source | Priority | Description | |--------|----------|-------------| | Flags | Highest | --instance, --profile, --format | | Environment | High | SERVICENOW_INSTANCE_URL, SERVICENOW_FORMAT | | Local config | Medium | ./.servicenow/config.json | | Global config | Low | ~/.config/servicenow/config.json | | Defaults | Lowest | Built-in defaults |

Profiles

# Login to a new instance
jsn auth login https://dev12345.service-now.com

# List all profiles
jsn profiles list

# Switch to a different profile
jsn profiles use dev12345

# Show current profile
jsn profiles show

Commands

CORE

| Command | Aliases | Description | |---------|---------|-------------| | incidents | incident, inc | Manage IT incidents | | changes | change, chg | Manage change requests | | requests | request, req, ritm | Manage service catalog requests | | tasks | task, sctask | Manage service catalog tasks | | tickets | ticket | Query generic tickets |

DATA & ADMIN

| Command | Aliases | Description | |---------|---------|-------------| | records | - | Generic Table API for any table | | users | user | Manage users | | groups | group | Manage user groups | | groupmembers | gm | Manage group memberships | | grouproles | gr | Manage group roles |

DEVELOPMENT

| Command | Description | |---------|-------------| | dev flows | Manage Flow Designer flows | | dev actions | Manage action definitions | | dev includes | Manage script includes | | dev rules | Manage business rules | | dev clientscripts | Manage client scripts | | dev uiactions | Manage UI actions | | dev uipolicies | Manage UI policies | | dev tables | View table definitions | | dev columns | Manage column definitions | | dev import | Manage import sets | | dev acls | Manage access controls | | dev roles | Manage roles | | dev updatesets | Manage update sets | | dev scopes | Manage application scopes | | dev properties | Manage system properties | | dev logs | Query system logs | | dev rest | Raw REST API calls | | dev eval | Execute background scripts |

CONFIGURATION

| Command | Description | |---------|-------------| | setup | Interactive first-time setup | | auth | Manage OAuth authentication | | profiles | Manage instance profiles |

UTILITY

| Command | Description | |---------|-------------| | version | Show version (use --check for update check) | | skill | Manage the jsn AI agent skill file |

Usage Examples

Incidents

jsn incidents                              # List all
jsn incidents list --query "priority=1"    # Critical only
jsn incidents INC0010001                   # Show specific
jsn incidents create --description "Server down" --priority 1
jsn incidents update INC0010001 --data '{"state": "6"}'

Requests (with enriched details)

jsn requests show RITM0010001
# Output includes attachments + catalog variables:
# ─ Attachments ─
#   onboarding_form.pdf  (by John Smith, 2026-05-15 14:23:10)
# ─ Catalog Variables ─
#   Department:  Engineering
#   Urgency:  High

Development

jsn dev flows                              # List flows
jsn dev includes MyScriptInclude           # Show a script include
jsn dev rules                              # List business rules
jsn dev updatesets set "My Update Set"     # Set current updateset
jsn dev eval "gs.info('Hello World')"      # Run background script

Generic Table API

jsn records list --table incident --limit 10
jsn records list --table incident --query "priority=1^active=true"
jsn records get --table incident --sys-id abc123
jsn records create --table incident --data '{"short_description": "Test"}'

Output Formats

| Format | Flag | Description | |--------|------|-------------| | Auto (default) | --format=auto | JSON for pipes, styled for TTY | | JSON | --json or --format=json | Machine-readable JSON | | Styled | --styled | ANSI-styled tables | | Markdown | --markdown | Markdown tables | | Quiet | --quiet or -q | Data only, no envelope |

jsn incidents --json | jq '.[].number'
jsn incidents --styled
jsn incidents -q | jq '.[].number'

Authentication

OAuth 2.0 with PKCE. Credentials stored in ~/.config/servicenow/credentials/.

jsn auth login https://dev12345.service-now.com

# Bot-friendly: print auth URL instead of opening a browser
jsn auth login https://dev12345.service-now.com --print-url

# Paste code from browser
jsn auth login https://dev12345.service-now.com --code ABC123

CI/CD Integration

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_OAUTH_TOKEN="***"
jsn incidents list   # No interactive auth needed

AI Agent Integration

JSN includes a built-in skill file for AI agents:

# View the skill file
jsn skill show

# Download the latest skill from GitHub
jsn skill fetch | head -30

# Install to Hermes skills directory
jsn skill install

# Install to a custom location
jsn skill install /path/to/skills/

Environment Variables

| Variable | Description | |----------|-------------| | SERVICENOW_INSTANCE_URL | Default instance URL | | SERVICENOW_FORMAT | Default output format | | SERVICENOW_OAUTH_TOKEN | OAuth token (for CI/CD) | | JSN_NO_HEADER | Suppress context header |

Getting Help

jsn                          # Categorized help with command groups
jsn incidents --help         # Command details
jsn version                  # Show version
jsn version --check          # Check for npm updates

Development

git clone https://github.com/jacebenson/jsn.git
cd jsn
git checkout nodejs
npm install
npm test           # 128+ tests
npm run lint       # ESLint
npm run start      # Run CLI locally

Project Structure

├── src/
│   ├── cli.js              # Root CLI (yargs setup)
│   ├── app.js              # App context
│   ├── auth.js             # OAuth PKCE manager
│   ├── sdk.js              # ServiceNow REST API client
│   ├── output.js           # Output formatting
│   ├── config.js           # Configuration loader
│   ├── context.js          # Runtime context
│   ├── errors.js           # Structured error types
│   ├── helpers.js          # Shared utilities
│   ├── help.js             # Custom grouped help renderer
│   └── commands/           # CLI command modules
├── skills/
│   └── servicenow/
│       └── SKILL.md        # AI agent skill file
├── test/                   # Test suite
└── package.json

Releasing

npm run release -- patch    # or minor, major
# Creates node-v* tag, pushes to GitHub, publishes to npm

Troubleshooting

Not authenticated

⚠️  Not authenticated to https://dev12345.service-now.com

To get started, run:
  jsn setup
  jsn auth login

Instance URL required

Error (usage): Instance URL required. Set via --instance flag,
               SERVICENOW_INSTANCE_URL env, or config file.

Outdated version

jsn version --check
# → jsn 0.0.10 — newer version 0.1.0 available
npm install -g @jacebenson/jsn

License

MIT License — see LICENSE file for details

Acknowledgments

This project follows architectural patterns from basecamp-cli.

| Project | What we learned | |---------|----------------| | Abey's sn CLI (Rust) | Table API patterns, aggregate stats, raw REST passthrough | | ServiceNow now-sdk | OAuth session flow for UI pages | | ServiceNow VS Code Extension | sys.scripts.do CSRF extraction | | Getting Real by Basecamp | Build less, start with no, embrace constraints |