Getting Started

Table of contents

  1. Installation
  2. First-time setup
    1. Step 1 — Open your project folder
    2. Step 2 — Initialize the workspace
    3. Step 3 — Configure authentication
    4. Step 4 — Validate authentication
    5. Step 5 — Pull records
    6. Step 6 — Edit and push
  3. Keyboard shortcuts
  4. Next steps

Installation

Install sn-sync from the VS Code Marketplace:

  1. Open VS Code
  2. Open the Extensions panel (Cmd+Shift+X on macOS, Ctrl+Shift+X on Windows/Linux)
  3. Search for sn-sync
  4. Click Install

Alternatively, install from the terminal:

code --install-extension AlexAlvarez.sn-sync

First-time setup

Follow these steps once per workspace (project folder).

Step 1 — Open your project folder

Open the folder where you want ServiceNow files to be saved (File → Open Folder).

Step 2 — Initialize the workspace

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), type sn: init, and run it.

This creates a .snsyncrc file in the workspace root with default sync settings.

When prompted, enter your ServiceNow instance name — the subdomain of your instance URL.

Example: for https://mycompany.service-now.com, the instance name is mycompany.

Step 3 — Configure authentication

Run sn: auth from the Command Palette and choose configure auth.

Select an authentication method:

Method When to use
basic Username + password. Simple setup, good for personal or development instances.
OAuth (PKCE) Token-based. Recommended for shared or production instances.

Follow the prompts. Your credentials are stored securely in VS Code Secret Storage — never written to disk.

Step 4 — Validate authentication

Run sn: auth again and choose validate auth.

sn-sync will make a test call to your instance and confirm the connection works before you start pulling records.

Step 5 — Pull records

Run sn: pull and choose a scope:

Scope What it does
all files Pulls all tables and records configured in .snsyncrc
current file Re-pulls the record for the currently open file
table Pulls all records from a single selected table
by sys_id Pulls a specific record by its ServiceNow sys_id

Files are saved under your workspace root, organised by table.

Step 6 — Edit and push

Edit the pulled files locally. When ready, run sn: push and choose:

Scope What it does
current file Pushes only the file currently open in the editor
all files Pushes all modified files with per-file conflict resolution
report Generates a Markdown report of pending changes (no push performed)

Keyboard shortcuts

Action Shortcut (all platforms)
Pull current (re-pull active file) Ctrl+Shift+C Ctrl+Shift+Down
Push current (re-push active file) Ctrl+Shift+C Ctrl+Shift+Up
Open active file in instance Ctrl+Shift+O

These use the same key combination on all platforms (including macOS) — Ctrl here is the physical Ctrl key, not Cmd. The scope-selector commands (sn: pull, sn: push) have no default shortcut; use the Command Palette.

You can override or remove these in VS Code Keyboard Shortcuts (Cmd+K Cmd+S).

Next steps