The instance command manages the local registry of ServiceNow instances. Instead of rewriting .env every time you switch targets, you register each instance once and then select it with --target on most commands. Each instance can carry named profiles for separating API vs UI access.
instance
Manage the instance registry — add, list, test, extract, and probe health.
| Subcommand | Purpose |
|---|---|
| list | List configured instances (`--json`, `--tag` filter) |
| show <name> | Show instance details (secrets redacted) |
| add <name> | Register a new instance — supports basic/oauth_cc/oauth_ropc/api_key auth |
| add-profile <instance> <profile> | Add a named credential profile (API-only, UI-only, or both) |
| profiles <instance> | List profiles for an instance |
| remove <name> | Remove an instance |
| use <name> | Set the default instance |
| test <name> | Probe connectivity and authentication (`--profile`) |
| extract <name> | Pull platform-definition tables (dictionary, choices, plugins…) to disk |
| health | Pre-flight probe — counts recent errors, slow transactions, active jobs |
sn instance health [--json] [--since <hours>] [--slow [N]] [--triggers [N]] [--patterns [N]] [--by-source [N]] [--stats] Pre-flight probe that grades instance state against fixed thresholds. Exits 0 (OK), 1 (WARNING), or 2 (CRITICAL) so it composes as a shell gate.
Flags
| Flag | Default | Description |
|---|---|---|
| --json | — | Emit a machine-readable JSON result (counts, reasons, thresholds, detail blocks). |
| --since <hours> | 1 | Lookback window for error and slow-transaction counts. |
| --slow [N] | 5 | Top N slow transactions (URL, response time, user). |
| --triggers [N] | 5 | Top N active `sys_trigger` jobs (age, next_action, script preview). |
| --patterns [N] | 5 | Top N normalized error patterns across recent syslog rows. |
| --by-source [N] | 5 | Top N error sources with their most frequent messages. |
| --stats | — | Include build tag and node ID in the report. |
Examples
sn instance health --since 2[OK] Instance healthy — no errors or slow-txn spikes in last 2h
errors (level>=2) : 0
slow txns (>=1000ms) : 2
active sys_trigger jobs : 37
sn instance health --slow 3 --stats[WARNING] Instance shows degradation in last 1h
errors (level>=2) : 3
slow txns (>=1000ms) : 18
active sys_trigger jobs : 42
Reasons:
- 3 error(s) in last 1h
- 18 slow transactions (>=1000ms) in last 1h (threshold: >10)
Top 3 slow transactions:
3842ms /api/now/table/incident [admin]
2108ms /now/nav/ui/home [admin]
1894ms /xmlstats.do [guest]
Instance stats (/stats.do):
build: glide-xanadu-07-02-2024__patch1-hotfix3
node: app146_us_east_1
sn instance health --json{ "status": "OK", "counts": { "errors": 0, "slowQueries": 2, "activeJobs": 37 }, "thresholds": {...}, "details": null }
sn instance extract <name> --outdir <path> [--stamp-config <path>] [--tables t1:fmt,t2:fmt,...] [--target <name>] [--profile <name>] Pull platform-definition tables (dictionary, choices, script includes, plugins, webservices) from an instance to disk. Useful for capturing pre/post-upgrade state or seeding a compat-check corpus.
Arguments
| Name | Required | Description |
|---|---|---|
| name | Yes | Free-form label for the extract (e.g. australia, yokohama-post-plugin-X, 2026-04-17-prod). |
Flags
| Flag | Default | Description |
|---|---|---|
| --outdir <path> | — | Output directory (created if missing). |
| --stamp-config <path> | — | Update `version` in a pre-existing JSON config to `glide.buildtag.last`. Preserves indent + key order. |
| --tables <list> | — | Override the default table set. Format: `table:fmt,table:fmt,…` where fmt ∈ `xml_unload|csv|json`. |
| --no-progress | — | Suppress per-partition progress output (on by default). |
| --target <name> | — | Select instance from registry. |
| --profile <name> | — | Credential profile under `--target`. |
Examples
sn instance extract australia \
--target dev274082 \
--outdir ./releases/australia/exports \
--stamp-config ./releases/australia/config.json▶ Extract "australia" → ./releases/australia/exports (8 table(s))
✓ sys_dictionary [csv] → sys_dictionary.csv (4.2s)
✓ sys_dictionary [xml_unload] → sys_dictionary.xml (11.8s)
✓ sys_choice [xml_unload] → sys_choice.xml (3.1s)
✓ sys_ws_definition [xml_unload] → sys_ws_definition.xml (0.4s)
✓ sys_ws_operation [xml_unload] → sys_ws_operation.xml (0.7s)
✓ sys_script_include [json] → sys_script_include.json (2.0s)
✓ sys_documentation [csv] → sys_documentation.csv (2.5s)
✓ v_plugin [json] → v_plugin.json (0.8s)
✓ stamped ./releases/australia/config.json version = glide-australia-11-14-2025__patch1
✓ Extract complete — 8 table(s)
instance add supports four auth types: basic (--user --pass), oauth_cc (--client-id --client-secret), oauth_ropc (--client-id --user --pass), and api_key (--api-key [--api-key-header]). Profiles specify --access api|ui|both so API-only tokens don't get picked up by sn ui-run.
Bootstrapping a dev + prod pair
sn instance add dev --url https://dev274082.service-now.com --user admin --pass '***' --tag dev --default
sn instance add prod --url https://acme.service-now.com --auth oauth_cc \
--client-id '***' --client-secret '***' --tag prod
sn instance add-profile prod ui --user ops.bot --pass '***' --access ui
sn instance test prod --profile ui
sn instance health --since 4