---
name: nowdev-ai-toolbox-servicenow-sdk
user-invocable: false
description: NowDev wrapper for the ServiceNow SDK CLI (now-sdk). Loads ServiceNow's official now-sdk skill first and adds NowDev guardrails — no npx, approval gates for install/cicd/auth/move, credential and query-data safety — plus a fallback for when the official skill is not installed. Use whenever an agent needs to run now-sdk, look up Fluent API docs (explain), query live instance data, or build, install, or deploy. For NowDev routing and project conventions, use nowdev-ai-toolbox-fluent-development.
---

# now-sdk — NowDev Wrapper

This skill is the **sole NowDev authority** for `now-sdk` command construction. Every agent or skill that invokes `now-sdk` loads this skill first. Other resources may own business purpose, tables, fields, encoded-query intent, evidence requirements, and documentation topic IDs, but must not duplicate complete commands or prescribe flags.

This skill does **not** own NowDev routing, agent delegation, domain workflows, or the meaning of retrieved evidence — use the relevant domain skill and `nowdev-ai-toolbox-fluent-development` for those.

## 1. Load the official `now-sdk` skill first

ServiceNow publishes an official agent skill named **`now-sdk`** (source: `github.com/ServiceNow/sdk`, folder `skills/now-sdk`; requires SDK 4.6+). It is the primary authority for CLI usage and Fluent orientation, and it is updated together with the SDK.

- If a skill named `now-sdk` is available, **load it and follow it**. The NowDev rules in sections 3–5 still apply on top of it; where they are stricter, they win.
- If it is not available, follow the fallback in section 2 and tell the user once that it can be installed:
  - GitHub Copilot / VS Code / Copilot CLI: `gh skill install` from the `ServiceNow/sdk` repository (skill `now-sdk`).
  - Claude Code: `/plugin install servicenow-sdk@claude-plugins-official`.

## 2. Fallback when the official skill is unavailable

**Resolve the command.** `now-sdk` is called directly from an existing install — never through `npx`, `npm exec`, `pnpm dlx`, or an ad-hoc global install. Check, in order: `now-sdk --version` (global, on PATH); `./node_modules/.bin/now-sdk` (POSIX) or `.\node_modules\.bin\now-sdk.cmd` (Windows); then a nested package's `node_modules/.bin` in monorepos. If none resolves, stop and tell the user. The package is **`@servicenow/sdk`** (`npm install -g @servicenow/sdk`, Node.js 20.18 or later); describe installation only when the user asks, and never run it without explicit confirmation.

**Discover before use.** Run `now-sdk --help` once per conversation, and `now-sdk <command> --help` before first use of any command. Never guess a flag.

**Orient per Fluent project.** For every distinct `now.config.json` touched (walk up from cwd), before other doc lookups:

```bash
now-sdk explain quickstart --list --format raw
now-sdk explain fluent-language --list --format raw
now-sdk explain <each-listed-topic> --format raw
now-sdk explain keys-file --format raw
```

Read every listed topic in full; installed docs are versioned with the project's pinned SDK, so orientation does not transfer between projects.

**Documentation lookup.** `explain` (SDK 4.6+) is offline and read-only. Preview before reading a full topic:

```bash
now-sdk explain --list <keyword> --format raw
now-sdk explain <topic> --peek --format raw
now-sdk explain <topic> --format raw
```

Always pass `--format raw`. `No documentation found` means a wrong topic name — retry with `--list <keyword>`. If `explain` itself is not recognized, the SDK is too old; tell the user rather than inventing a workaround. Use configured SDK documentation sources (MCP or llms.txt) only as supplementary context when an installed topic does not cover the question.

**Live instance data.** `query` (SDK 4.8+) is read-only:

```bash
now-sdk explain query --format raw
now-sdk explain encoded-query-guide --format raw
now-sdk query <table> -q '<encoded-query>' -f <fields> --limit 25 -o json
```

Other query flags (confirm with `--help`): `--offset`, `--display-value`, `--exclude-reference-link`, `--no-count`, `--timeout`, `--view`, `--query-category`, `--query-no-domain`, `--auth`.

## 3. Query and data safety

- Keep queries bounded: a small `--limit` (10–25) and only the `--fields` you need, unless the user asked for an export or count.
- With more than one auth alias configured, always pass `--auth <alias>`; ask when dev/test/prod is ambiguous.
- Prefer metadata-first discovery when the schema is uncertain.
- Never retrieve credential values, secrets, tokens, password fields, encryption material, or unrestricted journal content. For PII, journals, email bodies, logs, HR/security data, or production identifiers, request the minimum, redact before reporting, and summarize instead of pasting raw rows.
- Treat output as an envelope: check success, warnings, truncation, and pagination before concluding. Never treat the first page as the whole population.
- Live query results are task-scoped evidence, not project knowledge.

