@syndicalt/snow-cli 1.1.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # snow-cli
 
-A portable CLI for ServiceNow. Query tables, inspect schemas, edit script fields, and generate complete applications using AI — all from your terminal.
+A portable CLI for ServiceNow. Query tables, inspect schemas, edit and search script fields, bulk-update records, manage users and groups, handle attachments, promote update sets across environments, and generate complete applications using AI — all from your terminal.
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -10,6 +10,11 @@ A portable CLI for ServiceNow. Query tables, inspect schemas, edit script fields
   - [snow schema](#snow-schema)
     - [snow schema map](#snow-schema-map)
   - [snow script](#snow-script)
+  - [snow bulk](#snow-bulk)
+  - [snow user](#snow-user)
+  - [snow attachment](#snow-attachment)
+  - [snow updateset](#snow-updateset)
+  - [snow status](#snow-status)
   - [snow provider](#snow-provider)
   - [snow ai](#snow-ai)
 - [Configuration File](#configuration-file)
@@ -46,16 +51,32 @@ snow instance add
 # 2. Query a table
 snow table get incident -q "active=true" -l 10 -f "number,short_description,state,assigned_to"
 
-# 3. Configure an AI provider
-snow provider set openai
+# 3. Bulk-update records matching a query
+snow bulk update incident -q "active=true^priority=1" --set assigned_to=admin --dry-run
 
-# 4. Generate a simple feature
-snow ai build "Create a script include that auto-routes incidents by category and urgency"
+# 4. Pull a script field, edit it locally, push it back
+snow script pull sys_script_include <sys_id> script
+
+# 5. Search for a pattern across all scripts in an app scope
+snow script search x_myapp --contains "GlideRecord('old_table')"
+
+# 6. Manage update sets — list, export, and promote to another instance
+snow updateset list
+snow updateset export "Sprint 42" --out ./updatesets
+snow updateset apply ./sprint-42.xml --target prod
+
+# 7. Add a user to a group or assign a role
+snow user add-to-group john.doe "Network Support"
+snow user assign-role john.doe itil
 
-# 5. Generate a full scoped application (AI decides scope automatically)
-snow ai build "Build a hardware asset request application with a custom table, approval script include, and assignment business rule"
+# 8. Download all attachments from a record
+snow attachment pull incident <sys_id> --all --out ./downloads
 
-# 6. Start an interactive session to build iteratively
+# 9. Configure an AI provider and generate a feature
+snow provider set openai
+snow ai build "Create a script include that auto-routes incidents by category and urgency"
+
+# 10. Start an interactive session to build iteratively
 snow ai chat
 ```
 
@@ -331,6 +352,351 @@ snow script list
 
 Cached scripts are stored in `~/.snow/scripts/`.
 
+#### `snow script search`
+
+Search for a text pattern across script fields in a given app scope. Searches Script Includes, Business Rules, Client Scripts, UI Actions, UI Pages (HTML, client, and server scripts), and Scheduled Jobs.
+
+```bash
+# Find all scripts containing a string
+snow script search x_myapp --contains "GlideRecord('incident')"
+
+# Search only specific tables
+snow script search x_myapp --contains "oldMethod" --tables sys_script_include,sys_script
+
+# Use a JavaScript regex
+snow script search x_myapp --contains "gs\.(log|warn)" --regex
+```
+
+Results show the record name, sys_id, and matching lines with line numbers (up to 5 preview lines per record).
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `-c, --contains <pattern>` | Text or regex pattern to search for (required) |
+| `-t, --tables <tables>` | Comma-separated table list (default: all 8 script tables) |
+| `--regex` | Treat `--contains` as a JavaScript regex |
+| `-l, --limit <n>` | Max records per table (default: `500`) |
+
+#### `snow script replace`
+
+Find and replace text across script fields in an app scope. Supports dry-run preview before committing changes.
+
+```bash
+# Preview what would change
+snow script replace x_myapp --find "gs.log" --replace "gs.info" --dry-run
+
+# Replace with confirmation prompt
+snow script replace x_myapp --find "gs.log" --replace "gs.info"
+
+# Replace with regex and skip confirmation
+snow script replace x_myapp --find "GlideRecord\('old_table'\)" --replace "GlideRecord('new_table')" --regex --yes
+
+# Target only specific tables
+snow script replace x_myapp --find "deprecated.util" --replace "NewUtils" --tables sys_script_include
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `-f, --find <pattern>` | Text to find (required) |
+| `-r, --replace <text>` | Replacement text (required) |
+| `-t, --tables <tables>` | Comma-separated table list (default: all 8 script tables) |
+| `--regex` | Treat `--find` as a JavaScript regex |
+| `-l, --limit <n>` | Max records per table (default: `500`) |
+| `--dry-run` | Show matches without writing any changes |
+| `--yes` | Skip confirmation prompt |
+
+---
+
+### `snow bulk`
+
+Bulk update multiple records in one command. Fetches matching records, shows a preview, asks for confirmation, then patches each record.
+
+```bash
+# Preview affected records without making changes
+snow bulk update incident -q "active=true^priority=1" --set state=2 --dry-run
+
+# Update with confirmation prompt
+snow bulk update incident -q "active=true^priority=1" --set state=2 --set assigned_to=admin
+
+# Skip confirmation (useful in scripts)
+snow bulk update sys_user -q "department=IT^active=true" --set location=NYC --yes
+
+# Cap the number of records updated
+snow bulk update incident -q "active=true" --set impact=2 --limit 50
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `-q, --query <query>` | ServiceNow encoded query to select records (required) |
+| `-s, --set <field=value>` | Field assignment — repeat for multiple fields (required) |
+| `-l, --limit <n>` | Max records to update (default: `200`) |
+| `--dry-run` | Show preview without making changes |
+| `--yes` | Skip confirmation prompt |
+
+The preview table shows the sys_id, display name, and new values for every record that will be updated.
+
+---
+
+### `snow user`
+
+Manage group membership and role assignments for ServiceNow users. Users can be specified by `user_name`, email, display name, or sys_id.
+
+```bash
+# Add a user to a group
+snow user add-to-group john.doe "Network Support"
+snow user add-to-group john.doe@example.com "IT Operations" --yes
+
+# Remove a user from a group
+snow user remove-from-group john.doe "Network Support"
+
+# Assign a role to a user
+snow user assign-role john.doe itil
+
+# Remove a role from a user
+snow user remove-role john.doe itil --yes
+```
+
+Each command resolves the user and target, checks for existing membership/role to prevent duplicates, then prompts for confirmation before making any change.
+
+| Command | Description |
+|---|---|
+| `snow user add-to-group <user> <group>` | Add user to a `sys_user_group` |
+| `snow user remove-from-group <user> <group>` | Remove user from a `sys_user_group` |
+| `snow user assign-role <user> <role>` | Grant a `sys_user_role` to a user |
+| `snow user remove-role <user> <role>` | Revoke a `sys_user_role` from a user |
+
+All subcommands accept `--yes` to skip the confirmation prompt.
+
+---
+
+### `snow attachment`
+
+Download and upload file attachments on ServiceNow records via the Attachment API. Also available as `snow att`.
+
+```bash
+# List attachments on a record
+snow attachment list incident <sys_id>
+snow att ls incident <sys_id>
+
+# Download all attachments to a directory
+snow attachment pull incident <sys_id> --all --out ./downloads
+
+# Download a specific attachment by file name
+snow attachment pull incident <sys_id> --name report.pdf
+
+# Upload a file as an attachment
+snow attachment push incident <sys_id> ./fix-notes.pdf
+
+# Override the auto-detected Content-Type
+snow attachment push incident <sys_id> ./data.bin --type application/octet-stream
+```
+
+**`snow attachment pull` options:**
+
+| Flag | Description |
+|---|---|
+| `-a, --all` | Download all attachments on the record |
+| `-n, --name <file_name>` | Download a specific attachment by its file name |
+| `-o, --out <dir>` | Output directory (default: current directory) |
+
+**`snow attachment push` options:**
+
+| Flag | Description |
+|---|---|
+| `-t, --type <content-type>` | Override the Content-Type header (auto-detected from extension by default) |
+
+Content-Type is inferred from the file extension for common formats (PDF, PNG, JPG, CSV, XML, JSON, ZIP, DOCX, XLSX, etc.). Defaults to `application/octet-stream` for unknown types.
+
+---
+
+### `snow updateset`
+
+Manage ServiceNow update sets from the CLI — list, inspect, export, import, and diff. Also available as `snow us`.
+
+| Command | Description |
+|---|---|
+| `snow updateset list` | List update sets on the instance |
+| `snow updateset current` | Show the currently active update set |
+| `snow updateset set <name>` | Set the active update set |
+| `snow updateset show <name>` | Show details and all captured items |
+| `snow updateset capture <name> --add <table:sys_id>` | Add specific records to an update set |
+| `snow updateset export <name>` | Download the update set as an XML file |
+| `snow updateset apply <xml-file>` | Upload an XML file to another instance |
+| `snow updateset diff <set1> <set2>` | Compare captured items between two update sets |
+
+Names or sys_ids are accepted wherever `<name>` appears.
+
+#### `snow updateset list`
+
+```bash
+# All in-progress and complete update sets (default: excludes "ignore")
+snow updateset list
+
+# Filter by state
+snow updateset list --state "in progress"
+snow updateset list --state complete --limit 20
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `-s, --state <state>` | Filter by state: `in progress`, `complete`, `ignore` (default: all except `ignore`) |
+| `-l, --limit <n>` | Max results (default: `50`) |
+
+Output columns: **Name**, **State**, **Application** (scope), **Created by**, **Created on**. In-progress sets are highlighted in green; the active set is marked with a ★.
+
+#### `snow updateset current`
+
+```bash
+snow updateset current
+```
+
+Shows the update set that is currently active for the authenticated user (read from `sys_user_preference`). REST API writes go to this update set.
+
+#### `snow updateset set <name>`
+
+```bash
+snow updateset set "Sprint 42 - Incident fixes"
+snow updateset set a1b2c3d4e5f6...   # sys_id also accepted
+```
+
+Stores the selection in `sys_user_preference` so subsequent REST API operations (table updates, script pushes, etc.) are captured into the selected update set.
+
+#### `snow updateset show <name>`
+
+```bash
+snow updateset show "Sprint 42 - Incident fixes"
+snow updateset show "Sprint 42 - Incident fixes" --limit 200
+```
+
+Displays update set metadata followed by a table of every captured item (`sys_update_xml`) with type, action, and target name.
+
+#### `snow updateset capture <name> --add <table:sys_id>`
+
+Force-captures specific records into an update set without modifying them:
+
+```bash
+# Capture a single record
+snow updateset capture "My Update Set" --add sys_script_include:abc123...
+
+# Capture multiple records at once
+snow updateset capture "My Update Set" \
+  --add sys_script_include:abc123... \
+  --add sys_script:def456... \
+  --yes
+```
+
+**How it works:** temporarily activates the target update set for the authenticated user, performs a no-op PATCH on each record to trigger ServiceNow's capture mechanism, then restores the previously active update set. The records themselves are not changed.
+
+#### `snow updateset export <name>`
+
+```bash
+# Export to current directory
+snow updateset export "Sprint 42 - Incident fixes"
+
+# Export to a specific directory
+snow updateset export "Sprint 42 - Incident fixes" --out ./updatesets
+```
+
+Calls `/export_update_set.do` and saves the XML to `<safe-name>.xml`. The file can be imported into any ServiceNow instance using `snow updateset apply` or via the ServiceNow UI.
+
+#### `snow updateset apply <xml-file>`
+
+Import an update set XML into an instance. Creates a **Retrieved Update Set** record that you then load, preview, and commit.
+
+```bash
+# Apply to the active instance
+snow updateset apply ./sprint-42-incident-fixes.xml
+
+# Apply to a different instance by alias
+snow updateset apply ./sprint-42-incident-fixes.xml --target prod
+
+# Skip confirmation
+snow updateset apply ./sprint-42-incident-fixes.xml --target prod --yes
+```
+
+After uploading, the CLI prints the direct link to the Retrieved Update Set record and instructions for the load → preview → commit steps, which must be completed in the ServiceNow UI (or scripted separately).
+
+#### `snow updateset diff <set1> <set2>`
+
+Compare the captured items of two update sets side by side:
+
+```bash
+snow updateset diff "Sprint 42" "Sprint 43"
+snow updateset diff a1b2c3...  b4c5d6...   # sys_ids
+```
+
+Output shows:
+- Items only in the first set (removed in second) — in red
+- Items only in the second set (added in second) — in green
+- Items in both sets, flagged if the action changed (e.g. `INSERT_OR_UPDATE` → `DELETE`) — in yellow
+- A summary line: `3 removed  5 added  1 changed  42 unchanged`
+
+---
+
+### `snow status`
+
+Print a dashboard-style health and stats overview of the active instance. All sections run in parallel and degrade gracefully to `N/A` when the authenticated user lacks access.
+
+```bash
+snow status
+
+# Omit syslog sections (faster for non-admin users, or when syslog is restricted)
+snow status --no-errors
+```
+
+**Sections:**
+
+| Section | What it shows |
+|---|---|
+| **Instance** | ServiceNow version (`glide.version`), cluster node count and status |
+| **Users** | Total active user count |
+| **Development** | Custom scoped app count, custom table count (`x_` prefix), in-progress update sets (up to 5, with author) |
+| **Syslog errors** | Error count in the last hour + last 3 error messages with timestamps |
+| **Scheduler errors** | Failed scheduled job count in the last 24h + last 3 messages |
+
+**Example output:**
+```
+────────────────────────────────────────────────────
+  snow-cli  ·  dev  (https://dev12345.service-now.com)
+────────────────────────────────────────────────────
+
+  Instance
+  ────────
+  Version               Utah Patch 7
+  Cluster nodes         3 active / 3 total
+
+  Users
+  ─────
+  Active users          1,234
+
+  Development
+  ───────────
+  Custom apps           5
+  Custom tables         34
+  Update sets           2 in progress
+                        • My Feature Branch     admin
+                        • Hotfix-001             dev.user
+
+  Syslog errors  (last hour)
+  ──────────────────────────
+  Error count           3
+                        [10:34:01] Script error in BusinessRule 'Assign P...
+                        [10:22:45] Invalid GlideRecord field: assigne_to
+
+  Scheduler errors  (last 24h)
+  ────────────────────────────
+  Failed jobs           0
+```
+
+> **Note:** Version and cluster node stats require admin access to `sys_properties` and `sys_cluster_state`. Syslog sections require read access to the `syslog` table. Sections that can't be read are shown as `N/A` rather than failing the command.
+
 ---
 
 ### `snow provider`
@@ -677,7 +1043,12 @@ src/
     instance.ts             snow instance
     table.ts                snow table
     schema.ts               snow schema
-    script.ts               snow script
+    script.ts               snow script (pull/push/list/search/replace)
+    bulk.ts                 snow bulk (update)
+    user.ts                 snow user (add-to-group/remove-from-group/assign-role/remove-role)
+    attachment.ts           snow attachment (list/pull/push)
+    updateset.ts            snow updateset (list/current/set/show/capture/export/apply/diff)
+    status.ts               snow status
     provider.ts             snow provider
     ai.ts                   snow ai (build, chat, review, push)
   lib/