servicenow-cli 0.6.3

Fast, safe, human-friendly ServiceNow operations from the terminal
Documentation

servicenow-cli

CI crates.io PyPI License: MIT

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 routine sys_id hunting.
  • 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

Homebrew

brew install rvben/tap/servicenow-cli

Homebrew installs native binaries on macOS and builds from source on Linux.

Other installation methods

Both packages install the servicenow and servicenow-cli binaries:

cargo install servicenow-cli --locked

# or
pipx install servicenow-cli

# or run from PyPI without installing
uvx servicenow-cli --help

From a checkout:

cargo install --path .

Two-minute start

# Detects SSO and opens a browser sign-in window in a throwaway profile; no OAuth app is required.
servicenow init --profile work --instance company

# Managed OAuth remains available when your organization provides a client ID:
servicenow auth login --profile work --instance company --method oauth \
  --client-id YOUR_CLIENT_ID

# On headless Linux/WSL2, the CLI uses a protected file if no keychain is available.
# You can also select file storage directly:
servicenow init --profile work --instance company --insecure-storage

servicenow auth status
servicenow auth status --offline
servicenow doctor
servicenow doctor --offline
servicenow incidents mine
servicenow incidents show INC0010042

# Or stay in the terminal and browse interactively
servicenow tui

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:

servicenow tui
servicenow tui cmdb_ci
servicenow tui change_request --query 'active=true^ORDERBYDESCsys_updated_on'

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
servicenow incidents list --active
servicenow incidents list --query 'priority=1^ORDERBYDESCsys_updated_on'
servicenow incidents mine
servicenow incidents show INC0010042

# Create and update
servicenow incidents create \
  --short-description "VPN unavailable" \
  --description "Unable to connect since 08:30" \
  --impact 2 --urgency 2

servicenow incidents update INC0010042 --state 2

# Focused daily actions
servicenow incidents note INC0010042 "Investigating the gateway"
servicenow incidents assign INC0010042 --to ada@example.com --group "Network"
servicenow incidents resolve INC0010042 \
  --code "Solved (Permanently)" \
  --notes "Corrected the VPN gateway configuration"
servicenow incidents open INC0010042
servicenow incidents watch INC0010042

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:

servicenow incidents edit INC0010042

# Review a non-interactive plan without writing, even on a read-only profile.
servicenow incidents edit INC0010042 --file incident.yaml --dry-run
servicenow incidents note INC0010042 --file note.md --dry-run
servicenow incidents assign INC0010042 --to @me --dry-run
servicenow incidents resolve INC0010042 \
  --code "Solved (Work Around)" --notes-file resolution.md --dry-run

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
servicenow attachments list incident INC0010042

# Stream the upload, infer text/plain, and keep status output off stdout
servicenow attachments upload incident INC0010042 ./diagnostic.txt

# Preview writes even when the active profile is read-only
servicenow attachments upload incident INC0010042 ./diagnostic.txt --dry-run

# Download atomically; existing files are never replaced accidentally
servicenow attachments download 0123456789abcdef0123456789abcdef ./downloads/
servicenow attachments download 0123456789abcdef0123456789abcdef - > diagnostic.txt

# Inspect the exact deletion before permanently removing the attachment
servicenow attachments delete 0123456789abcdef0123456789abcdef --dry-run
servicenow attachments delete 0123456789abcdef0123456789abcdef --yes

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.

Service Catalog requests

Order catalog items through the Service Catalog API, the same path the portal uses, so approvals, flows, and fulfillment tasks run as usual:

# Find an item and see the variables it takes
servicenow catalog search "aws account"
servicenow catalog show "AWS account request"

# Validate the order without submitting anything
servicenow catalog order "AWS account request" \
  --var division=IT --var environment=Dev \
  --var describe_briefly_the_purpose_of_this_account="Sandbox" --dry-run

# Submit it; variables can also come from a JSON or YAML file (or - for stdin)
servicenow catalog order "AWS account request" --vars-file request.yaml --yes

# Track what you ordered and read back the submitted values
servicenow catalog requests mine --open
servicenow catalog requests vars RITM0010001

ServiceNow accepts unknown variable names, invalid choices, and wrongly formatted dates without complaint and then drops or stores them silently. The CLI checks every variable against the item before ordering, so a typo or an unlisted choice fails with the valid options instead of producing a broken request. Item defaults are checked the same way. Reference variables accept a sys_id, and user or group variables also accept a name or email. order requires the exact item name or sys_id.

Dates are sent as yyyy-MM-dd and times as HH:mm:ss. The instance reads them in your user's formats, so an order with date variables is refused when your formats differ. It is also refused when your formats cannot be read, unless you pass --allow-unverified-formats. catalog requests vars --json prints an object you can pass back to --vars-file, without sensitive or read-only variables. It keeps empty values for variables that have a default, so a reorder does not bring back a default that was cleared.

catalog order sends one request and never retries it: if a response is lost, check catalog requests mine before ordering again.

