jsn / ServiceNow, simplified.

THE JSN HANDBOOK

CLI guide

The command surface, discovery paths and conventions for finding the right command before using it.

JSN CLI guide

A command-line interface for ServiceNow. Type jsn and start working — no web UI needed.

Works standalone or with AI agents (Claude Code, OpenCode, Hermes, Cursor, Copilot).

Install

npm install -g @jacebenson/jsn

Current Node.js LTS release. macOS, Linux, Windows.

The install also copies an AI agent skill file to ~/.agents/skills/servicenow/SKILL.md.

Install from GitHub (test unreleased builds)

The publishable package lives in cli/, not the repository root. To test an unreleased branch, clone the repository, check out the exact branch or revision, and install its dependencies before running the checkout's executable:

git clone https://github.com/jacebenson/jsn.git
cd jsn
git checkout <branch-or-revision>
npm --prefix cli ci
node cli/bin/jsn.js version
node cli/bin/jsn.js --help

For the published development channel, use npm install -g @jacebenson/jsn@dev. To install a checkout globally, run npm install -g ./cli from the repository root. Direct github:jacebenson/jsn#<branch> installs address the private root package and do not install the CLI.

Go back to the released version with:

npm install -g @jacebenson/jsn

Requires Node.js 24 or newer. SQLite is built into Node.js, so npm and git installs do not need Python, make, or a C++ compiler. Local docs indexing/search requires FTS5 in the installed Node build and checks this at runtime. Use a current official Node.js 24 LTS or newer build if FTS5 is unavailable. Hosted docs search does not load SQLite.

Direct MID installation

jsn midservers add --install-method direct --name worker1

Official x86-64 ZIPs for Linux and Windows, selected from the instance's mid.version. Credentials are prompted and validated before installation. Linux supports a user-owned background runtime. Windows currently prepares private files and offers a foreground console, not native service registration. See direct MID installation for security boundaries, lifecycle commands and the untested Windows host phases. Docker remains available.

Create an update set in a scope

jsn updatesets create --name "Workspace changes" --scope sn_sow

--scope accepts a scope value, application sys_id, or display name, using the same resolver as jsn scopes set. JSN selects and verifies the application before creating the update set in that application, then selects the new set. An unknown, ambiguous, or unselectable scope stops creation. Omit --scope to keep the existing behavior.

The scope switch persists if creation later fails. If creation succeeds but selecting the new set fails, the output reports the created record and a warning. Inspect that record rather than rerunning create and making a duplicate.

Customization reports

jsn customizations capture --label before-upgrade --customer-scope x_acme_app
jsn customizations list
jsn customizations show <run_id>
jsn customizations html <run_id>                 # writes customizations-<run_id>.html
jsn customizations html <run_id> --out review.html
jsn customizations compare <baseline_id> <new_id> --json
jsn customizations show <run_id> --get data.coverage
jsn customizations show <run_id> --get data.triage

Capture data access uses Table API GET requests only. Captures never run background scripts or create, update or delete instance records. Standard authentication still applies, including OAuth refresh, local refreshed-credential storage and session/GCK bootstrap, which can make authentication POST requests. Expired credentials without a usable refresh token require login. Reports are private local JSON files in $JSN_DATA_HOME/customizations, defaulting to ~/.jsn/customizations. List, show and compare work offline. Interactive terminals offer local report pickers; pass explicit IDs with JSON, pipes or --get.

The bounded inventory joins visible sys_metadata, sys_scope and sys_upgrade_history_log records. ootb_modifications contains artifacts with historical skipped-upgrade evidence, not a verified current OOTB diff. Because the broad sys_metadata read is an arbitrary sys_id-ordered slice (994 of 621972 rows on a large instance), it is reported as a bounded sample, not an inventory: it only ever describes the rows the page budget reached. The skipped-upgrade artifacts are inventoried separately and completely for the observed history: after the filtered upgrade-history read, every observed sys_update_name is resolved with chunked GET-only sys_update_nameIN<chunk of names> lookups on sys_metadata, so an artifact with skipped-upgrade evidence appears in ootb_modifications even when it falls far outside the sample. coverage.upgrade_evidence reports the skipped rows observed, the distinct update names, how many resolved by direct lookup, the unresolved name list and any failed lookup chunks. customer_app_artifacts contains only scopes explicitly declared with repeatable --customer-scope values or sys_ids. The instance verifies the scope identity, not its ownership. Installed/vendor scopes are never automatically called customer-built. Other visible artifacts remain unclassified, and both those categories cover only what the bounded sample read.

Each item reports identity, scope, evidence, unknown risk with rationale and a review recommendation. Historical OOTB findings include the known skipped-upgrade impact and explicit unknown baseline, runtime impact and dependencies. No reversion is performed or recommended as safe without further investigation.

show adds a computed data.triage view with evidence confidence, the reason for the classification and concrete review steps; it does not alter saved captures or pretend to score risk. html exports a self-contained offline report with search, classification filters, grouping, evidence, coverage and links back to records. The default output is customizations-<run_id>.html; existing files are never overwritten. The report does not change ServiceNow records.

Defaults are 100 records per page and 10 pages per source. Adjust --page-size and --max-pages within the documented limits. Source coverage compares the rows fetched with the Stats API count for the same query and reports both. A page shorter than the requested size never implies exhaustion; exhausted is reported only when the fetched rows account for the available total, and an unavailable count is reported as unknown rather than implied completeness. Other statuses distinguish missing fields, unstable pagination and read failures. Both the count and the rows reflect visible ACL-filtered records, so hidden rows cannot be ruled out and reports remain incomplete. An empty category does not prove that no customizations exist. A 2xx table body without a result array is treated as an unavailable source, never as an empty table.

