ServiceNow SDK + Cursor — Full Documentation

The short answer to "where is the full SDK documentation": it did not exist until this page. What the repository had was five fragments totalling about six kilobytes, plus three real working SDK projects with no prose explaining them. Worse, the file whose name promises SDK documentation does not contain any.

What does exist, and is genuinely good: three working SDK projects

Every code example in §6 of this page is taken from hr-leave-sdk/src/fluent/ — real source that has actually compiled and installed, not invented samples.

The ServiceNow SDK is a Node command-line tool that lets you define platform artefacts as TypeScript source on your own machine, compile them into an installable application package, and install that package onto an instance. The TypeScript dialect you write is called Fluent: a set of typed factory functions — Table(), BusinessRule(), Acl(), Role(), Flow() — exported from @servicenow/sdk/core.

The thing most people miss on first contact: this is not a wrapper that drives the Studio UI, and it is not an update-set generator. It produces the application package itself. Your source files are the definition of the app; the instance is a deployment target.

1.1 The honest comparison

1.2 When each one is the right answer

2.1 Prerequisites

2.2 Install into a project

mkdir my-app
cd my-app
npm init -y
npm install -D @servicenow/sdk@latest

# confirm what you got
npx @servicenow/sdk --version
npx @servicenow/sdk --help

Three binaries are installed into node_modules/.bin/: now-sdk, now-sdk-debug, and @servicenow/sdk. They are the same program. Inside an npm script you can write now-sdk build directly; from your shell use npx @servicenow/sdk build or npx now-sdk build.

This project pins the version rather than using latest, which is the right call for a team:

{
  "name": "hr-leave-sdk",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "now-sdk build",
    "clean": "now-sdk clean",
    "install:dev": "now-sdk install --auth DEV",
    "deploy:dev": "now-sdk install --auth DEV"
  },
  "devDependencies": {
    "@servicenow/sdk": "4.12.2"
  }
}

2.3 Authentication — the complete auth surface

Credentials are stored in your OS keychain under an alias, never in the project. One alias per instance.

# interactive, the normal case
npx @servicenow/sdk auth --add https://dev398980.service-now.com --type basic --alias DEV

# list what you have
npx @servicenow/sdk auth --list

# make one the default so you can drop --auth from later commands
npx @servicenow/sdk auth --use DEV

# fully non-interactive (CI, containers) — password never appears in the command line
echo "$env:SN_PASSWORD" | npx @servicenow/sdk auth --add https://dev398980.service-now.com `
  --type basic --alias DEV --username admin --password-stdin

# remove it
npx @servicenow/sdk auth --delete DEV

2.4 auth --print — the flag worth knowing about

This is the most useful command almost nobody discovers. It mints a live token from a stored credential so you can hit the REST API by hand without ever typing a password into a terminal:

# ready-to-paste curl headers
npx @servicenow/sdk auth --print DEV --format headers

# just the bearer token, for scripting
npx @servicenow/sdk auth --print DEV --format bearer

# shell-exportable form
npx @servicenow/sdk auth --print DEV --format env

Combine it with now-sdk query (§3.11) and you have a complete read-only investigation toolkit for an instance without leaving your terminal.

Three global options apply to every command: -d, --debug (print debug output, default false), -h, --help, and -v, --version. Where a command takes a source or --directory argument, the default is the current working directory — so run commands from the project root and you can omit it.

3.1 The twelve commands at a glance

3.2 init — create or convert a project

# brand new app, fully specified so it never prompts
npx @servicenow/sdk init --appName "HR Leave" --packageName hr-leave-sdk `
  --scopeName x_786686_hr_leave --auth DEV

# with a UI template
npx @servicenow/sdk init --appName "Ops Console" --packageName ops-console `
  --scopeName x_acme_ops --template partial.typescript.react --auth DEV

# convert an existing scoped app that lives on the instance
npx @servicenow/sdk init --from c84db0e8839f0b509f02b0d6feaad3c9 --auth DEV

3.3 build — compile Fluent into an installable package

npx @servicenow/sdk build
npx @servicenow/sdk build --frozenKeys        # CI gate
npx @servicenow/sdk build --errorOnConflict   # strict mode, recommended once stable

3.4 install — push the app to an instance

npx @servicenow/sdk install --auth DEV
npx @servicenow/sdk install --auth DEV --open-browser
npx @servicenow/sdk install --auth DEV --info          # what is currently installed?
npx @servicenow/sdk install --auth DEV --reinstall     # nuclear: read the warning first

