ServiceNow Python CLI

Run ServiceNow Background Scripts from your terminal — fast, reliable, and cross‑platform. The CLI also handles login, elevation, multi‑instance management, and secure credential storage with persistent sessions.

At a Glance

• Run Background Scripts from file or stdin, with parsed output
• Login and persist sessions (cookies saved per instance)
• Elevate to security_admin when needed
• Manage multiple instances: add, list, use (set default), remove, info
• Secure credentials via OS keyring (fallback to config file)
• Works on macOS, Linux, and Windows — no GNU/Bash dependencies

Quickstart

# Install locally
pip install -e .

# Add your instance and set it as default (interactive for credentials)
snow add --default dev1234.service-now.com

# Login and create a session
snow login

# Run a background script (core feature)
echo "gs.print('Hello');" | snow run
# or from file
snow run example.js

# Elevate if your task requires security_admin
snow elevate

Warning

It would, in the most measured opinion of those entrusted with the uninterrupted prosecution of business-as-usual, be singularly ill-advised to employ this instrument upon any environment denominated as “production”, the consequences of which—while perfectly predictable—would be lamentably time‑consuming to elucidate and even more so to remediate. (Plainly: do not run this on production.)

Next Generation

This project is the next-generation rewrite of snow-run:

• Repository (this project): https://github.com/chovanecm/snow-run-python
• Original Bash version: https://github.com/chovanecm/snow-run
• The original was Bash-based and ran into cross-platform compatibility issues across systems (e.g., GNU vs. BSD tools, Windows shells).
• This Python implementation focuses on consistent behavior across macOS, Linux, and Windows, with easier maintenance and clearer debugging.

Features

• Background Scripts (core): Run from file or stdin, parsed output, raw HTML saved for troubleshooting
• Login + elevation: Authenticate and elevate to security_admin when required
• Persistent sessions: Cookies stored per instance for reuse
• Multi-instance management: add/list/use/remove, with a default instance
• Secure credentials: OS keyring when available, config fallback
• Cross-platform: macOS, Linux, Windows; no GNU/Bash dependencies
• Better debugging: Clear errors; verbose mode planned

Installation

Choose one of the following:

• Install via pipx (recommended for CLIs)

  pipx install git+https://github.com/chovanecm/snow-run-python@main
  # upgrade later
  pipx upgrade --spec git+https://github.com/chovanecm/snow-run-python@main snow

• Install via pip (user install)

  python3 -m pip install --user git+https://github.com/chovanecm/snow-run-python@main

• Pin to a tag or commit

  pipx install "git+https://github.com/chovanecm/snow-run-python@<tag_or_commit>"

• Try without installing

  pipx run --spec git+https://github.com/chovanecm/snow-run-python@main snow --help

• Development install from a local clone

  git clone https://github.com/chovanecm/snow-run-python.git
  cd snow-run-python
  pip install -e .

Configuration

Use snow add to store credentials securely (OS keyring when available) and set a default instance. You can always override with --instance for one-off commands. Configuration is stored in ~/.snow-run/config.json with file permissions set to 600 (owner read/write only). Passwords are stored in the OS keyring when available; otherwise they fall back to the config file.

Commands

• snow add [--default] [INSTANCE] — Add an instance (interactive credentials)
• snow list — List configured instances
• snow use INSTANCE — Set the default instance
• snow remove INSTANCE — Remove an instance
• snow info — Show current configuration and paths
• snow login — Login and persist session cookies
• snow elevate — Elevate to security_admin
• snow run [SCRIPT_FILE|-] — Run a Background Script (file or stdin)

Managing Multiple Instances

# Interactive prompt
snow add

# Specify instance directly
snow add dev1234.service-now.com

# Set as default
snow add --default dev5678.service-now.com

# List configured instances
snow list

# Switch default instance
snow use dev5678.service-now.com

# Remove an instance
snow remove dev1234.service-now.com

# Show info
snow info

Working with Instances

# Login to default instance
snow login

# Login to specific instance (one-off)
snow --instance dev5678.service-now.com login
# or
snow -i dev5678.service-now.com login

# Run scripts
snow run script.js
echo "gs.print('Hello');" | snow run

# Run on a specific instance
snow -i dev5678.service-now.com run script.js

# Elevate privileges
snow elevate
snow -i dev5678.service-now.com elevate

Troubleshooting & Debugging

• Last raw output (HTML) after running scripts: ~/.snow-run/tmp/{instance}/last_run_output.txt
• Verbose HTTP logging (--debug) is planned.
• On errors, the CLI prints clear messages and relevant HTTP status codes.

Advanced

Environment variables (legacy override; prefer snow add):

export snow_instance=dev1234.service-now.com
export snow_user=admin
export snow_pwd=your-password

# Example using env vars
snow login

Advantages over Bash version

1. Platform-independent: No GNU grep/sed dependencies
2. Better error handling: Python exceptions vs shell error codes
3. Easier to debug: Can add logging, breakpoints, unit tests
4. Type hints: Better IDE support and code documentation
5. Extensible: Easy to add new commands and features

Development

# Install in development mode
pip install -e .

# Run tests (coming soon)
pytest

# Add logging for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

Migration from Bash

The Python version is designed as a drop-in replacement:

• Same command names: snow login, snow elevate, snow run
• Same environment variables: snow_instance, snow_user, snow_pwd
• Same cookie storage location: ~/.snow-run/tmp/{instance}/cookies.txt
• Compatible with existing scripts

TODO

• Add remaining commands (eval, inspect, table, record, etc.)
• Add --debug flag for verbose HTTP logging
• Add unit tests
• Improve output parsing for edge cases
• Add retry logic for network errors
• Support for custom SSL certificates