servicenow-cli
Fast, safe, human-friendly ServiceNow operations from the terminal.
servicenow is an unofficial open-source CLI for people, scripts, and agents.
It pairs focused daily workflows with generic Table API access, works through
supported instance APIs, and requires no instance-side CLI plugin.
$ servicenow incidents mine
┌────────────┬──────────────┬─────────────────┬─────────────┬──────────┬─────────────────────┐
│ NUMBER │ PRIORITY │ DESCRIPTION │ STATE │ ASSIGNEE │ UPDATED │
╞════════════╪══════════════╪═════════════════╪═════════════╪══════════╪═════════════════════╡
│ INC0010042 │ 2 - High │ VPN unavailable │ In Progress │ Ada │ 2026-08-22 10:30:00 │
└────────────┴──────────────┴─────────────────┴─────────────┴──────────┴─────────────────────┘
Why it feels different
- Workflow-first commands for incidents and attachments, with every table still available.
- Human inputs such as incident numbers, user names, emails, group names, and
@me; no routinesys_idhunting. - Zero-admin browser sign-in for SSO instances, with managed OAuth available when administrators provide it.
- Credentials in the operating-system keychain, with a permission-locked file fallback for environments such as WSL2 that do not provide a credential service.
- Beautiful responsive tables for humans; deterministic JSON, JSONL, YAML, and CSV for automation.
- Read-only profiles, semantic editor patches, dry runs, and explicit dangerous operation confirmation.
- Stable error kinds and exit codes for scripts and agents.
Install
Both packages install the servicenow and servicenow-cli binaries:
# or
# or run from PyPI without installing
From a checkout:
Two-minute start
# Detects SSO and opens a browser sign-in window in a throwaway profile; no OAuth app is required.
# Managed OAuth remains available when your organization provides a client ID:
# On headless Linux/WSL2, choose the permission-locked file fallback directly:
# Or stay in the terminal and browse interactively
For browser SSO, OAuth, bearer-token, CI, migration, and production-profile guidance, see Authentication and profiles.
Interactive terminal browser
Launch the Ratatui incident workspace, or start directly on any standard or custom table:
The default incident view shows active incidents assigned to the signed-in user
or one of their assignment groups, ordered by most recently updated. Pass
--query to open a different view, or clear the query with / inside the TUI
to browse all incidents.
The ledger adapts to the terminal width: wide terminals keep the selected
record's field sheet beside the index, while compact terminals open that sheet
on demand. Use ↑/↓ or j/k to move, enter to inspect, / to apply an
encoded query, s to search display values on the currently loaded page, t
to change tables, n/p to page, a for incident actions, and ? for the
complete keyboard map. Local search stays active across page loads and query
changes; submit a blank search to clear it. Press o to hand the selected
record off to the ServiceNow web interface.
You can launch the TUI before setup is complete. If the active profile is not
connected—or if its session has expired—the ledger presents secure sign-in as
the primary recovery. Press enter or a, complete the guided authentication
outside the alternate screen, and the TUI returns directly to the record list.
Press q or esc instead to return to the shell without changing anything.
Incident inspection unfolds into four read-only views: Overview shows every
readable field, Activity shows recent comments and work notes, Attachments
lists file metadata, and SLAs shows task-SLA progress and breach state. Move
between them with tab/shift-tab or jump directly with 1–4; related views
load only when opened, return up to 100 recent entries, and can be retried
independently with r. Access remains subject to the active ServiceNow user's
table and field ACLs.
On an incident, press a to add a work note, change the assignee or assignment
group, or resolve the incident. The TUI validates the input, resolves user and
group names, maps configured resolution choices, and shows the exact update on
a separate review screen. Nothing is written until you confirm with enter;
the update is sent as one PATCH request, failed writes preserve the review, and
the ledger refreshes after success.
Incident writes honor the active profile's write policy. Read-only profiles are
clearly labeled and block every action; standard and custom tables remain
browse-only. The TUI reuses the active credentials, keeps secrets out of the
rendered state, honors --no-color, and refuses to start when stdin or stdout
is not an interactive terminal. Fields whose names identify passwords, secrets,
tokens, cookies, credentials, authorization values, or private/API keys are
always shown as [REDACTED].
Incident workflows
# Find work
# Create and update
# Focused daily actions
Resolution is a guarded, atomic workflow: the CLI maps configured state and
resolution-code labels to their raw values, requires non-empty resolution notes,
and refuses incidents that are already resolved, closed, or canceled. Use
--notes-file PATH for longer notes, repeated --field name=value arguments for
instance-specific mandatory fields, --state for a customized resolved state,
or --refresh after instance choices change.
Edit safely in $EDITOR. The document contains only curated editable fields;
the CLI shows a diff, confirms, and PATCHes only values that changed:
# Review a non-interactive plan without writing, even on a read-only profile.
Use repeated --field name=value arguments for instance-specific fields.
Values that parse as JSON retain their JSON type.
Attachment workflows
Attachment commands work with any table. Records can be identified by number,
sys_id, or a form URL copied from the configured ServiceNow instance:
# Discover files without looking up the incident sys_id
# Stream the upload, infer text/plain, and keep status output off stdout
# Preview writes even when the active profile is read-only
# Download atomically; existing files are never replaced accidentally
# Inspect the exact deletion before permanently removing the attachment
Uploads and downloads are streamed rather than loaded entirely into memory.
Server-provided file names are reduced to a safe local basename, downloads use
a temporary file plus atomic persistence, and replacing a local file requires
--force. Upload and delete operations honor profile-level read-only mode.
Discover your instance
ServiceNow tables, choices, and custom fields vary by instance. The CLI can cache its dictionary locally and resolve human references before writes:
# Inspect the full offline contract, or one token-efficient command
Cached metadata contains no credentials or record data.
Every ServiceNow table
Focused commands never take away generic access:
Only records and fields allowed by the authenticated user's ServiceNow ACLs are available.
Output and automation contract
Interactive stdout uses a table. Piped stdout automatically becomes JSON. An explicit format always wins:
Incident tables prefer ServiceNow display values and curated columns. Machine
output intentionally keeps raw values by default for stable automation. Use
--display-value false|true|all to override either behavior explicitly.
Data goes to stdout; status messages and errors go to stderr. --quiet
suppresses status messages. --no-color and the NO_COLOR environment
variable disable ANSI color. During browser authentication, --verbose streams
timestamped, secret-free handoff milestones to stderr:
Verbose browser diagnostics report only stage transitions and HTTP status
codes. URLs, cookies, tokens, usernames, browser paths, and page content are
never logged. SERVICENOW_VERBOSE=true enables the same behavior.
Machine-readable errors use a stable envelope:
Command-line parsing errors (an unknown flag, a missing required argument, an
unrecognized subcommand) use the same envelope with kind: invalid_input and
exit code 2 whenever the output mode is machine-readable, including auto-JSON
mode when stdout is not a terminal. --help and --version always print
their normal text to stdout with exit code 0.
| Exit | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected or transport error |
| 2 | Invalid input or configuration |
| 3 | Authentication or authorization failure |
| 4 | Record not found |
| 5 | Other ServiceNow API error |
| 6 | Rate limited |
| 7 | Conflict or ambiguous match |
The versioned offline command schema describes argument types, defaults, enums, side effects, confirmation and dry-run behavior, output envelopes, and exit codes. Query a single command to keep agent context small:
|
Configuration precedence
Command options override environment variables, which override the active profile. Environment variables are useful for ephemeral automation:
| Variable | Purpose |
|---|---|
SERVICENOW_INSTANCE |
Instance name, hostname, or full base URL |
SERVICENOW_USERNAME |
Basic-auth username |
SERVICENOW_PASSWORD |
Basic-auth password |
SERVICENOW_COOKIE |
Ephemeral ServiceNow browser-session cookie |
SERVICENOW_USER_TOKEN |
Matching browser anti-CSRF token for write requests |
SERVICENOW_TOKEN |
Bearer/OAuth access token |
SERVICENOW_AUTH_TYPE |
browser, basic, bearer, or oauth |
SERVICENOW_BROWSER |
chrome, edge, chromium, firefox, a platform executable path, or a windows-* WSL override |
SERVICENOW_PROFILE |
Named profile |
SERVICENOW_READ_ONLY |
Block all actual mutations when true |
SERVICENOW_CACHE_DIR |
Override the metadata cache root |
Development and release trust
The default suite uses mock servers. The ignored PDI lifecycle suite creates isolated records, verifies incident and attachment lifecycles, and cleans up every record and file it creates.
CI runs formatting, linting, tests on Linux/macOS/Windows, a RustSec audit, and an MSRV build. Tagged releases produce native archives, Cargo/PyPI packages, SHA-256 checksums, a CycloneDX SBOM, and GitHub artifact attestations, then install and execute both public packages as a final smoke test. See SECURITY.md, SUPPORT.md, and the release runbook.
Status
This project is unofficial and is not affiliated with or supported by ServiceNow. ServiceNow is a trademark of ServiceNow, Inc.
Licensed under the MIT License.
Releasing
Vership owns versioning, changelog generation, release commits, and tags. See the release runbook for the verified workflow and recovery policy.