3.5 download — pull application metadata from an instance

npx @servicenow/sdk download ./downloaded
npx @servicenow/sdk download ./downloaded --incremental

3.6 transform — turn instance records into Fluent source

# bring every business rule and ACL of the app into Fluent
npx @servicenow/sdk transform --table sys_script,sys_security_acl --auth DEV

# convert an update set XML you already exported
npx @servicenow/sdk transform --from ./exports/update-set.xml

3.7 dependencies — types and declared dependencies

# after git clone
npm install
npx @servicenow/sdk dependencies --auth DEV

# just refresh GlideRecord / GlideSystem types for editor autocomplete
npx @servicenow/sdk dependencies --type-defs-only --auth DEV

# depend on a global flow action so Fluent can reference it
npx @servicenow/sdk dependencies --add actions --scope global --auth DEV

3.8 clean and pack

npx @servicenow/sdk clean
npx @servicenow/sdk build
npx @servicenow/sdk pack
# → target/hr_leave_sdk_1_0_0.zip  (this project's artefact is 114 KB)

3.9 query — read instance data from your terminal

# what is in my app's table right now?
npx @servicenow/sdk query x_786686_hr_leave_req_v2 -q "u_state=submitted" `
  -f u_number,u_state,u_days_count --display-value all --auth DEV

# grab a single sys_id for a script, unquoted
npx @servicenow/sdk query sys_user -q "user_name=admin" `
  -s "records[0].sys_id" -o raw --auth DEV

