Skip to content

KV Lifecycle: A 5-Minute Tour

A visual walkthrough of managing rules in NATS KV — generate, push, list, pull, delete — using shunt dev so you don't need a separate NATS install.

For a deeper hands-on tutorial covering rule semantics, conditions, templating, and KV enrichment, see the Local Testing Tutorial.

Prerequisites

The shunt binary on your PATH. From the repo root:

task build:shunt
export PATH="$(pwd)/bin:$PATH"

1. Start an embedded NATS server

In one terminal:

shunt dev

shunt dev spins up an embedded NATS server on port 14222, auto-provisions the rules KV bucket, and seeds a few demo rules so the engine has something to evaluate. It's intended for local exploration — not production.

In a second terminal, point the CLI at the dev server:

export SHUNT_NATS_URL="nats://localhost:14222"

2. Generate a rule from a template

shunt new -t nats-basic -o rule.yaml

Templates are starting points. Run shunt new -t list to see what's available, or shunt new -i for the interactive builder.

3. Push the rule into KV

shunt kv push rule.yaml

Shunt picks up the new rule immediately via KV Watch — no server restart needed. The KV key is derived from the file path: rule.yaml becomes the key rule.

4. List rules in KV

shunt kv list

You'll see rule alongside any rules shunt dev seeded on startup (e.g. router.basic, http.webhooks). The video uses --rules-dir pointed at an empty directory to keep the listing focused — by default you'll have a few extras.

5. Pull a rule back out

shunt kv pull rule -f yaml

Useful for inspecting what's actually stored in KV, or pulling rules into Git for version control. -f json is also supported.

6. Delete the rule

shunt kv delete rule --force

Shunt detects the deletion and tears down the rule's subscriptions automatically. --force skips the confirmation prompt.

Next steps

  • Local Testing Tutorial — graduated, hands-on lessons covering rule conditions, templating, wildcards, time-based logic, and the HTTP gateway.
  • Core Concepts — the rule syntax in depth.
  • KV Enrichment — using NATS KV to enrich messages at evaluation time.
  • Deployment — running Shunt in production with externally managed NATS.