Comparisons show newly observed, no-longer-observed and changed metadata/evidence. They ignore local capture IDs, labels, timestamps and enumeration order. They do not prove record creation/deletion or detect source-body changes without captured metadata changes. Changed entries render the concrete before/after field values, and additions/removals list the artifact's name, table, scope, category and evidence basis. When either report has an unavailable or empty source, the comparison status is unreliable and those differences are labelled as missing coverage instead of mass creation or deletion. Compare only reports from the same instance.

Provider contract: ServiceNow Customizations Unchanged explains that the Skipped disposition preserves customizations. Other skip reasons are not treated as equivalent evidence. This command cannot establish a trusted baseline from that history alone.

The verified provider join is sys_upgrade_history_log.file_name to sys_metadata.sys_update_name, not the log's nonexistent name field. Capture uses raw values from sysparm_display_value=all: disposition 4 or 104 means Skipped or Skipped (second pass). Resolution reviewed_reverted excludes that history row; a present empty resolution is distinct from a missing field. The upgrade-history read is filtered server-side to those dispositions so a bounded capture spends its pages on preserved-customization evidence instead of arbitrary history rows, and unmatched_upgrade_records counts only that filtered population, not all upgrade history. The filtered history is the unit of the inventory claim: every observed file_name is then resolved against visible sys_metadata with chunked GET-only sys_update_nameIN<chunk> lookups, so skipped artifacts are inventoried from the history instead of from the arbitrary sys_id-ordered metadata sample. unmatched_upgrade_records and coverage.upgrade_evidence.unresolved_update_names describe only names no visible metadata row matched; a failed lookup chunk is reported rather than treated as an absent artifact. These values were checked against the PDI dictionary, choices and actual joined rows. Display labels are not used for classification.

Quick Start

jsn setup                                    # Interactive: add, switch, remove, modify instances
jsn incidents list --query "priority=1"      # Critical incidents

What It Does

jsn talks to the ServiceNow REST API. Read, create, update, delete — tickets, users, groups, records on any table. Inspect flows and business rules. Export update sets. Run background scripts.

Everything outputs JSON when piped, styled tables in a terminal.

# Core ticket work
jsn incidents list --query "active=true^priority=1"
jsn incidents INC0010001
jsn incidents create --description "Server down" --priority 1

# Admin tasks
jsn flows list                                # Interactive picker with pagination
jsn flows show "Assign Task"                  # Full flow detail
jsn flows executions                          # All states, newest first
jsn flows executions --active                  # Only waiting/running/queued
jsn flows executions --since "2026-08-25 00:00:00" --until "2026-08-26 00:00:00"
jsn flows executions --summary                 # Server totals + sampled duration metrics by flow
jsn flows executions --limit 100               # Inspect more rows from the matching population
jsn flows executions --record <sys_id>        # Executions for one source record
jsn flows create --data-file flow.manifest.json # Create a draft record-triggered flow
jsn workflows list --table incident             # Legacy Workflow Editor, read-only (wf_* tables)
jsn workflows show "Incident approval"          # Versions, activities, transitions, conditions, scripts
jsn rules list --query "collection=incident"
jsn updatesets set "My Feature"

# Generic table access
jsn records list --table incident --limit 50 --json | jq '.data.records[].number'
jsn records create --table incident --data '{"short_description":"test"}'
jsn records list --table incident --limit 50 --get "data.records.0.number"   # no jq needed
jsn records list --table incident --query "active=true"                       # totals included by default
jsn records list --table incident --limit 10 --no-count                       # opt out of the total query
jsn records bulk --table incident --query "priority=1" --set '{"state":"3"}'  # dry-run by default
jsn records get --table incident --sys-id 8a1234abcd5678 --attachments        # record + its files
jsn records list --table incident --limit 10 --csv                            # output CSV

# Attachment transfers (standalone, also discoverable via jsn attachments --help)
jsn attachments list --sys-id <record-id> --json
jsn attachments download <attachment-id> --out ./report.pdf
jsn attachments upload ./report.pdf --table incident --sys-id <record-id>
# get/add alias download/upload; uploads require confirmation, or --force after approval.
# Downloads refuse existing files unless --overwrite is explicitly supplied.

# Read-only cross-profile record diff
jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod
jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --ignore state
jsn diff record --table incident --sys-id <sys_id> --profile-a dev --profile-b prod --no-ignore

# Script execution
jsn eval "gs.info('Hello World')"
cat script.js | jsn eval --stdin          # pipe a script in (no shell escaping)

# Interactive background-script mode for trying successive scripts.
# Each .exec is its own server request: variables do not persist between
# submissions, while database writes do. .clear .help .exit; Ctrl+D exits.
jsn eval --repl --profile dev --scope x_my_app

# Now GraphQL (documents may contain mutations; read-only profiles are blocked)
jsn graphql --query '{ GlideRecord_Query { incident(pagination: {limit: 2}) { _results { number { value } } } } }'
cat incident.graphql | jsn graphql --stdin --variables '{"limit":2}'

# Saved query snippets (stored locally, run against the active profile)
jsn snippets save open-inc --table incident --query "active=true"
jsn snippets run open-inc

# Live log tailing (Ctrl+C to stop)
jsn logs follow --level error --tail 10

Update set completion

jsn updatesets complete                         # Current set, opens a notes editor in a human terminal
jsn updatesets complete "My Feature" --notes "Fixed validation" --force --json

complete [name] saves concise bullet-list notes in the selected set's Description and marks it complete. Omit the name to use the current set. Explicit names must be unique; for duplicate names, select the intended set with updatesets set and complete it without a name. ServiceNow's normal batch completion rules still apply: completing a parent can complete its children. Notes are not copied to children.