# did my business rule actually fire? check the audit table
npx @servicenow/sdk query x_786686_hr_leave_audit_v2 -q "ORDERBYDESCsys_created_on" `
  --limit 5 -f u_old_state,u_new_state,u_event_type --auth DEV

3.10 cicd — app repository and test suite operations

npx @servicenow/sdk cicd publish --help
npx @servicenow/sdk cicd testsuite --help

3.11 explain — covered in its own section

explain deserves more than a table. See §4.

The SDK ships its own complete reference offline. On your installed 4.12.2 there are 256 topics: 152 API references (one per Fluent artefact type) and 97 narrative guides, plus faq, keys-file, now-config-reference and the language overviews. No network, no browser, no stale documentation site.

4.1 How to actually use it

# what topics exist at all?
npx @servicenow/sdk explain --list

# narrow by keyword — every flow-related topic
npx @servicenow/sdk explain --list flow

# read the full API reference for a Fluent type
npx @servicenow/sdk explain businessrule-api
npx @servicenow/sdk explain acl-api
npx @servicenow/sdk explain table-api

# read a narrative guide rather than a reference
npx @servicenow/sdk explain business-rule-guide
npx @servicenow/sdk explain security-guide
npx @servicenow/sdk explain keys-file

# quick summary when you only need to remember the shape
npx @servicenow/sdk explain scriptinclude-api --peek

# pipe clean markdown into a file, or into an AI assistant
npx @servicenow/sdk explain ci-integration --format raw > ci-notes.md

4.2 Searching works on keywords, not just names

Every topic carries a keyword list, so you can search by what you are trying to do rather than by the artefact name. Topics are tagged with ServiceNow table names, UI labels and synonyms — acl-api is findable via access control, security, permission and sys_security_acl. Try the thing you would type into the filter navigator; it usually hits.

4.3 The AI-assistant angle

This is the single most valuable thing in this document for anyone pairing the SDK with Cursor. Fluent's API surface is large and moves between versions, so a model answering from memory will confidently invent property names. explain --format raw emits clean markdown designed to be piped — which means you can ground the assistant in the exact API of your exact version:

# give the assistant the real API before asking it to write code
npx @servicenow/sdk explain scheduledscript-api --format raw | clip     # Windows
npx @servicenow/sdk explain scheduledscript-api --format raw | pbcopy   # macOS

Then paste it into the chat with "use this exact API". The repository's own Cursor rule already encodes this instinct — rule 2 in .cursor/rules/servicenow-sdk-master.mdc says to run explain when the API is uncertain. That rule is correct and worth keeping.

5.1 Layout of a real project

This is hr-leave-sdk exactly as it exists in this repository:

hr-leave-sdk/
├─ now.config.json          # scope, scopeId, app name, where Fluent lives
├─ package.json             # pinned SDK version + npm scripts
├─ package-lock.json        # 481 KB — commit it
├─ .gitignore
├─ .now/
│  └─ bom.json              # bill of materials the build maintains
├─ src/
│  └─ fluent/               # ← everything you write lives here
│     ├─ tables.now.ts
│     ├─ roles.now.ts
│     ├─ acls.now.ts
│     ├─ script-includes.now.ts
│     ├─ business-rules.now.ts
│     ├─ client-scripts.now.ts
│     ├─ events.now.ts
│     ├─ notifications.now.ts
│     ├─ catalog.now.ts
│     ├─ properties.now.ts
│     ├─ menu.now.ts
│     ├─ flows/
│     │  └─ leave-approval.now.ts
│     └─ generated/
│        └─ keys.ts         # ← GENERATED, BUT COMMIT IT. See 5.3.
├─ dist/                    # build output: XML update records  (do not commit)
└─ target/
   └─ hr_leave_sdk_1_0_0.zip   # packaged artefact, 114 KB  (do not commit)

5.2 now.config.json

{
  "$schema": "https://www.servicenow.com/sdk/now.config.schema.json",
  "scope": "x_786686_hr_leave",
  "scopeId": "e5f5bc9493a303507520703efaba104d",
  "name": "HR Leave",
  "fluentDir": "src/fluent",
  "clientDir": ""
}

Run npx @servicenow/sdk explain now-config-reference for the full schema of every key this file accepts.

5.3 keys.ts — the most important file in the project

Every Fluent record can carry a $id, written as Now.ID['some_identifier']. The build maps each of those identifiers to a concrete ServiceNow sys_id and writes the mapping into src/fluent/generated/keys.ts as a TypeScript declaration:

// src/fluent/generated/keys.ts  — generated, ~1,340 lines in this project
import '@servicenow/sdk/global'

declare global {
    namespace Now {
        namespace Internal {
            interface Keys extends KeysRegistry {
                explicit: {
                    hrlx_acl_approver_write: {
                        table: 'sys_security_acl'
                        id: 'a6b167fdbf204118a048cc5741627408'
                    }
                    hrlx_acl_audit_create: {
                        table: 'sys_security_acl'
                        id: 'c0cbf0ef04424544aa0c65b562ea6a2a'
                    }
                    // … one entry per identified record
                }
            }
        }
    }
}

5.4 What to commit and what to ignore

We build the same application the Studio chapters build, but as code. Follow in order; each file imports the one before it.

6.0 Create the project

mkdir hr-leave-sdk; cd hr-leave-sdk
npm init -y
npm install -D @servicenow/[email protected]
npx @servicenow/sdk auth --add https://dev398980.service-now.com --type basic --alias DEV
npx @servicenow/sdk init --appName "HR Leave" --packageName hr-leave-sdk `
  --scopeName x_786686_hr_leave --auth DEV
npx @servicenow/sdk dependencies --auth DEV      # get the type definitions

6.1 Tables — src/fluent/tables.now.ts

Four tables. Note the shared leaveTypeChoices object reused across two tables — the kind of deduplication that is impossible in Studio and free in code.

import {
  Table,
  StringColumn,
  IntegerColumn,
  ReferenceColumn,
  DateColumn,
  ChoiceColumn,
} from '@servicenow/sdk/core'

const leaveTypeChoices = {
  annual: { label: 'Annual', sequence: 1 },
  sick: { label: 'Sick', sequence: 2 },
  unpaid: { label: 'Unpaid', sequence: 3 },
}

export const x_786686_hr_leave_employee_v2 = Table({
  name: 'x_786686_hr_leave_employee_v2',
  label: 'HR Employee',
  schema: {
    u_user: ReferenceColumn({ label: 'User', referenceTable: 'sys_user' }),
    u_employee_id: StringColumn({ label: 'Employee ID', maxLength: 40 }),
    u_department: StringColumn({ label: 'Department', maxLength: 100 }),
    u_manager: ReferenceColumn({ label: 'Manager', referenceTable: 'sys_user' }),
    u_join_date: DateColumn({ label: 'Join Date' }),
    u_grade: StringColumn({ label: 'Grade', maxLength: 20 }),
  },
})

