Getting oriented — required before other work
Condition: the project root contains now.config.json (same role as package.json for an npm project — walk up from cwd to find it, and treat each one found as a distinct fluent project, not a nested copy of another).
Action: run the orientation below for that project. Docs are versioned together with the @servicenow/sdk version installed per-project — orientation done for one project does NOT transfer to another. Re-run this for every distinct now.config.json you touch, even within the same session.
Step 1 — run all three:
Both lists are required — fluent-language is not a subset of quickstart.
Step 2 — read every topic returned by both --list calls in full, plus keys-file by name (not reliably tagged into either list). Read each topic once even if reachable multiple ways. Do not skip any. Do not --peek first — they are already pre-scoped, so peeking first is redundant overhead, not a safety step:
Step 3 — treat this content as required working knowledge for the rest of this project's session. Do not re-derive fluent conventions from guesswork once they've been covered here — this includes safety-critical rules such as never deleting a Table()/BusinessRule()/Record() definition from a .now.ts file without confirming with the user first (deletion may need to propagate as an upgrade-time delete via keys.ts, which the code alone can't reveal). If uncertain later, re-run --peek on the specific topic rather than relying on memory:
Rule: before using any subcommand for the first time, run npx @servicenow/sdk <subcommand> --help first — --help at the top level lists subcommands but not their flags. Never guess flag names.
SDK Documentation (explain)
Rule: never open a full topic without --peek first, except quickstart topics (covered in Getting oriented above — read those directly, no peek needed).
explain (including --peek and --list) is read-only documentation lookup with no side effects. Do not ask the user for confirmation before running it — peek and read relevant topics automatically as part of the task.
To show all available topics with their related tags:
To search for topics, showing the descriptions of all matches:
To preview a topic:
Once you are certain you want to read the full topic, open it like this:
What to search for
- Metadata types —
BusinessRule,Table,Acl,Flow,ScriptInclude,ClientScript,UiPolicy - Skills — workflows like
build,transform,deploy,auth - Conventions —
naming,structure,scoping,file-layout
For any task — always start here
Step order: search (--list) → peek (--peek) → read full topic. Repeat for every relevant topic — fluent behavior is often split across multiple topics, so stopping at one risks an incomplete picture.
- Search:
npx @servicenow/sdk explain <search-term> --list --format=raw - Peek:
npx @servicenow/sdk explain <topic> --peek --format=raw - Read (only if peek confirms relevance):
npx @servicenow/sdk explain <topic> --format=raw
If explain fails
explainis only available in@servicenow/sdkversions >=4.6.0— upgrade if the command is not found.No documentation found for "<topic>"— wrong topic name, try--listNo match for "<topic>"— use a different search term
Live Instance Queries (query)
query is only available in @servicenow/sdk versions >= 4.8.0. If the command is not found, check the installed version and inform the user to upgrade.
Before writing any query call, run the subcommand help to get the exact flag names — the top-level --help does not show subcommand flags, so do not guess:
Then read the full usage guide and encoded query format guide for deeper context:
The required flag for filtering is -q / --query. Every query call needs it along with the table name.
Always include the -o json flag to output machine-readable json.
Rule: query output is live instance data, not documentation. Do not retain it as project knowledge the way quickstart topics are retained — treat it as scoped to the current task only.