Existing Description text is preserved exactly. The command shows it and asks before appending notes, unless --force or the profile's skip_confirmations policy explicitly allows the append. Scripts and JSON output must supply nonempty --notes; they never open prompts. Separate multiple notes with real newlines. Success requires readback of both Description and state. If verification fails, inspect the set before retrying because the write may have partially succeeded.

Update set transfer

jsn --profile source updatesets export "Digital Helpdesk 0.1.77"   # auto-named XML here
jsn --profile target updatesets import transfer.xml --dry-run --json
jsn --profile target updatesets import transfer.xml --yes
jsn --profile target updatesets preview "Digital Helpdesk 0.1.77" --yes
jsn --profile target updatesets problems "Digital Helpdesk 0.1.77"
jsn --profile target updatesets commit "Digital Helpdesk 0.1.77" --yes

Export never changes the set's state and keeps raw XML when piped. Import loads a retrieved update set and stops; preview and commit drive the platform's own CICD Update Set API steps and follow their progress trackers. problems is read-only: jsn never accepts, skips, or ignores a preview problem, and commit refuses while any remains unresolved. Both mutating steps verify previewed / committed by readback. See update-set-transfer.md.

Flow Designer actions

actions and action are the same command. list, show, and explicit delete remain available. In a human terminal, omit the target to open a searchable picker. Create and edit guide you through provider schemas and save full Process Flow definitions, not ordinary table-field updates.

jsn actions create                 # Guided scope, name, schemas, inputs and script
jsn actions edit                   # Pick an action, edit its saved definition
jsn actions definition             # Pick and inspect a complete definition
jsn actions test --wait            # Pick an action, supply saved-schema inputs, confirm
jsn actions step-types             # Pick the exact transaction scope

Script inputs offer a file path or your $VISUAL/$EDITOR. New script steps can declare outputs and map them to action outputs. Variable declarations reuse provider schema templates and receive fresh UI identities. Unknown nested schema fields are retained. Unsupported input types stop with instructions to use --data-file; JSN does not silently omit them or invent schema defaults. Creation waits for an explicit final confirmation before allocating a parent. It saves a draft only and never publishes or runs it automatically.

For automation, keep using explicit identifiers and full JSON:

jsn actions step-types --scope <scope_sys_id> --get data > step-types.json
jsn actions create --scope <scope_sys_id> --data-file new-action.json --json
jsn actions definition <action_sys_id> --get data > action.json
# Edit action.json, retaining its ID, scope, lifecycle fields and all arrays.
jsn actions update <action_sys_id> --data-file action.json --json
jsn action edit <action_sys_id> --data-file action.json --json  # same operation
jsn actions test <action_sys_id> --force --output-map '{"response":"hello"}' --wait --timeout 60 --json
jsn actions test <action_sys_id> --force --data-file action.json --output-map '{"response":"hello"}' --wait --get data.outputs.response.value
jsn actions delete <action_sys_id> --force  # explicit cleanup, never automatic

Existing targets infer their exact transaction scope from the action record. An explicit --scope must match that record byte-for-byte and exist in sys_scope. For Global, use the literal sys_id global.

This illustrative create document shows an input/script/output mapping. Replace <SCRIPT_STEP_TYPE_SYS_ID> with the target's step-types result. Start from that step type's full input/output schemas, preserving runtime settings, status outputs and any other required fields. The shortened example is not a captured or instance-verified template. New steps/variables need their own identifiers; do not clone another action's record IDs. Leave new steps' step_id and action blank or omitted. Create binds their action to the newly allocated parent; persisted step IDs or parent bindings are rejected before creation.

{
  "name": "Echo response",
  "description": "Return the supplied response",
  "internal_name": "echo_response",
  "inputs": [{"name": "response", "label": "Response", "type": "string", "mandatory": true}],
  "outputs": [{"name": "response", "label": "Response", "type": "string", "value": "{{step[11111111-2222-4333-8444-555555555555].response}}"}],
  "steps": [{
    "cid": "11111111-2222-4333-8444-555555555555",
    "step_type": "SCRIPT",
    "step_type_id": "<SCRIPT_STEP_TYPE_SYS_ID>",
    "label": "Echo script",
    "order": 1,
    "inputs": [
      {"name": "required_run_time", "type": "choice", "value": "instance"},
      {"name": "script", "type": "script", "value": "(function execute(inputs, outputs) { outputs.response = inputs.response; })(inputs, outputs);"}
    ],
    "outputs": [],
    "extended_inputs": [{"name": "response", "type": "string", "value": "{{inputs.response}}", "extended": true}],
    "extended_outputs": [{"name": "response", "type": "string", "extended": true}]
  }]
}

Create first inserts the parent in sys_hub_action_type_definition, reads that parent's own Process Flow defaults, then saves the inputs, outputs and nonempty steps with the internal /api/now/processflow/action/action_types/{id} PUT. It retains fresh lifecycle/status metadata instead of copying source snapshot or status IDs. A subsequent definition GET plus /step_instances GET verifies scripts, mappings and schemas. Update requires a complete document from definition, including target-owned lifecycle fields. Omitted fields are rejected before mutation. A PUT timeout triggers readback, not another PUT; persisted_after_timeout means persistence was verified, not that HTTP success was received. Failed creation reports the parent ID and leaves cleanup to you.

Test sends action, outputMap, runOnThread and tracingEnabled to /test. Despite its wire name, --output-map supplies action inputs. Without --wait, success means dispatch only, with status: dispatched and no outputs. With --wait, JSN requires a COMPLETE context, blank error_message, and each declared user output's actual value from sys_flow_runtime_value. Output entries have value, displayValue and hasValue; false, zero and empty strings count. Failures, denied/missing outputs and timeouts exit nonzero. The wait budget starts after dispatch, defaults to 60 seconds, and is capped at 3600 seconds. Timeout does not cancel the server execution. Draft actions can be tested without publication. Testing runs their scripts and can have side effects. It requires interactive confirmation or --force, unless the profile explicitly skips confirmations. Read-only profiles block create/update/delete/test. No publish or snapshot command is added. These internal endpoints and runtime-table permissions can vary by instance.