export const x_786686_hr_leave_req_v2 = Table({
  name: 'x_786686_hr_leave_req_v2',
  label: 'Leave Request',
  schema: {
    u_number: StringColumn({ label: 'Number', maxLength: 40 }),
    u_requested_for_user: ReferenceColumn({ label: 'Requested For', referenceTable: 'sys_user' }),
    u_employee_ref: ReferenceColumn({
      label: 'Employee',
      referenceTable: 'x_786686_hr_leave_employee_v2',
    }),
    u_leave_type: ChoiceColumn({ label: 'Leave Type', choices: leaveTypeChoices }),
    u_start_date: DateColumn({ label: 'Start Date' }),
    u_end_date: DateColumn({ label: 'End Date' }),
    u_days_count: IntegerColumn({ label: 'Days' }),
    u_state: ChoiceColumn({
      label: 'State',
      choices: {
        draft: { label: 'Draft', sequence: 1 },
        submitted: { label: 'Submitted', sequence: 2 },
        approved: { label: 'Approved', sequence: 3 },
        rejected: { label: 'Rejected', sequence: 4 },
        cancelled: { label: 'Cancelled', sequence: 5 },
      },
    }),
    u_approver_user: ReferenceColumn({ label: 'Approver', referenceTable: 'sys_user' }),
    u_reason: StringColumn({ label: 'Reason', maxLength: 1000 }),
  },
})

export const x_786686_hr_leave_bal_v2 = Table({
  name: 'x_786686_hr_leave_bal_v2',
  label: 'Leave Balance',
  schema: {
    u_employee_ref: ReferenceColumn({
      label: 'Employee',
      referenceTable: 'x_786686_hr_leave_employee_v2',
    }),
    u_year: IntegerColumn({ label: 'Year' }),
    u_leave_type: ChoiceColumn({ label: 'Leave Type', choices: leaveTypeChoices }),
    u_entitled: IntegerColumn({ label: 'Entitled' }),
    u_used: IntegerColumn({ label: 'Used' }),
    u_remaining: IntegerColumn({ label: 'Remaining' }),
  },
})

export const x_786686_hr_leave_audit_v2 = Table({
  name: 'x_786686_hr_leave_audit_v2',
  label: 'Leave Audit',
  schema: {
    u_leave_ref: ReferenceColumn({
      label: 'Leave',
      referenceTable: 'x_786686_hr_leave_req_v2',
    }),
    u_old_state: StringColumn({ label: 'Old State', maxLength: 40 }),
    u_new_state: StringColumn({ label: 'New State', maxLength: 40 }),
    u_event_type: StringColumn({ label: 'Event Type', maxLength: 60 }),
    u_actor: ReferenceColumn({ label: 'Actor', referenceTable: 'sys_user' }),
  },
})

Column types available include StringColumn, IntegerColumn, DecimalColumn, FloatColumn, BooleanColumn, DateColumn, DateTimeColumn, DurationColumn, ChoiceColumn, ReferenceColumn, DocumentIdColumn, HtmlColumn, JsonColumn, ScriptColumn, UrlColumn, EmailColumn, Password2Column, ListColumn, GuidColumn and about forty more. Run npx @servicenow/sdk explain --list column for the full set on your version.

6.2 Roles — src/fluent/roles.now.ts

import { Role } from '@servicenow/sdk/core'

export const roleEmployee = Role({
  name: 'x_786686_hr_leave.employee',
  description: 'Submit and view own leave requests',
  grantable: true,
})

export const roleManager = Role({
  name: 'x_786686_hr_leave.manager',
  description: 'Approve team leave requests',
  grantable: true,
})

export const roleHrAdmin = Role({
  name: 'x_786686_hr_leave.hr_admin',
  description: 'Full HR Leave administration',
  grantable: true,
})

export const roleIntegration = Role({
  name: 'x_786686_hr_leave.integration',
  description: 'API / integration leave create access',
  grantable: true,
})

These are plain TypeScript exports, which is what makes the next file type-safe.

6.3 ACLs — src/fluent/acls.now.ts

Here is the first real payoff of code over Studio: ACLs import the role objects rather than referencing role names as strings. Rename a role and the compiler finds every ACL that used it.

import { Acl } from '@servicenow/sdk/core'
import { roleEmployee, roleHrAdmin, roleIntegration, roleManager } from './roles.now'

Acl({
  $id: Now.ID['hrlx_acl_req_read'],
  type: 'record',
  table: 'x_786686_hr_leave_req_v2',
  operation: 'read',
  adminOverrides: true,
  active: true,
  description: 'Read leave via security utils',
  script: `answer = new x_786686_hr_leave.HRLXProSecurityUtilsV2().canReadLeave(current);`,
})

