@syndicalt/snow-cli 1.1.0 → 2.0.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, browse the Service Catalog, inspect Flow Designer flows, manage scoped applications, tail system logs, and generate complete applications using AI — all from your terminal.
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -10,6 +10,17 @@ 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 diff](#snow-diff)
+  - [snow factory](#snow-factory)
+  - [snow catalog](#snow-catalog)
+  - [snow flow](#snow-flow)
+  - [snow app](#snow-app)
+  - [snow log](#snow-log)
   - [snow provider](#snow-provider)
   - [snow ai](#snow-ai)
 - [Configuration File](#configuration-file)
@@ -46,17 +57,60 @@ 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. 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
 
-# 4. Generate a simple feature
+# 8. Download all attachments from a record
+snow attachment pull incident <sys_id> --all --out ./downloads
+
+# 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"
 
-# 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"
+# 10. Compare schema/scripts between instances to detect drift
+snow diff incident --against prod --fields
+snow diff all --against test --scripts --scope x_myco_myapp
+
+# 11. Run the full factory pipeline: plan → build → test → promote
+snow factory "Build a hardware asset request app with approval workflow" --envs test,prod
 
-# 6. Start an interactive session to build iteratively
+# 12. Start an interactive session to build iteratively
 snow ai chat
+
+# 13. Browse the Service Catalog
+snow catalog list
+snow catalog search "VPN"
+snow catalog get "Request VPN Access"
+
+# 14. Inspect Flow Designer flows and actions
+snow flow list
+snow flow list --subflows --scope x_myco_myapp
+snow flow get "My Approval Flow"
+
+# 15. List scoped applications
+snow app list
+snow app get x_myco_myapp
+
+# 16. Tail system logs
+snow log
+snow log --level err --follow
+snow log app --scope x_myco_myapp
+snow log tx --slow 2000
 ```
 
 ---
@@ -331,6 +385,833 @@ 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 diff`
+
+Compare schema field definitions and script content between two configured instances. Useful for detecting drift — fields added/removed/changed, or scripts that diverged between dev and test/prod.
+
+```bash
+# Compare field definitions for a table
+snow diff incident --against prod --fields
+
+# Compare script content in an app scope between dev and test
+snow diff all --against test --scripts --scope x_myco_myapp
+
+# Compare both fields and scripts
+snow diff sys_script_include --against prod --fields --scripts
+
+# Output as Markdown (for pasting into docs or tickets)
+snow diff incident --against prod --fields --markdown
+
+# Output as JSON (for scripting or CI pipelines)
+snow diff incident --against prod --fields --scripts --json
+
+# Save the diff report to a file (ANSI stripped automatically)
+snow diff all --against prod --scripts --scope x_myco_myapp --output ./diff-report.txt
+```
+
+The source is always the **active instance** (`snow instance use <alias>` to set it). `--against` specifies the target instance alias.
+
+**Arguments:**
+
+| Argument | Description |
+|---|---|
+| `<table>` | Table to compare for `--fields`. Use `all` with `--scripts` to scan all script-bearing tables. |
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--against <alias>` | Target instance alias to compare against (required) |
+| `--fields` | Compare `sys_dictionary` field definitions |
+| `--scripts` | Compare script field content across script-bearing tables |
+| `--scope <prefix>` | Filter scripts by application scope prefix (e.g. `x_myco_myapp`) |
+| `--markdown` | Output as Markdown for docs/tickets |
+| `--json` | Output structured JSON (fields rows + script hunks) |
+| `--output <file>` | Write the diff to a file (ANSI color codes stripped automatically) |
+
+At least one of `--fields` or `--scripts` is required.
+
+#### Field diff output
+
+Shows every field that was **added** (only in target), **removed** (only in source), or **changed** (type, max_length, mandatory, read_only, reference, or active flag differs):
+
+```
+  Schema diff: incident
+  ──────────────────────────────────────────────────
+  Field                  Status    Detail
+  ──────────────────────────────────────────────────────────────────────────
+  x_myco_priority_code   added     type=string
+  x_myco_legacy_flag     removed   type=boolean
+  category               changed   max_length: 40 → 100
+```
+
+#### Script diff output
+
+For each script-bearing table, shows scripts **added** (only in target), **removed** (only in source), or **changed** (content differs), with a contextual line diff for changed scripts:
+
+```
+  Script diff: sys_script_include
+  ──────────────────────────────────────────────────
+  + NewUtils  (only in prod)
+  - OldHelper (only in dev)
+  ~ IncidentRouter
+
+  IncidentRouter
+  --- dev
+  +++ prod
+  @@ lines 12–16 @@
+     var gr = new GlideRecord('incident');
+  -  gr.addQuery('state', 1);
+  +  gr.addQuery('state', 2);
+     gr.query();
+```
+
+**Script tables scanned** (when using `--scripts`):
+
+| Table | Description |
+|---|---|
+| `sys_script_include` | Script Includes |
+| `sys_script` | Business Rules |
+| `sys_script_client` | Client Scripts |
+| `sys_ui_action` | UI Actions |
+| `sysauto_script` | Scheduled Script Executions |
+
+---
+
+### `snow factory`
+
+AI-orchestrated multi-component application pipeline. Takes a natural language description, breaks it into a dependency-ordered build plan, generates each component via LLM, pushes to the source instance, optionally generates and runs ATF tests, then promotes through additional environments.
+
+```bash
+# Plan and build (deploys to active instance only)
+snow factory "Build an employee onboarding app with custom tables, approval workflow, and email notifications"
+
+# Full pipeline: dev → test → prod
+snow factory "Build a hardware asset request app" --envs test,prod
+
+# Force all artifacts into an existing application scope
+snow factory "Add an approval business rule to the asset request app" --scope x_myco_assetreq
+
+# Preview the plan without building
+snow factory "Build an incident escalation app" --dry-run
+
+# Generate and immediately run ATF tests
+snow factory "Build a change approval workflow" --run-tests
+
+# Skip ATF test generation (faster)
+snow factory "Add a business rule to auto-assign P1 incidents" --skip-tests
+
+# Resume a failed or interrupted run
+snow factory "..." --resume abc12345
+
+# List recent factory runs
+snow factory "" --list
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--envs <aliases>` | Comma-separated instance aliases to promote to after source, in order (e.g. `test,prod`) |
+| `--scope <prefix>` | Override the application scope prefix for all artifacts (e.g. `x_myco_myapp`) |
+| `--skip-tests` | Skip ATF test generation |
+| `--run-tests` | Execute the generated ATF test suite immediately after pushing |
+| `--dry-run` | Show the generated plan only — no builds, no deployments |
+| `--resume <id>` | Resume a previous run from its checkpoint (see `--list`) |
+| `--list` | Show recent factory runs and their component completion status |
+
+#### Pipeline phases
+
+```
+  [1/N] Planning
+        LLM analyzes the prompt → structured plan with components, dependencies, risks
+        Displays plan for review → confirm before proceeding
+
+  [2/N] Building components
+        Each component is built sequentially in dependency order
+        Tables first, then script includes, then business rules / client scripts
+        Each component saved to ~/.snow/factory/<run-id>/<component>/
+
+  [3/N] Pushing to <source-instance>
+        All artifacts pushed to the active instance via Table API
+        Creates or updates existing records
+
+  [4/N] Generating ATF tests (unless --skip-tests)
+        LLM generates a test suite with server-side script assertions
+        Tests pushed to the instance as sys_atf_test + sys_atf_step records
+        Optionally executed if --run-tests is set
+
+  [5/N] Promoting to <env>  (once per additional env in --envs)
+        Checks for pre-existing artifacts on the target
+        Confirms before applying
+        Uploads combined update set XML to sys_remote_update_set
+        Prints direct link → then Load → Preview → Commit in the UI
+```
+
+#### Checkpointing and resume
+
+Every factory run is checkpointed to `~/.snow/factory/<run-id>/state.json` after each completed phase. If a run is interrupted (network error, LLM failure, manual cancellation), resume it:
+
+```bash
+snow factory "" --list                 # find the run ID
+snow factory "" --resume abc12345     # resume from last successful phase
+```
+
+The resume prompt argument is ignored when `--resume` is provided — the original prompt and plan are loaded from the checkpoint.
+
+#### Example output
+
+```
+  ────────────────────────────────────────────────────────
+  snow factory  ·  anthropic
+  Source: dev  https://dev12345.service-now.com
+  Pipeline: dev → test → prod
+  ────────────────────────────────────────────────────────
+
+  [1/5] Planning
+  ────────────────────────────────────────────────────────
+  Employee Onboarding App
+  Automates new-hire onboarding with task assignment, document tracking, and notifications
+  scope: x_myco_onboard  v1.0.0
+
+  Components (3) — ~14 artifacts
+  1. Custom Tables          (no deps)
+     Employee and HR document tracking tables
+  2. Script Includes        ← depends on: tables
+     OnboardingUtils class for task generation and notifications
+  3. Business Rules         ← depends on: tables, scripts
+     Auto-assign tasks on employee insert; notify on completion
+
+  ⚠ Risks:
+    • SMTP server must be configured for email notifications
+    • MID Server required for Active Directory sync
+
+  ? Execute factory pipeline? (3 components → dev → test → prod) Yes
+
+  [2/5] Building components
+  ────────────────────────────────────────────────────────
+  ✓ Custom Tables  2 artifacts
+     + table            x_myco_onboard_employee
+     + table            x_myco_onboard_doc
+  ✓ Script Includes  1 artifact
+     + script_include   x_myco_onboard.OnboardingUtils
+  ✓ Business Rules  3 artifacts
+     + business_rule    Auto-Assign Tasks on Insert
+     + business_rule    Notify Manager on Completion
+     + scheduled_job    Weekly Onboarding Report
+
+  ✔ 6 total artifacts combined
+
+  [3/5] Pushing to dev
+  ────────────────────────────────────────────────────────
+  created  Table             x_myco_onboard_employee
+  created  Table             x_myco_onboard_doc
+  created  Script Include    x_myco_onboard.OnboardingUtils
+  created  Business Rule     Auto-Assign Tasks on Insert
+  ...
+  6 pushed, 0 failed
+
+  [4/5] Generating ATF tests
+  ────────────────────────────────────────────────────────
+  Employee Onboarding App — ATF Suite
+  4 tests generated
+    • Test employee record creation and field defaults  (3 steps)
+    • Test OnboardingUtils task generation  (2 steps)
+    • Test business rule fires on insert  (3 steps)
+    • Test manager notification trigger  (2 steps)
+  ✓ Test suite created
+    https://dev12345.service-now.com/nav_to.do?uri=sys_atf_test_suite.do?sys_id=...
+```
+
+#### Permission-denied errors
+
+Some artifact types require elevated roles to push via the Table API:
+
+| Artifact | Required role |
+|---|---|
+| `table` (`sys_db_object`) | `admin` or `delegated_developer` |
+| `decision_table` (`sys_decision`) | `admin` or `developer` |
+| `flow_action` (`sys_hub_action_type_definition`) | `flow_designer` + `IntegrationHub` |
+
+When a 403 is encountered the artifact is **skipped** (shown in yellow) rather than failing the whole run. The generated update set XML is always written to disk regardless — use it to import via the UI when Table API access is restricted:
+
+```
+  System Update Sets → Retrieved Update Sets → Import XML → Load → Preview → Commit
+```
+
+---
+
+### `snow catalog`
+
+Browse and search the ServiceNow Service Catalog.
+
+```bash
+# List catalog items
+snow catalog list
+snow catalog list --category "Hardware"
+snow catalog list --catalog "Employee Center" -l 50
+
+# Search by name or description
+snow catalog search "VPN"
+snow catalog search "laptop" --limit 10
+
+# Get details for a specific item (by name or sys_id)
+snow catalog get "Request VPN Access"
+snow catalog get abc1234...
+
+# List catalog categories
+snow catalog categories
+snow catalog categories --catalog "IT Catalog"
+```
+
+**`snow catalog list` options:**
+
+| Flag | Description |
+|---|---|
+| `-q, --query <encoded>` | Encoded query filter |
+| `--category <name>` | Filter by category name |
+| `--catalog <name>` | Filter by catalog title |
+| `-l, --limit <n>` | Max records (default: `25`) |
+| `--json` | Output as JSON |
+
+**`snow catalog search` options:**
+
+| Flag | Description |
+|---|---|
+| `-l, --limit <n>` | Max records (default: `20`) |
+| `--json` | Output as JSON |
+
+**`snow catalog categories` options:**
+
+| Flag | Description |
+|---|---|
+| `--catalog <name>` | Filter by catalog title |
+| `-l, --limit <n>` | Max records (default: `100`) |
+| `--json` | Output as JSON |
+
+Sub-categories are indented based on their depth in the `full_name` hierarchy.
+
+---
+
+### `snow flow`
+
+List and inspect Flow Designer flows, subflows, and custom actions.
+
+```bash
+# List flows
+snow flow list
+snow flow list --scope x_myco_myapp
+snow flow list -l 50
+
+# List subflows instead
+snow flow list --subflows
+snow flow list --subflows --scope x_myco_myapp
+
+# Get details and inputs for a specific flow (by name or sys_id)
+snow flow get "My Approval Flow"
+snow flow get abc1234...
+
+# List custom Flow Designer actions
+snow flow actions
+snow flow actions --scope x_myco_myapp
+```
+
+**`snow flow list` options:**
+
+| Flag | Description |
+|---|---|
+| `--subflows` | Show subflows instead of flows |
+| `--scope <prefix>` | Filter by application scope prefix |
+| `-q, --query <encoded>` | Additional encoded query filter |
+| `-l, --limit <n>` | Max records (default: `25`) |
+| `--json` | Output as JSON |
+
+**`snow flow actions` options:**
+
+| Flag | Description |
+|---|---|
+| `--scope <prefix>` | Filter by application scope prefix |
+| `-q, --query <encoded>` | Additional encoded query filter |
+| `-l, --limit <n>` | Max records (default: `25`) |
+| `--json` | Output as JSON |
+
+`snow flow get` shows flow metadata, trigger type, run-as setting, and the list of typed input variables. It also prints the direct Flow Designer URL for the record.
+
+Active flows are shown with a green `●`; inactive with a red `○`.
+
+---
+
+### `snow app`
+
+List and inspect scoped applications on the active instance.
+
+```bash
+# List custom scoped applications (sys_app)
+snow app list
+
+# Include all system scopes (sys_scope)
+snow app list --all
+
+# Filter with an encoded query
+snow app list -q "vendor=Acme Corp"
+
+# Get details for a specific app by scope prefix or name
+snow app get x_myco_myapp
+snow app get "My Custom App"
+snow app get abc1234...   # sys_id also accepted
+```
+
+**`snow app list` options:**
+
+| Flag | Description |
+|---|---|
+| `--all` | Include all system scopes, not just custom applications |
+| `-q, --query <encoded>` | Encoded query filter |
+| `-l, --limit <n>` | Max records (default: `50`) |
+| `--json` | Output as JSON |
+
+`snow app get` shows scope prefix, sys_id, version, vendor, created/updated dates, and whether the scope has update set entries. It also prints helpful next-step commands for `snow factory` and `snow diff`.
+
+---
+
+### `snow log`
+
+View system and application logs from the active instance.
+
+```bash
+# System log (default subcommand)
+snow log
+snow log system
+snow log --level err
+snow log --source Evaluator --limit 100
+
+# Filter by scope
+snow log --scope x_myco_myapp
+
+# Follow mode — polls for new entries every 5 seconds
+snow log --follow
+snow log --follow --interval 10000
+
+# Application log (requires admin role)
+snow log app
+snow log app --scope x_myco_myapp
+
+# Transaction log
+snow log tx
+snow log tx --slow 2000   # only show responses > 2000ms
+```
+
+#### `snow log system` (default)
+
+Queries the `syslog` table. Output columns: timestamp, level, source, message.
+
+| Flag | Description |
+|---|---|
+| `--level <level>` | Filter by level: `err`, `warn`, `info`, `debug` |
+| `--source <source>` | Filter by log source (e.g. `Evaluator`, `Script`) |
+| `--scope <prefix>` | Filter by application scope prefix |
+| `-q, --query <encoded>` | Additional encoded query filter |
+| `-l, --limit <n>` | Max records (default: `50`) |
+| `--follow` | Poll for new entries (Ctrl+C to stop) |
+| `--interval <ms>` | Polling interval in ms when using `--follow` (default: `5000`) |
+| `--json` | Output as JSON |
+
+#### `snow log app`
+
+Queries the `syslog_app_scope` table, which contains application-level log entries written by `gs.log()`, `gs.warn()`, etc. **Requires the `admin` role** — a clear error is shown if access is denied.
+
+| Flag | Description |
+|---|---|
+| `--scope <prefix>` | Filter by application scope prefix |
+| `--source <source>` | Filter by log source |
+| `-l, --limit <n>` | Max records (default: `50`) |
+| `--follow` | Poll for new entries |
+| `--interval <ms>` | Polling interval in ms (default: `5000`) |
+| `--json` | Output as JSON |
+
+#### `snow log tx`
+
+Queries the `syslog_transaction` table. Output columns: timestamp, HTTP status, response time (highlighted red if > 2s), username, URL.
+
+| Flag | Description |
+|---|---|
+| `-l, --limit <n>` | Max records (default: `25`) |
+| `--slow <ms>` | Only show transactions slower than this many milliseconds |
+| `--json` | Output as JSON |
+
+---
+
+#### `snow ai test <path>`
+
+Generate ATF tests for any previously generated build and push them to the active instance. Usable independently of `snow factory`.
+
+```bash
+# Generate and push tests for a build
+snow ai test ./my-build/
+
+# Generate, push, and immediately run
+snow ai test ./my-build/ --run
+
+# Custom suite name
+snow ai test ./my-build/my-build.manifest.json --suite-name "Sprint 42 — Onboarding Tests"
+```
+
+**Options:**
+
+| Flag | Description |
+|---|---|
+| `--run` | Execute the test suite immediately after pushing via the ATF API |
+| `--suite-name <name>` | Override the generated suite name |
+
+Requires access to `sys_atf_step_config`, `sys_atf_test`, `sys_atf_test_suite`, and `sys_atf_step` tables. ATF must be enabled on the instance.
+
 ---
 
 ### `snow provider`
@@ -677,7 +1558,18 @@ 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
+    diff.ts                 snow diff (cross-instance schema/script comparison)
+    factory.ts              snow factory (AI-orchestrated multi-env app pipeline)
+    catalog.ts              snow catalog (Service Catalog browse/search)
+    flow.ts                 snow flow (Flow Designer flows, subflows, actions)
+    app.ts                  snow app (scoped application metadata)
+    log.ts                  snow log (system, app, and transaction logs)
     provider.ts             snow provider
     ai.ts                   snow ai (build, chat, review, push)
   lib/
@@ -686,6 +1578,7 @@ src/
     llm.ts                  LLM provider abstraction (OpenAI, Anthropic, xAI, Ollama)
     sn-context.ts           ServiceNow system prompt and artifact type definitions
     update-set.ts           XML update set generation and Table API push
+    atf.ts                  ATF test generation and execution utilities
   types/
     index.ts                Shared TypeScript interfaces
 ```