Flow execution fields

Flow Designer terminal workflows

jsn flows create         # Guided record trigger and published action inputs
jsn flows edit           # Pick a flow, edit condition or existing inputs (drafts, and published flows you can write)
jsn flows show           # Pick a flow to inspect
jsn flows status         # Pick a flow to diagnose
jsn flows test           # Pick flow and a record from its actual trigger table, confirm
jsn flows publish        # Pick a flow, explicitly confirm activation
jsn flows unlock         # Release this user's stale safe-edit lease after a failed update
# Automation must explicitly confirm publication too:
jsn flows publish <flow_sys_id> --force --json

Wizards and omitted-target pickers require both a prompt-capable terminal and auto output. --json, explicit formats, --get, --data, --data-file, --output-map, pipes, CI, NONINTERACTIVE and JSN_NO_PROMPTS=1 never open a wizard. In those modes provide identifiers and required scope/record/data explicitly. Tests, publish and deletion require --force or the profile's existing explicit skip-confirmations setting when prompting is unavailable. Read-only profiles still block mutations before authentication or prompting. Press Escape in any prompt or record picker to cancel; Ctrl+C aborts as well. Refusing a final confirmation leaves the instance untouched.

Existing action/flow scopes come from saved raw identifiers. New scopes offer the active application preference if available, then a searchable scope picker. No scope name is guessed. Input pills are passed through unchanged.

Flow edits are limited to the existing manifest contract. They do not rename flows, add/remove steps, implement Flow Logic, subflows, variables or error handling. Flow deletion remains unsupported. Action deletion retains its existing explicit parent-record cleanup and absence readback, not a new native builder deletion lifecycle. See command coverage and local proof.

Flow creation manifest

jsn flows create accepts --data-file or inline --data, or guides human terminal users without those options. The supported slice supports one record_create_or_update trigger and published Action types whose input schemas are available from the instance. JSN resolves action metadata, defaults, and typed inputs from ServiceNow; callers do not provide GraphQL or editor-generated identifiers.

{
  "name": "JSN-STUDY-ticket-log",
  "description": "Log JSN study tickets",
  "scope": "<SCOPE_SYS_ID>",
  "trigger": {
    "type": "record_create_or_update",
    "table": "ticket",
    "condition": "short_descriptionSTARTSWITHJSN-STUDY-"
  },
  "actions": [
    { "type": "Log", "inputs": { "log_level": "info", "log_message": "Ticket received" } }
  ]
}

scope is required; JSN never defaults it to a tenant-specific or captured scope. The record-trigger condition currently accepts one simple encoded-query predicate (fieldSTARTSWITHvalue, field=value, fieldLIKEvalue, and the equivalent single-predicate operators). Compound ^/^OR expressions are rejected until their predicate AST mapping is proven against the instance.

Creation leaves the flow in Draft and inactive, then creates and reads back an Autosave version. flows publish remains a separate lifecycle operation: it reads the saved ProcessFlow definition, POSTs /snapshot, creates an Activate/Publish version, reads version history, and verifies active=true. Do not use it in a dry-run: publishing activates the flow.

jsn flows test <identifier> --record <sys_id> is also a mutating operation. It requires confirmation (or --force), reads the saved definition, verifies that the supplied record exists in the record-trigger table, and POSTs the full definition to the ProcessFlow test endpoint. A response with only a context ID is reported as accepted, not completed. Test runs execute actions and can have side effects; this slice does not execute test flows during development.

Flow Logic, subflows, flow-variable lifecycle, and error handling are deferred and rejected by this slice rather than silently ignored.

jsn flows update <identifier> --data-file update.json updates supported fields of existing Draft flows, and of published or active flows whose ProcessFlow definition reports security.can_write=true. The manifest may contain only trigger (with table and/or condition) and actions. Each action selects one saved instance by its one-based order and reusable action type (name or sys_id). Its inputs object may change only inputs already present in that saved Action. The CLI reads the saved component identities itself; manifests never carry UI UUIDs. Omitted trigger fields, Action inputs, metadata, and other flow components are preserved. Names must resolve to exactly one flow, and the protected jace-test-flow is rejected. Update sends the captured GraphQL triggerInstances.update and/or actions.update shapes, reads the full ProcessFlow definition back, creates an Autosave version, and reports update-set captures. It never publishes or activates the flow. A published flow is edited as its working definition: the published snapshot, its version rows and the parent active, status, master_snapshot, latest_snapshot and version_record pointers are compared before and after, and a change fails the command loudly instead of being reported as a safe edit. A published flow whose definition reports security.can_write=false (or no security.can_write) is refused before any edit session or content write, naming the permission rather than the lifecycle. Unsupported Flow Logic, subflows, variables, error handling, new Action inputs and ambiguous selectors are rejected before mutation.

jsn flows executions reads sys_flow_context and returns both the raw row and a normalized execution object. JSN discovers the runtime columns from sys_dictionary first, then uses these mappings:

  • started: started, start_time, started_at, then sys_created_on
  • ended: ended, end_time, ended_at, then completed_on
  • duration_seconds: stored duration, run_time, or execution_duration, otherwise ended - started
  • waiting_age_seconds: current time minus started while the status is waiting, queued, paused, or pending
  • execution_age_seconds: current time minus started while the status is running, executing, or processing
  • status: state, then status, then execution_state
  • error: error, error_message, exception, then message