An order succeeds only when the instance creates a request. Some instances answer an order by putting the item in a cart instead, for example when checkout needs a separate step. Then catalog order exits 8 (kind: not_ordered) and names the cart in error.cart.sys_id. The instance may also put a copy of the item in your cart. Do not order again, because every attempt adds another cart item. Finish or undo it with the cart commands instead:

# See what your cart holds, then order all of it or remove what you do not want
servicenow catalog cart show
servicenow catalog cart submit
servicenow catalog cart remove <cart_item_id>
servicenow catalog cart clear

# Or order through the cart in one step, on an instance that needs checkout
servicenow catalog order "AWS account request" --vars-file request.yaml --checkout --yes

catalog order --checkout adds the item to your cart and submits it, which works whether or not the instance has a separate checkout step. It submits the whole cart, so it refuses to start (exit 7, kind: conflict) while your cart holds anything. Empty the cart first, or order it with catalog cart submit. It cannot order for someone else, because the instance ignores --requested-for for cart items, so the two flags are refused together. When the submission is refused, it exits 8 and leaves the item in your cart rather than removing it; if the item has left the cart by then (the cart is shared with the portal), it says the item may have been ordered instead. When the outcome is unknown (a server error or a lost response), it says the order may have been placed: check catalog requests mine before submitting again. That is exit 1 (kind: unexpected_error), as is a submission the instance answers with a cart instead of a request; exit 8 always means nothing was ordered. --checkout --dry-run reads your cart (creating an empty one if you have none), refuses with exit 7 while it holds anything, and adds "checkout": true to the plan.

cart submit orders every item in the cart, including any added in the portal, and shows them before asking. cart submit and cart clear read the cart again just before acting and refuse (exit 7) if it changed since it was shown, so nothing added in the portal meanwhile is ordered or removed unseen. The cart does not show variable values, so when an item in it has a sensitive variable or a multi-row variable set (or cannot be checked), cart submit withholds the instance's error message rather than risk quoting one. cart remove and cart clear ask before removing anything. Reading the cart creates an empty one when you have none, as the portal does. The cart commands honor read-only profiles. When the instance flags an item as not orderable through the API, catalog show notes it and catalog order warns before ordering.

Items that need the portal are refused with a link to it: record producers, order guides, items with a mandatory attachment, and items with a mandatory multi-row variable set. The CLI cannot fill multi-row variable sets: an optional one is left empty, as the portal submits it when no row is added, and --dry-run lists it under warnings. UI policies, client scripts and custom widgets do not run outside the browser; catalog show and catalog order say when an item has them. Values of masked and secret-looking variables are never echoed, and they are refused with --var, which lands in shell history: pass them through --vars-file. --vars-file - reads standard input, which then cannot answer the confirmation prompt, so add --yes (after a --dry-run to check the plan). When an order with such a value fails, the instance's error message is shown with the value replaced. An error page, or a message with escaped, HTML-encoded or URL-encoded text that could quote the value in another form, is withheld, leaving the HTTP status. Orders honor read-only profiles, and --dry-run works even in read-only mode.

To create requests, always use catalog order. Creating sc_req_item records directly with tables create skips the catalog engine, so no variables, approvals, or fulfillment flows are attached.

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:

servicenow schema incident --refresh
servicenow choices incident state
servicenow resolve user ada@example.com
servicenow resolve group "Network"

# Inspect the full offline contract, or one token-efficient command
servicenow schema
servicenow schema --command 'incidents list'

Cached metadata contains no credentials or record data.

Every ServiceNow table

Focused commands never take away generic access:

servicenow tables list cmdb_ci \
  --query 'operational_status=1' \
  --fields sys_id,name,sys_class_name --limit 100

servicenow tables get cmdb_ci 0123456789abcdef0123456789abcdef
servicenow tables create u_example --data '{"name":"Demo","active":true}'
servicenow tables update u_example 0123456789abcdef0123456789abcdef \
  --field active=false
servicenow tables delete u_example 0123456789abcdef0123456789abcdef --yes

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:

servicenow incidents list --output json
servicenow incidents list --output jsonl
servicenow incidents list --output yaml
servicenow incidents list --output csv
servicenow incidents list --output table

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:

servicenow auth login --profile work --method browser --verbose

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:

{"error":{"kind":"not_found","message":"not found: ...","remediation":null}}

An error with kind: not_ordered also carries "cart":{"sys_id":"..."}.

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 (kind: auth) or permission (kind: permission) failure
4 Record not found
5 Other ServiceNow API error
6 Rate limited
7 Conflict or ambiguous match
8 Not ordered: the item was left in a cart and no request was created (kind: not_ordered, with error.cart.sys_id)

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:

servicenow schema | jq '.commands[].name'
servicenow schema --command 'attachments delete'
servicenow completions zsh > _servicenow

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
servicenow profile list
servicenow profile use production
servicenow profile remove old --yes
servicenow auth status
servicenow auth status --offline
servicenow auth logout
servicenow config show
servicenow config path

Development and release trust

make check
make test-e2e # requires an ignored .env.e2e file and a PDI

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.