Acl({
  $id: Now.ID['hrlx_acl_req_write'],
  type: 'record',
  table: 'x_786686_hr_leave_req_v2',
  operation: 'write',
  adminOverrides: true,
  active: true,
  description: 'Write leave via security utils',
  script: `answer = new x_786686_hr_leave.HRLXProSecurityUtilsV2().canWriteLeave(current);`,
})

Acl({
  $id: Now.ID['hrlx_acl_req_create'],
  type: 'record',
  table: 'x_786686_hr_leave_req_v2',
  operation: 'create',
  adminOverrides: true,
  active: true,
  roles: [roleEmployee, roleHrAdmin, roleIntegration],   // ← typed references
  description: 'Create leave for employee/hr/integration',
  script: `answer = gs.hasRole('x_786686_hr_leave.employee')
 || gs.hasRole('x_786686_hr_leave.hr_admin')
 || gs.hasRole('x_786686_hr_leave.integration');`,
})

Acl({
  $id: Now.ID['hrlx_acl_req_delete'],
  type: 'record',
  table: 'x_786686_hr_leave_req_v2',
  operation: 'delete',
  adminOverrides: true,
  active: true,
  roles: [roleHrAdmin],
  description: 'Delete leave HR admin only',
})

// field-level ACL: only HR admin may change the approver
Acl({
  $id: Now.ID['hrlx_acl_approver_write'],
  type: 'record',
  table: 'x_786686_hr_leave_req_v2',
  field: 'u_approver_user',
  operation: 'write',
  adminOverrides: true,
  active: true,
  roles: [roleHrAdmin],
  description: 'Approver field writeable by HR admin',
  script: `answer = gs.hasRole('x_786686_hr_leave.hr_admin');`,
})

The real file continues with read/write/create/delete for the employee, balance and audit tables — sixteen ACLs in total, each with a stable $id. Writing sixteen ACLs in Studio is an afternoon of clicking; here it is a file you can review in two minutes and diff forever.

6.4 Business rules — src/fluent/business-rules.now.ts

The server script is a template literal. Keep it as the same JavaScript you would paste into Studio, so the code is portable in both directions.

import { BusinessRule } from '@servicenow/sdk/core'

export const BR1_calculate_days = BusinessRule({
  $id: Now.ID['hrlx_br1_calculate_days'],
  name: 'HRLX BR1 Calculate Days',
  table: 'x_786686_hr_leave_req_v2',
  when: 'before',
  action: ['insert', 'update'],
  order: 100,
  active: true,
  script: `(function executeRule(current, previous /*null when inserting*/) {

    var util = new x_786686_hr_leave.HRLXProLeaveUtilsV2();

    if (current.u_start_date.changes() || current.u_end_date.changes() || current.isNewRecord()) {
        current.u_days_count = util.calculateBusinessDays(
            current.getValue('u_start_date'),
            current.getValue('u_end_date')
        );
    }

    if (current.u_employee_ref.changes() || current.isNewRecord()) {
        util.setApproverFromEmployee(current);
    }

})(current, previous);`,
})

export const BR2_on_submit_event = BusinessRule({
  $id: Now.ID['hrlx_br2_on_submit_event'],
  name: 'HRLX BR2 On Submit Event',
  table: 'x_786686_hr_leave_req_v2',
  when: 'after',
  action: ['insert', 'update'],
  order: 200,
  active: true,
  script: `(function executeRule(current, previous) {

    if (current.u_state.changesTo('submitted')) {
        gs.eventQueue(
            'x_786686_hr_leave.leave_v2.submitted',
            current,
            current.getValue('u_approver_user'),
            current.getValue('u_number')
        );
    }

})(current, previous);`,
})

export const BR3_audit_state_change = BusinessRule({
  $id: Now.ID['hrlx_br3_audit_state_change'],
  name: 'HRLX BR3 Audit State Change',
  table: 'x_786686_hr_leave_req_v2',
  when: 'after',
  action: ['update'],
  order: 300,
  active: true,
  script: `(function executeRule(current, previous) {

    if (!current.u_state.changes()) return;

    var util = new x_786686_hr_leave.HRLXProLeaveUtilsV2();
    util.auditStateChange(
        current.getUniqueValue(),
        previous ? previous.getValue('u_state') : '',
        current.getValue('u_state'),
        'state_change'
    );

    if (current.u_state.changesTo('approved') && current.u_employee_ref) {
        var year = new GlideDateTime(current.getValue('u_start_date')).getYearLocalTime();
        util.recalculateBalance(current.getValue('u_employee_ref'), year);
    }

})(current, previous);`,
})