The timestamp fields are instance-dependent. sys_created_on is a fallback for when the context row was created, not a claim that it is the true runtime start time.

Commands

Run jsn for the full grouped list. Commands are organized by ServiceNow domain:

Core — incidents, changes, requests, tasks, tickets

Automation — flows, actions, rules, scrapi, updatesets, eval, rest

Upgrade review — skipped-updates discovers existing unresolved skips, reviews current/base field changes and known dependencies, and processes only explicitly selected actions after an exact batch preview and one confirmation.

Access — acls, roles, scopes, properties, privileges

User Experience — forms, lists, clientscripts, uipolicies, uiactions

Data — records (list/get/create/update/delete/count/bulk), attachments (list/download/upload), diff record (cross-profile read-only comparison), tables, columns, includes, import, logs (list/show/follow), snippets (save/run), users, groups

Platform — platform health (cluster records) and platform stats (bounded, read-only /xmlstats.do summary; allowlisted metrics only)

Every command supports --json, --query, and --help.

For multiline script fields, --data-file parses the file as UTF-8 JSON and passes the resulting values through unchanged. On Windows PowerShell, generate the payload as JSON text and inspect it before invoking JSN, for example:

$script = [string](Get-Content -Path .\Example.script.js -Raw)
$payload = @{ script = $script; description = 'Example' } |
  ConvertTo-Json -Depth 5 -Compress
Set-Content -Path .\Example.update.json -Value $payload -Encoding UTF8
Get-Content .\Example.update.json -Raw | ConvertFrom-Json | Select-Object -ExpandProperty script
jsn includes update Example --data-file .\Example.update.json --json

JSON.parse preserves a JSON string as a JavaScript string, and the SDK serializes update payloads with JSON.stringify. If the file already contains a {value=...} or FileSystem-provider representation, that text is external to JSN and must be corrected before the update. Use a read-back command or records update --strict where applicable to verify persisted fields.

Instances

Switch between instances without re-authenticating.

jsn setup                    # Guided login and connection management
jsn auth status              # Compact profile status table

jsn setup is the human front door. It collects answers and calls the same operations as auth: add, sign in again, status, choose a default, change settings, sign out, and remove. For scripts and CI, use explicit commands (Basic login below reads SN_USERNAME/SN_PASSWORD from the environment):

jsn auth login dev12345 --name work --basic --read-only --make-default --json
jsn auth refresh --profile work                   # Refresh an OAuth profile
jsn auth switch work                             # Explicitly choose the default
jsn auth modify work --read-only --no-include-counts --confirm-deletes --json

Output Formats

Flag When to use
(default) Terminal — styled tables
--json Pipelines, scripts
--markdown Documentation
--quiet / -S Data only, no envelope
--csv Spreadsheets (opens straight into Excel)
--tsv / --format=tsv Compact flat lists separated by real tabs
--get <path> / --select <path> Extract a value, e.g. --select 'data.records[0].number'
--raw Print selected strings without JSON quotes
--verbose Restore JSON summaries, breadcrumbs and two-space indentation

JSON is compact by default and omits top-level summary and breadcrumbs. It retains record data, pagination, context and error details. Human formats are unchanged. Extraction accepts both data.records[0].number and data.records.0.number; non-string --raw results remain compact JSON.

-q now means --query, not quiet. It works on commands that declare query support and errors on commands that do not. For example:

jsn records list --table incident -q 'active=true' --json
jsn records list --table incident -q 'active=true' --select 'data.records[0].number' --raw

Table API list reads omit reference links by default. Add --include-reference-links to request the provider's reference-link objects. Counted list responses include data.pagination.hasMore; records lists omit that field when totals are unavailable or disabled with --no-count. Ticket lists can instead set it from page fullness, without a known total.

CSV stdout contains only the header and record rows, including on a terminal. When a records envelope explicitly reports pagination.hasMore: true, one notice goes to stderr with the returned page count, total if known, and next offset when the envelope supplies a valid offset and limit. The next offset advances by the requested limit, not the number of returned rows. A notice with an unknown total does not establish how many records remain. Complete results emit no pagination notice; absent hasMore is not proof of completeness.

jsn records list --table incident --limit 2 --csv > incidents.csv 2> pagination.log

A CSV reader consuming only stdout will not see this notice. Capture and check stderr separately, and do not merge it into the CSV stream with 2>&1. For automation that needs structured pagination metadata, use --json instead. CSV does not fetch subsequent pages automatically.

TSV cells and terminal spacing

jsn records list --table incident --columns sys_id,number,state --limit 5 --tsv

--tsv and --format=tsv are equivalent. TSV shares CSV's row selection: headers come from the first record's keys, reference objects prefer display_value, then value, and other objects/arrays become JSON cell strings. Null and missing cells become empty strings (indistinguishable from an empty string); empty results emit no bytes, not a header. CSV/TSV do not preserve both reference IDs and labels. JSON preserves reference objects only when the command has retained them; an earlier scalar projection cannot recover discarded IDs.

Fields and headers escape backslash as \\, tab as \t, newline as \n, and carriage return as \r. Each record occupies one physical line, with real tabs between cells and LF between records. Quotes have no special meaning. To parse, split lines and tabs before decoding those four backslash escapes in one pass; decode JSON-valued cells separately afterward if needed.

Tabs use the viewer's tab stops, not padded column widths. Long values can cross a tab stop, so TSV does not guarantee visually aligned columns. Use the default styled terminal view for padded tables.

Like CSV, TSV keeps summaries and pagination footers off stdout and sends a TSV pagination: notice to stderr only when hasMore is explicitly true. Silence (including --no-count) does not prove completeness. Capture stderr separately; use JSON when automation needs pagination metadata. Neither format fetches additional pages. --get/--select extraction still takes precedence.