## 4. Commands (SDK 4.13)

Every row needs its own `--help` before use — this table is for orientation, not a flag reference.

| Command | Purpose | Notable options |
|---|---|---|
| `now-sdk auth` | Manage instance credential aliases | `--add`, `--type basic\|oauth`, `--alias`, `--list`, `--use`, `--delete`, `--print` (4.12+, `--format headers\|bearer\|env`) |
| `now-sdk init` | Scaffold an app, or convert an existing app (`--from`) | `--template` (`base`, `typescript.basic`, `typescript.react`, `javascript.basic`, `javascript.react`, `partial.*`), `--appName`, `--packageName`, `--scopeName` |
| `now-sdk build [source]` | Compile Fluent sources | `--frozenKeys`, `--errorOnConflict`, `--skipClean` |
| `now-sdk install` | Install or update the app on an instance (async by default since 4.12) | `--reinstall`, `--skip-flow-activation`, `--demoData`, `--open-browser`, `--info`, `--auth` |
| `now-sdk dependencies [sysIds..]` | Download dependencies and type definitions, or register new ones | `--type-defs-only`, `--fluent-only`, `--add`, `--scope` |
| `now-sdk transform` | Convert instance or local XML records into Fluent source | `--from`, `--table`, `--timeout`, `--format` |
| `now-sdk download <directory>` | Download application metadata | `--incremental`, `--timeout` |
| `now-sdk clean [source]` | Clean build output | |
| `now-sdk pack [source]` | Zip a built app into an installable artifact | `--skip-package-inventory` |
| `now-sdk explain [topic]` | Installed SDK documentation | `--list`, `--peek`, `--format raw` |
| `now-sdk query <table>` | Read-only live instance query | see section 2 |
| `now-sdk cicd <command>` | Instance CI/CD (`sn_cicd`, 4.10+): `install`, `publish`, `rollback`, `test run\|watch\|result\|logs`, `testsuite run\|watch\|result` | run `now-sdk cicd <command> --help` |
| `now-sdk move` | Hidden: move existing records into the app (`--ids`) | not in `--help` output; confirm with `now-sdk move --help` |
| `now-sdk run [script]` | Hidden: run a named script from `now.config.json` `scripts` | not in `--help` output; confirm with `now-sdk run --help` |

For CI pipelines, prefer OAuth `client_credentials` or `SN_SDK_*` environment variables over stored aliases (topic `ci-integration`). Basic auth may prompt for an MFA code (4.13+). On Windows, credentials stored before SDK 4.3 must be re-added.

## 5. Safety and approval

| Operation class | Examples | Approval rule |
|---|---|---|
| Local read-only | `--help`, `--version`, `explain` | May run when relevant. |
| Instance read-only | Bounded `query`, `auth --list`, `install --info`, `cicd … result\|logs` | May run when the target and authorization are clear; apply section 3. |
| Local workspace mutation | `init`, `download`, `dependencies`, `transform`, `clean`, `pack`, `build`, `run` | Requires an explicit user request for the task. |
| Instance mutation | `install`, `move`, `cicd install\|publish\|rollback\|test run\|testsuite run` | Requires explicit target-instance confirmation and user approval immediately before execution. |
| Destructive or credential operations | `install --reinstall`, `auth --add\|--delete\|--use`, `auth --print` | Requires explicit approval for the exact action. |

Additional NowDev rules:

- Never request, echo, log, or route passwords, tokens, or other secrets through chat or model-mediated terminal input. Interactive credential entry happens in a terminal the user controls.
- `auth --print` outputs a live credential. Run it only when the user asks for a header or token, never paste its output into chat or files, and prefer the extension's "Copy Auth Header" command, which copies to the clipboard without displaying the value.
- Never delete a `Table()`, `BusinessRule()`, or `Record()` definition, or add `Now.del()`, without confirming with the user first — the deletion propagates to the instance through `keys.ts` on the next install.
- When running as a subagent without a way to ask the user, return an **Approval Required** block (operation, target instance, impact) to the caller instead of running a gated operation.

## 6. Troubleshooting

- **Command not recognized** — a resolution problem; see section 2.
- **Recognized, but fails, times out, or returns an auth/connection error** — connectivity, proxy/TLS, or credentials, not the SDK version. Check the alias with `now-sdk auth --list` and ask the user to confirm network access. `explain` is offline, so it never fails for network reasons.
- **Flag not recognized** — run `now-sdk --version` and tell the user the installed SDK may be too old. Do not trust minimum-version numbers from memory; verify with `--help`.

Report failures with one category — command resolution, unsupported command/flag, authentication, authorization, connectivity/TLS/proxy, invalid query or schema, timeout, output parse failure, or partial/truncated result — plus the failed operation and sanitized error text, never credentials, tokens, cookies, or sensitive row data.