6.5 Build and install

npx @servicenow/sdk build
npx @servicenow/sdk install --auth DEV --open-browser

6.6 Verify on the instance

Do not trust "install succeeded" — check the instance, ideally without leaving the terminal:

# the app record
npx @servicenow/sdk query sys_app -q "scope=x_786686_hr_leave" `
  -f name,scope,version --display-value all --auth DEV

# did all four business rules land, and in the right order?
npx @servicenow/sdk query sys_script -q "sys_scope.scope=x_786686_hr_leave^ORDERBYorder" `
  -f name,table,when,order,active --auth DEV

# all sixteen ACLs?
npx @servicenow/sdk query sys_security_acl -q "sys_scope.scope=x_786686_hr_leave" `
  -f name,operation,admin_overrides --auth DEV --limit 50

Or open the forms directly — replace {BASE} with your instance:

6.7 The daily loop

cd C:\SVCProject\HR_Leave_App\servicenow-ai-workspace\hr-leave-sdk

# 1. edit a .now.ts file
# 2. build
npx @servicenow/sdk build
# 3. install
npx @servicenow/sdk install --auth DEV
# 4. verify
npx @servicenow/sdk query x_786686_hr_leave_req_v2 -q "" --limit 3 --auth DEV
# 5. commit — INCLUDING keys.ts if it changed
git add -A; git commit -m "BR5: block overlapping leave requests"

7.1 The actual reason this pairing works

An AI assistant cannot help you fill in a Studio form. It can help enormously with a TypeScript file it can read, edit and type-check. Moving platform development into source is what makes AI assistance possible at all — that, not any Cursor feature, is the whole argument.

The second-order effect matters just as much: because the SDK ships explain, you can feed the assistant the exact API of your exact version instead of letting it guess from training data. A grounded assistant writing Fluent is genuinely productive; an ungrounded one invents plausible property names that fail at build time.

7.2 Open the workspace

cursor C:\SVCProject\HR_Leave_App\servicenow-ai-workspace

Open the workspace root, not a single app folder, so the assistant can see all three projects and the shared rules.

7.3 The rules file

This project already has .cursor/rules/servicenow-sdk-master.mdc. Rules files use front matter to control when they apply:

---
description: ServiceNow SDK Fluent — Cursor Agent rules (HR + CRM + Portal)
globs: "**/*.now.ts,**/now.config.json,**/package.json"
alwaysApply: true
---

# ServiceNow SDK + Cursor (Auto / Agent mode)

## Before any Fluent code
1. Read `package.json` for `@servicenow/sdk` version.
2. Run `npx @servicenow/sdk explain "<ArtifactType>"` when API is uncertain.
3. After edits: `npx @servicenow/sdk build`.

## Scopes (three apps in this workspace)
- **HR Leave:** `x_786686_hr_leave` — tables suffix `_v2`, SI prefix `HRLX`
- **CRM Suite:** `x_snc_crm_suite` — SI prefix `CRM`
- **Portal Website:** `x_snc_sp_website` — widgets in `portal-website-sdk/src/portal/`

## Conventions
- Custom fields: `u_` prefix only.
- Server scripts: `getValue()` / `setValue()`, `gs.nil()`, `setLimit()` on queries.
- User text: `gs.getMessage()`. Logging: `gs.info('[scope] ...')`.
- Never hard-code sys_ids. Never commit passwords or API keys.
- Windows terminal: PowerShell commands only.
- Always commit `src/fluent/generated/keys.ts` when a build changes it.

## Deploy (ask user before production)
- Dev PDI: `npx @servicenow/sdk install --auth DEV`
- All three: `.\scripts\deploy-all.ps1`

7.4 The four rules that pay for themselves

7.5 A workflow that actually works

1. Describe the artefact, not the code. "Add a business rule on req_v2 that blocks submitting a request overlapping an existing approved one for the same employee" beats pasting half an implementation.
2. Point at the pattern. "Follow the style of BR3_audit_state_change in business-rules.now.ts." The existing file is better context than any prompt you can write.
3. Make it ground itself. "Run explain businessrule-api first and use that exact API."
4. Require a build. "Then run the build and fix anything it reports."
5. Review the diff, not the chat. Judge the .now.ts change in the editor. The explanation in the chat window is not the deliverable.
6. Install yourself. You run install --auth DEV, after reading the diff.

7.6 Give the assistant live instance access

Two options, in increasing order of power:

Start with query. It costs nothing, it is already authenticated through your stored alias, and it covers "what does the instance actually look like right now" — which is 90% of what the assistant needs.

7.7 What to keep out of the repository

Three commands cover adoption, and they are not interchangeable:

8.1 The low-risk adoption sequence

1. Step 1 On a clone of your instance, not the real one, run init --from <app sys_id> --auth DEV.
2. Step 2 Build immediately: npx @servicenow/sdk build. Whatever fails to compile is your conversion gap list.
3. Step 3 Install onto a second clean instance and compare against the original. This is the only honest test that the conversion is faithful.
4. Step 4 Commit everything, including keys.ts, before touching a single line.
5. Step 5 Only now declare the app SDK-managed and tell the team to stop editing it in Studio.

8.2 Incremental adoption with transform

# week 1: bring the security model under source control
npx @servicenow/sdk transform --table sys_security_acl,sys_user_role --auth DEV

# week 2: server logic
npx @servicenow/sdk transform --table sys_script,sys_script_include --auth DEV

# week 3: client side
npx @servicenow/sdk transform --table sys_script_client,sys_ui_policy --auth DEV

# convert an update set XML you exported earlier — no instance required
npx @servicenow/sdk transform --from ./exports/HR_Leave_Build.xml

Transform one artefact type per pull request. A single commit that converts an entire application is unreviewable, and conversion issues are exactly the kind you want a reviewer to catch.

9.1 The two things CI must do

1. Gate on --frozenKeys. Catch the uncommitted keys.ts before merge, not after it corrupts an instance.
2. Authenticate without a keychain. CI has no OS keychain, so the CLI reads credentials from environment variables instead — but only when you explicitly switch it into CI mode.

9.2 CI mode and its environment variables

CI mode is gated by a single variable. Without it the CLI looks for a keychain and fails:

Prefer OAuth. The client secret authenticates the CI system itself rather than impersonating a person, so a leak can be rotated without touching anyone's account, and there is no live user password sitting in a pipeline variable for a compromised job to exfiltrate.

9.3 Instance-side OAuth setup — all three steps are mandatory

1. Service user. Must have the admin role, and must have Identity Type = Human on its sys_user record. The SDK's installer processor rejects non-human accounts.
2. Enable the grant type. The system property glide.oauth.inbound.client.credential.grant_type.enabled must exist and be true. Create it in sys_properties if it is not there.
3. Register the OAuth client in the Application Registry and map the service user from step 1 as the OAuth application user.

The CLI calls ${SN_SDK_INSTANCE_URL}/oauth_token.do once at startup with grant_type=client_credentials and uses the returned token for everything after. There is no refresh token in this grant; each run gets a fresh token.

9.4 A corrected GitHub Actions workflow

The workflow currently in this repository will not run — it calls validate and passes auth flags that do not exist. Here is the working version:

name: Deploy ServiceNow Apps
on:
  push:
    branches: [main, develop]
    paths: ['HR_Leave_App/servicenow-ai-workspace/**']
  workflow_dispatch:

jobs:
  build-and-install:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        app: [hr-leave-sdk, crm-suite-sdk, portal-website-sdk]
    defaults:
      run:
        working-directory: HR_Leave_App/servicenow-ai-workspace/${{ matrix.app }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      # The gate. Fails if someone forgot to commit keys.ts.
      - name: Build and verify keys.ts is committed
        run: npx @servicenow/sdk build --frozenKeys

      # Install to the TEST instance on main only. Never to production.
      - name: Install to test instance
        if: github.ref == 'refs/heads/main'
        env:
          SN_SDK_NODE_ENV: SN_SDK_CI_INSTALL
          SN_SDK_AUTH_TYPE: oauth
          SN_SDK_INSTANCE_URL: ${{ secrets.SN_INSTANCE_URL }}
          SN_SDK_OAUTH_CLIENT_ID: ${{ secrets.SN_OAUTH_CLIENT_ID }}
          SN_SDK_OAUTH_CLIENT_SECRET: ${{ secrets.SN_OAUTH_CLIENT_SECRET }}
        run: npx @servicenow/sdk install

9.5 A corrected deploy-all.ps1

# Deploy all three SDK apps to a dev PDI (run from the workspace root)
param(
    [string]$AuthAlias = "DEV"
)

$ErrorActionPreference = "Stop"
$root = Split-Path $PSScriptRoot -Parent          # scripts/ lives one level below the root
$apps = @("hr-leave-sdk", "crm-suite-sdk", "portal-website-sdk")

foreach ($app in $apps) {
    Write-Host "`n========== $app ==========" -ForegroundColor Cyan
    Push-Location (Join-Path $root $app)

    npm ci
    if ($LASTEXITCODE -ne 0) { Pop-Location; throw "npm ci failed: $app" }

    npx @servicenow/sdk build
    if ($LASTEXITCODE -ne 0) { Pop-Location; throw "Build failed: $app" }

    npx @servicenow/sdk install --auth $AuthAlias
    if ($LASTEXITCODE -ne 0) { Pop-Location; throw "Install failed: $app" }

    Pop-Location
}