Authentication

jsn auth status shows a compact table of profiles, methods, credential state, connection verification, and read-only/delete-confirmation/count settings. The selected and default profiles are labeled explicitly. Usernames and instance URLs are hidden by default, including in JSON; add --details to include the User and Instance columns and their JSON fields. Use jsn --profile <name> auth status to focus on one profile, or add --local to inspect saved state without contacting any instance. Scripts extracting default_instance, profiles.*.instance, username, or verified_as must include --details.

When jsn auth login <instance> creates a profile interactively, it offers the same read-only, delete-confirmation, and result-count options as setup. Scripts can supply --read-only, --no-include-counts, and --confirm-deletes. The compatible --skip-confirmations disables delete prompts. jsn auth modify <profile> accepts the same setting flags; repeating a request sets the same values. Without flags, humans get a settings picker; scripts get a structured usage error. Reauthentication preserves existing preferences.

Use --name <new-name> to create another connection, including a second user on the same instance, and --profile <existing-name> to reconnect. Setup asks whether to use a connection by default. Scripts must pass --make-default or run auth switch; even a first login does not silently set a default.

JSN supports OAuth 2.0 with PKCE, Basic Auth, and browser-session auth. Persisted credentials require the OS keyring (secret-tool/libsecret). If a save or its exact readback fails, JSN refuses rather than silently writing plaintext. Environment-only authentication does not require credential persistence.

For an explicitly accepted headless plaintext fallback, set JSN_ALLOW_PLAINTEXT_CREDENTIAL_STORAGE=1 on the individual JSN process (for example, prefix your jsn auth login command). Only the exact value 1 enables it; project/profile configuration cannot enable it. Do not put this override in a project, shell startup file, or shared environment. A fallback read or write warns on stderr, and loaded credentials report auth_source: file. The override still prefers the keyring; it is not an encryption mode. Credential JSON under ${XDG_CONFIG_HOME:-~/.config}/servicenow/credentials/ contains reusable secrets. A directory copy or backup can transfer access, subject to provider token policy. Exclude these files from sync, source control, shared volumes, and backups.

Existing fallback files do not implicitly enable insecure storage. Reads, including local status, never migrate or persist credentials. With no keyring entry, JSN refuses a fallback read unless the process explicitly opts in. To migrate an existing credential, unlock/install the keyring, opt in for one process, then save through login or an ordinary token refresh. Alternatively, reauthenticate with the working keyring without opting in. Every secure save verifies exact readback before unlinking that identity's old plaintext file; failed verification preserves the original. Other users' entries are untouched. Unlinking is not secure erasure and cannot remove backups, snapshots, copied files, or filesystem remnants. If credentials were copied unintentionally, revoke/rotate them at the provider and remove exposed copies; deleting a local file does not revoke a token.

Credential and pending PKCE files use atomic same-directory replacement. On POSIX, files require 0600 modes and leaf directories require 0700 modes. Unsafe existing modes, unexpected ownership, hard-linked files, symlinks, and writable ancestors are refused rather than automatically chmodded or followed. Inspect and manually repair or move the exact owned path before retrying (never apply recursive chmod to your home/config tree). JSN does not change permissions on broad parent directories. PKCE state is necessarily a local plaintext login secret; it receives the same path protections, independent of the credential-storage override.

On Windows, POSIX mode/UID checks are not applied: Node's mode bits do not validate Windows DACLs. Files and directories inherit their parent's ACL; JSN does not set or verify those ACLs. Use a private per-user config directory and verify its ACL separately; do not use shared or broadly writable locations. Regular-file/directory, hard-link and lstat-detectable symlink/junction rejection still apply, but Node cannot identify every reparse-point type or eliminate same-user path races. PKCE remains a local plaintext login secret on Windows. Persisted credentials still require verified keyring storage by default; using portable plaintext on Windows requires the same explicit process-only opt-in and warning. No Windows ACL protection or secure-erasure guarantee is implied.

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

For Basic Auth, set SN_USERNAME and SN_PASSWORD, then run jsn auth login --basic <instance>.

If the instance requires TOTP MFA, Basic requests prompt for a masked six-digit authenticator code before sending the operation. Escape cancels cleanly. Noninteractive, --json, and --get invocations fail with mfa_required and guidance instead of prompting. JSN never stores TOTP seeds or generates codes. Configure OAuth or a browser session explicitly for unattended use. MFA failure never switches authentication methods or sends the pending operation. See the authentication lifecycle for timeouts, identity verification, and the fixture-only verification boundary. For browser-session auth, run jsn auth login --gck <instance> and paste the request headers when prompted.

OAuth from scripts or a remote terminal

jsn auth login dev12345 --name work --oauth --print-url --json
jsn auth login dev12345 --name work --oauth --code "$CODE" --read-only --json

The first result contains data.authorization_url and a completion command. Keep the same instance and profile name when exchanging the code. The existing --print-url --wait-file <path> flow remains available. Progress goes to stderr; JSON results and auth errors remain machine-readable. Noninteractive login without a code or URL request returns a usage error instead of prompting.

Log in using a browser (experimental)

Run jsn setup, enter the instance and profile name, and choose Browser session. Choose an installed browser when prompted, then sign in in the window JSN opens. JSN continues automatically after verifying your account. There are no debugging-port or request-header prompts.

The direct command is:

jsn auth login dev12345 --browser
jsn auth login dev12345 --browser --browser-name chromium

Installed Chromium, Chrome, and Edge are detected. Chromium is the first validated launch integration; Firefox is not supported yet. --browser-name accepts chromium, chrome, or edge; without it, interactive login offers installed browsers and noninteractive login selects the first available one.

