state

Fleet ownership + execution log views across every manifest.

The state command is a fleet-level view over two indexes: .sn-customizations/ (who owns which sys_id) and .sn-executions/ (append-only log of every step result). It answers questions like "which manifests touched sys_script?", "when was this record last modified?", and "what drifted since yesterday's run?". No instance calls for list / show / log; validate and rebuild read local .sn-results/ data.

sn state list [--table <t>] [--scope <s>] [--manifest <p>] [--json]

List customizations from the fleet index, optionally filtered.

Flags

Flag	Default	Description
--table <t>	—	Filter by ServiceNow table.
--scope <s>	—	Filter by application scope.
--manifest <p>	—	Substring match on owner manifest path.
--json	—	Emit `{version, entries}` JSON.

Examples

sn state list --table sys_script

sys_script (2)

abc123... global manifests/payroll/manifest.ts#create-br [dorian]

def456... x_acme_hr manifests/hr/manifest.ts#create-br [alex]

sn state show <sys_id> [--json]

Show the index entry plus full touch timeline for one sys_id.

Arguments

Name	Required	Description
sys_id	Yes	The record sys_id.

Flags

Flag	Default	Description
--json	—	Emit JSON.

Examples

sn state show abc123def456...

sn state log [--since <iso>] [--manifest <p>] [--table <t>] [--run <id>] [--sys-id <id>] [--include-archive] [--follow] [--json]

Tail or query the execution log.

Flags

Flag	Default	Description
--since <iso>	—	Only entries with ts ≥ iso.
--manifest <p>	—	Substring match on manifest path.
--table <t>	—	Exact table match.
--run <id>	—	Exact runId match.
--sys-id <id>	—	Exact sysId match.
--include-archive	—	Also read rotated partitions from `.sn-archive/executions-YYYY-MM.jsonl.gz`.
--follow	—	Tail the live log (exits on SIGINT/SIGTERM).
--json	—	NDJSON when `--follow`; pretty array on one-shot.

Examples

sn state log --since 2026-04-17T00:00:00Z --manifest payroll

sn state archive --before <YYYY-MM | YYYY-MM-DD | ISO> [--dry-run] [--json]
                 sn state archive --manifest <p> [--reason <text>] [--dry-run] [--json]

Rotate execution log partitions older than a cutoff (`--before`), or freeze a retired manifest's ownership entries (`--manifest`).

Flags

Flag	Default	Description
--before <date>	—	Cutoff for log rotation. `YYYY-MM` bumps to first-of-next-month UTC; `YYYY-MM-DD` → midnight UTC; full ISO used as-is.
--manifest <p>	—	Manifest path to freeze (mutually exclusive with `--before`).
--reason <text>	—	Optional freeze reason, recorded in the snapshot.
--dry-run	—	Preview the plan without writing.
--json	—	Emit structured output.

Examples

sn state archive --before 2026-03

sn state archive --manifest manifests/legacy-approval --reason "Replaced by payroll v2"

sn state rebuild [--incremental] [--manifest <p>]
sn state validate [--table <t>] [--manifest <p>] [--batch-size <n>] [--json]

`rebuild` regenerates the ownership index from `.sn-results/`. `validate` buckets every indexed record into clean / modified / missing / unreachable.

Flags

Flag	Default	Description
--incremental	—	Rebuild only refresh the given manifest (requires `--manifest`).
--manifest <p>	—	Scope rebuild/validate to one manifest.
--table <t>	—	Scope validate to one table.
--batch-size <n>	—	Batch size for validate (parsed for compat).
--json	—	Emit `{clean, modified, missing, unreachable}` JSON.

Examples

sn state rebuild --incremental --manifest manifests/payroll

sn state validate --manifest manifests/payroll

state log --follow uses watchFile (500ms polling). On NFS/SMB mounts prefer an external watcher — watchFile can drop events.