Write-Host "`nAll 3 apps installed on '$AuthAlias'." -ForegroundColor Green

Three fixes versus the current script: the validate step is gone, $root now resolves to the workspace root instead of the scripts/ folder it was pointing at, and Pop-Location runs before each throw so a failure does not leave your shell in the wrong directory.

Verifying this documentation against SDK 4.12.2 surfaced real defects in files that are already in the project. They are not cosmetic: seven files call a command that does not exist, and that command sits in the middle of every deploy path this workspace has.

10.1 The validate problem — all seven call sites

npx @servicenow/sdk validate returns Unknown command: validate and exits non-zero. Every one of these runs it:

The fix is the same everywhere: delete the validate step. Validation already happens inside build. Where a stricter gate is wanted, that is build --frozenKeys --errorOnConflict, not a separate command.

10.2 Three more defects

Worth noticing why this happened at all: validate is a perfectly reasonable thing for a CLI to have, which is exactly why it propagated into seven files unchallenged. Every one of them was written from what the SDK ought to look like. That is the argument for explain and --help over recollection, and it applies to humans as much as to assistants.

10.3 The commands that do not exist in 4.12.2

11.1 When nothing above matches

1. npx @servicenow/sdk <command> --help — confirm the flag you used is real on your version.
2. npx @servicenow/sdk explain faq — the SDK's own FAQ, offline.
3. npx @servicenow/sdk --debug <command> — verbose logging.
4. npx @servicenow/sdk query sys_update_xml -q "sys_created_on>javascript:gs.hoursAgo(1)" --auth DEV — see what the last install actually wrote.