JSN opens a fresh, temporary login window, so another window's account is not silently reused. Finish signing in within five minutes. JSN verifies access to the current user's sys_user record, saves standard GCK credentials, then closes its login window and removes its temporary browser profile. Press Ctrl+C or close the login window to cancel. Your normal browser windows stay open. An existing profile's username must match the browser account.

When the session expires, log in again:

jsn auth login --profile limited --browser

Interactive auth login on an existing GCK profile launches browser login. Bots must request that explicitly with --browser; JSON/piped commands never open a browser implicitly. Pages without a readable g_ck still need the explicit --gck paste flow. Login is explicit; JSN does not renew browser sessions in the background.

For an already configured local debugging browser, the advanced connection path remains available without launching or closing that browser:

jsn auth login dev12345 --browser --browser-url http://127.0.0.1:9222

That endpoint must be loopback-only. Chrome requires a non-default browser data directory for this connection (Chrome documentation). Keep one logged-in application tab open for the instance; multiple matching tabs are rejected. The debugging connection grants access to that browser profile, so close it when finished.

For CI/CD, set environment variables:

export SERVICENOW_INSTANCE_URL="https://dev12345.service-now.com"
export SERVICENOW_OAUTH_TOKEN="***"
jsn incidents list

For the credential identity, auth-method, diagnostics, migration, and concurrency contract, see AUTH_LIFECYCLE.md.

GraphQL uses ServiceNow's /api/now/graphql endpoint and sends {query, variables} through the authenticated SDK transport. The command preserves GraphQL data and errors; introspection and available namespaces depend on the target instance.

jsn platform stats uses a fixed GET /xmlstats.do request. It never accepts a processor path, query parameters, or request body, and it does not emit raw XML, cookies, credentials, or full node identifiers. Oversized, HTML/login, permission, unsupported, timeout, and malformed responses are reported with bounded collector statuses; missing metrics remain unavailable rather than being reported as zero.

Local data

JSN stores durable local data under ~/.jsn/. Documentation lives in ~/.jsn/docs/, including docs.db, the ServiceNowDocs source checkout, and community markdown. Configuration stays under ~/.config/servicenow/ and credentials use the operating system's credential store, with a file fallback under ~/.config/servicenow/credentials/.

Existing installations migrate documentation from ~/.cache/servicenow-cli/docs/ automatically the first time the docs data is accessed. The old directory is removed only after the destination is verified.

AI Agents

jsn ships with a skill file that tells AI agents how to use it. Installed automatically to ~/.agents/skills/servicenow/SKILL.md.

jsn skill show                  # View the skill
jsn skill install               # Install to Hermes
jsn skill install --target all  # All supported agents

Development

git clone https://github.com/jacebenson/jsn.git
cd jsn
npm --prefix cli ci
npm test
npm run lint

Releases run from the GitHub Actions workflow. Dispatch Release production with patch, minor, or major. The workflow tests and lints the repo, bumps the version, pushes the commit and tag, dispatches the npm publish workflow, and creates the GitHub release.

License

MIT

Auth and setup prompts show Esc to cancel, as does every other prompt. Press Esc to leave the current workflow without accepting the highlighted choice. jsn auth status includes hints for switching profiles, renewing OAuth/browser sessions, and changing profile settings.

Additional command workflows

Use jsn knowledge search "VPN setup" --profile work (alias kb) to search accessible articles, then jsn knowledge show KB0000010 --profile work to read one. Search supports bounded --limit/--offset, knowledge-base sys_ids with --kb, and --language. JSON preserves native HTML; human output uses Markdown. Hints preserve an explicitly selected profile/instance. The Knowledge API plugin (sn_km_api) must be available; access is evaluated by that API, with no fallback to direct table reads. Reads do not request view-count updates. See the Knowledge API reference.

Instance Scan

jsn scan manages checks and suites and runs scans against an explicit target. Use jsn scan --help and each subcommand's --help to discover the options.

jsn scan checks list --profile dev
jsn scan checks create --type table --data-file check.json --profile dev
jsn scan checks activate <check-id> --profile dev
jsn scan suites add-check <suite-id> --check <check-id> --profile dev
jsn scan run --update-set "My change" --suite "My suite" --wait --profile dev
jsn scan run --table sys_script_include --record <record-id> --profile dev
jsn scan results <execution-id> --profile dev

Check types are table, column, linter, and script. Definitions are created inactive unless the payload explicitly sets active: true; activation never starts a scan. Both checks and suites support list/show/create/update/delete and activate/deactivate. Suites also support add-check/remove-check.

Runs require an update set, scope, record plus table, or explicit --full. Instance-wide scans may traverse many tables even when a check's script only examines a few records. Starting and cancelling a scan require confirmation; use --force only after approving that operation. --wait --timeout 120 bounds the wait, not the scan's lifetime. A timed-out wait keeps the execution id and does not cancel or resubmit the scan. Use status, results, or cancel next.

Update-set scans examine current instance records, not the historical XML versions. Inactive records may be skipped. Script-only checks do not participate in record/update-set scans; use an explicitly instance-wide suite run to execute them. Execution success does not mean zero findings or complete test coverage: results report recorded check executions, finding counts, unreadable sources, and truncated lists separately. A result's rerun hint preserves the previous target combination and requires --full again for instance-wide scans.

Every command returns next-step breadcrumbs in human and JSON output, retaining an explicitly selected profile or instance. updatesets show also offers a scan hint. Recommendation/generation of new checks is not part of this command; JSN contains no AI and does not infer missing business requirements.

