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 │ short_description │ state │
╞════════════╪══════════╪═════════════════════════╪═════════════╡
│ INC0010042 │ 2 │ VPN unavailable │ In Progress │
└────────────┴──────────┴─────────────────────────┴─────────────┘
Why it feels different
- Workflow-first commands for incidents, with every table still available.
- Human inputs such as incident numbers, user names, emails, group names, and
@me; no routinesys_idhunting. - Secure interactive login with Basic, bearer, or OAuth + PKCE authentication.
- Credentials in the operating-system keychain, not plaintext profile files.
- 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 binary:
# or
From a checkout:
Two-minute start
# Prompts securely; the password is stored in your OS keychain.
For OAuth, bearer-token, CI, migration, and production-profile guidance, see Authentication and profiles.
Incident workflows
# Find work
# Create and update
# Focused daily actions
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.
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:
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:
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.
Machine-readable errors use a stable envelope:
| 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 offline command schema and generated completions make integration easy:
|
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_TOKEN |
Bearer/OAuth access token |
SERVICENOW_AUTH_TYPE |
basic, bearer, or oauth |
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 an isolated incident, verifies CRUD/query/display-value behavior, and cleans it up.
CI runs formatting, linting, tests on Linux/macOS/Windows, and a RustSec audit. Tagged releases produce native archives, Cargo/PyPI packages, SHA-256 checksums, a CycloneDX SBOM, and GitHub artifact attestations. 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.