Read any of these with npx @servicenow/sdk explain <topic>. Add --format raw to get markdown suitable for piping into an assistant (§4).

13.1 Everything you type daily

# --- setup, once per machine ---
npm install -D @servicenow/[email protected]
npx @servicenow/sdk auth --add https://devXXXXXX.service-now.com --type basic --alias DEV
npx @servicenow/sdk auth --list

# --- new project ---
npx @servicenow/sdk init --appName "My App" --packageName my-app \
    --scopeName x_mycode_myapp --auth DEV
npx @servicenow/sdk dependencies --auth DEV

# --- adopt an existing app ---
npx @servicenow/sdk init --from <app_sys_id> --auth DEV       # whole app
npx @servicenow/sdk transform --table sys_script --auth DEV    # one artefact type
npx @servicenow/sdk transform --from ./update-set.xml          # from XML, offline

# --- the loop ---
npx @servicenow/sdk build
npx @servicenow/sdk install --auth DEV
npx @servicenow/sdk query sys_app -q "scope=x_mycode_myapp" -f name,version --auth DEV
git add -A ; git commit -m "..."         # keys.ts included

# --- getting unstuck ---
npx @servicenow/sdk explain --list <keyword>
npx @servicenow/sdk explain <topic>
npx @servicenow/sdk <command> --help

# --- CI ---
npx @servicenow/sdk build --frozenKeys --errorOnConflict
SN_SDK_NODE_ENV=SN_SDK_CI_INSTALL SN_SDK_AUTH_TYPE=oauth npx @servicenow/sdk install

# --- housekeeping ---
npx @servicenow/sdk clean
npx @servicenow/sdk pack

13.2 The six things that actually bite

13.3 All twelve commands, one line each