jsn cmdb search "web" --profile work searches names, FQDNs, IP addresses and serial numbers on cmdb_ci. Use --class cmdb_ci_server for an exact class match (excluding subclasses), and bounded --limit/--offset pagination. Search text is literal; encoded-query operators and query scripts are rejected. Existing cmdb list --query remains available for deliberate encoded queries. Results include show/relationship hints and preserve the selected connection.

Commands for the connected account

Login and OAuth refresh check for the current account's admin role. Profiles without that role show a compact command list focused on tickets, generic records, people/groups, documentation, and connection management. If the role check is unavailable, the profile also uses compact help; this does not assert that the account lacks admin. Existing profiles keep full help until renewed.

This applies to root help, root JSON, discover. Use jsn --all-commands --help or jsn discover --all-commands --json to inspect every registered command. Explicit command paths remain available and ServiceNow ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.

Ordering catalog items

Use jsn catalogitems search "laptop" --profile work, then jsn catalogitems describe <item-sys-id> --profile work to inspect pricing and variable definitions through the native Service Catalog API. Create a JSON file mapping variable names to values, then preview with jsn catalogitems order <item-sys-id> --variables-file variables.json --dry-run --profile work. Omit --dry-run to submit after confirmation. --quantity defaults to one; --requested-for accepts a user sys_id subject to instance delegation rules.

show is the one view of an item — describe and inputs are aliases for it. It reads the item twice and answers once: the Table API gives the definition (sc_cat_item plus item_option_new), and /api/sn_sc/servicecatalog/items/{id} gives what this account can actually request. The catalog API wins when it answers; the definition list keeps the command working when it does not, with variables_source naming which one answered and variables_api_error carrying the reason for the fallback.

Questions come back as {name, label, type, friendly_type, mandatory, instance_supplied} with required_variables and instance_supplied_variables, so a script can build the payload without guessing names or types. Layout entries that draw the form but hold no value — containers, labels, HTML and rich text blocks, breaks and UI macros — are not reported as questions; only their container children are walked. required_variables excludes the instance-supplied ones: "Requested for" (type 31) is mandatory in the API payload, but the instance fills it from the session and --requested-for overrides it. order refuses locally when a required question is missing and an unknown variable name is reported as unknown_variable_names without blocking. The server remains the authority.

What the API returns is what a caller can send: questions withheld by a catalog UI policy are absent, and a policy-applied mandatory flag is not visible here, so the server still decides at submission. Record producers and order guides expose their variables but are not orderable through order.

Orders use order_now, preserving catalog fulfillment rather than inserting an RITM directly. order_now returns the request (REQ); JSN then reads the request's items and reports request_id, request_number and requested_items (sys_id/number). If that follow-up read is denied, the order is still reported as placed with requested_items_readable: false — inspect requests rather than resubmitting. The command handles standard catalog items; record producers and order guides require separate workflows. Server rules validate dynamic variables at submission; a preview does not validate those rules. Preview output lists variable names and required names, not entered values. Previews only read, so they work on a read-only profile; submitting requires a write-enabled profile and no development update set. Confirmation follows the existing profile policy; automation can supply --force only for an approved order. Timeout or incomplete response is an uncertain outcome: inspect requests before retrying. JSN does not automatically submit a second order. create/list/show retain their definition-management behavior.

See the Service Catalog API reference.

Viewing service and HR cases

jsn cases list, jsn cases show <number> and jsn cases search "<text>" read cases through the normal authenticated Table API. Which case table is meant depends on the installed application, so JSN probes the known case tables in order — sn_customerservice_case (Customer Service Management), then sn_hr_core_case (HR Service Delivery) — and uses the first one the profile can read. jsn cases tables reports each candidate without claiming access, and --table <name> names any other case table.

jsn cases list --json
jsn cases list --hr --query "active=true"
jsn cases search "printer" --table sn_customerservice_case
jsn cases show CS0001001

Visibility is not widened by JSN: application roles and ACLs decide which records are returned, and a denied table reports forbidden (HTTP 403) rather than an empty list. An instance without a case application reports which tables were unavailable instead of pretending there are no cases, and naming such a table with --table fails the same way (Reading <table> failed (HTTP 400), exit 2) instead of printing an empty list. To scope a list to the connected account, add a query term — field names differ per application, for example --query "opened_by=javascript:gs.getUserID()". These commands only read; case work that changes state stays in the application UI or jsn records update.

HR cases are a thin addition over this generic path: --hr selects sn_hr_core_case. Employee self-service visibility depends on the HR roles and ACLs of the connected account — an administrator profile does not represent an employee's view. HR case tasks, relations and the employee portal's widgets are not exposed yet.

Domain configuration and browser sessions

jsn domains current reports the selected profile's configured X-Now-Domain header. domains set <name-or-id> and domains set clear configure that header locally. Header effectiveness depends on the instance; clearing it does not reset the actual server session domain.

With saved browser-session (gck) credentials, use these explicit commands:

jsn domains session-current --profile example --json
jsn domains session-list --profile example --search '*Internal' --limit 20 --offset 0 --json
jsn domains session-reset --profile example --json
jsn domains session-list --profile example --json
jsn domains session-set <domain-sys-id> --profile example --json

session-list returns one picker-visible page (items, offset, limit, next_offset). Search matches a name prefix, or a substring with a leading *. Visibility depends on the actual session domain. For cross-branch selection, explicitly reset to global, then list and select a domain from that result. Neither listing nor selecting silently resets the session. session-current reports both configured_domain and session_domain.

Session reset and selection may affect a browser sharing these credentials. Both commands verify the resulting domain with a separate readback. They leave profile configuration unchanged and omit the configured domain header on picker requests. Save the original domain ID from session-current if you intend to restore it afterward. A failed readback can leave the session changed; inspect session-current before retrying. These commands do not call touch-session. Other authentication methods retain the existing profile configuration flow.