Change what's live

An act changes what visitors see without a deploy: pause, resume, promote, retire or revert. This guide shows each one, how to run it safely, and the code edit that keeps it in place. Routing settings change with set, in Routing settings; a period when tracking broke is recorded with gap, in Track conversions.

An act reaches every visitor within about 2 minutes, with no deploy and no review. Run it with --dry-run first.

Run an act safely

Every act takes three options:

--dry-run writes nothing. It prints what the act would change, before and after, the scorecards it would open or close, and its warnings.
--expect <n> refuses the act if anything changed on the site since you read it. For n, give what the dry run’s first line prints after registry version.
--idempotency-key <key> makes a retry safe: the same key returns the first act’s result instead of acting twice. Pass your own whenever you might retry, since the command otherwise makes a new one each time.

So show the person the dry run, then act with --expect:

$ routingcat promote home/hero:family --dry-run
promote · dry run: nothing written · registry version 19
would change
  home/hero  default: plan-week → family
  era boundary  home
…
command   routingcat promote home/hero:family

Here npx routingcat promote home/hero:family --expect 19 promotes only if nothing changed in between. Each act runs as you, with your sign-in, and --json returns every field of its result.

Pause or resume a variant

npx routingcat pause home/hero:studio stops serving a variant; name several to pause them at once.

Visitors already shown it get the slot’s default for the rest of their visit.
Its scorecards close.
A pause holds through every deploy until you resume, since your templates can’t express it. An edit to a paused variant, stamped by push and deployed, records its new version and keeps it paused.
A slot left with one live variant stops being routed until it has two again.
On Hobby, a pause frees room for a variant the plan holds, which then goes live; a resume past the 10 live variants across your sites holds the variant it resumes.
A slot’s default can’t be paused:

$ routingcat pause home/hero:plan-week
✗ home/hero:plan-week is the default of home/hero, and every slot needs its default, so it cannot be paused or retired. Promote another variant first.  (A8, exit 1)

npx routingcat resume home/hero:studio serves a paused or retired variant again, and opens a fresh scorecard against its slot’s default. The scorecard its pause closed stays closed.

Promote a variant

npx routingcat promote home/hero:oneclick makes a variant its slot’s default, so the control sees it from then on.

The measured gain so far is kept. The era boundary line marks where measurement starts again, against the new defaults.
Scorecards stay open, since what each one compares doesn’t change.
Several slots of one page can change in one act, with one variant per slot. Only a live variant can be promoted, including one the plan holds: as its slot’s default, it is never held.

$ routingcat promote home/hero:family
promote · done · op_01m4zbfqr0fa49v710xk3sc2w2 · registry version 20
  home/hero  default: plan-week → family
  publications  pb_01m4zbfqr0fwqttp9y5atppz0f
  era boundary  home (pb_01m4zbfqr0fwqttp9y5atppz0f)

Until your templates make family the default, a change to that slot’s default in them that reaches production replaces the promote: the edit below keeps it.

Retire a variant

npx routingcat retire home/hero:best stops serving a variant for good, keeping its history. Its scorecards close, and a slot’s default can’t be retired. Here, on Hobby at its 10 live variants, on a site whose home/hero default is no longer current:

$ routingcat retire home/hero:current
retire · done · op_01m4zbfqr0fa49v710xk3sc2w2 · registry version 20
  home/hero:current  eligibility: live → retired
  welcome/checklist:tour  held: true → false
  change        ch_01m4zbfqr0fwqttp9y5atppz0f
  publications  pb_01m4zbfqr0fzbb7a7j23jr4e9q · pb_01m4zbfqr0fgq9d4fhwyhfgbd7
  scorecard ev_01m4zbfqr0eddsyqqmq0kgke7y opened: welcome/checklist:tour vs welcome/checklist:steps
  scorecard ev_01kx68ntc0fgnbx7xqtn0wa7xx: window closed
  scorecard ev_01kx68ntc0fz2tfkmdtfzpescs: window closed
  scorecard ev_01ky9xn1r0ebbtkka94kcpe432: window closed

The retire freed room under the plan’s limit, so welcome/checklist:tour, which the plan held, goes live on the welcome page, with a scorecard against its slot’s default, steps.

A retired variant can come back with its history: through resume, revert, or a production deploy whose templates, stamped by push, write its key again or change its content, which the build log reports. A new idea still takes a new key.

Revert a page

npx routingcat revert home returns the page to what it served before its last change: its defaults, its routing settings, which variants are live, and the version each one serves.

Variants it served then come back, retired ones included; the others are paused. Their scorecards close or open to match. On Hobby, those it brings back past the 10 live variants across your sites are held.
It creates no version and changes nothing in your code.
If a default moves, measurement starts again against it, as after a promote.
--to goes back further, to an earlier state of the page: give it the id of a publication, a recorded state of what the page served, from the timeline of npx routingcat status --since.

Use it when a deploy or an act went wrong and the page must be right now; then fix the code at your pace. A page with no earlier state has nothing to revert.

Make your code agree

A production deploy applies only what your templates and routingcat.config.json changed since the previous production deploy, field by field. So an act holds until a deploy changes the same thing, even for an unrelated reason. After each act, edit them to match what’s live:

After	Edit
`promote`	In the slot’s markup, take `hidden` and `data-nosnippet` off the promoted variant, so that search engines can quote it. Give the former default `hidden`, and take off its `style`: a hidden variant with a display style would show without RoutingCat, so `push` refuses it. The edit makes no new version of either variant, since a version leaves out what marks the variant that shows.
`retire`	Delete the variant’s element, so a later edit to it can’t bring it back.
`revert`	Return your templates and config to what is live, often by reverting the commit.
`pause` or `resume`	Nothing: a pause holds until `resume`, whatever your templates say.
`set` on a slot	Write the same value under the slot’s address in the config’s `slots`, if it declares that setting.

Then npx routingcat push completes the markup: commit what it changes, and deploy as usual. npx routingcat plan shows beforehand what the deploy will change.

Find drift

Drift is anywhere what’s live differs from your code. npx routingcat status lists each place, with the code’s value and the live one:

drift     home/hero default: code current, live plan-week

npx routingcat show lists the drift of a page, a slot or a variant, and of everything under it:

$ routingcat show home/hero
home/hero · sl_01kx68ntc0enatwx14ctrzbj6n · default plan-week
  routing  fixed share 0% · personalization on · floor auto · cap auto
  variant  current · live · @v1
  variant  save-time · live · @v1
  variant  plan-week · live · default · @v2
  variant  no-waste · retired · @v1
  variant  family · live · @v1
  drift    default: code current, live plan-week

related   sf_01kx68ntc0e14vzjnaxx9ckq5s · vr_01kx68ntc0e598by33936d659n · vr_01kx68ntc0e1j9x6dma6hjgtym · vr_01kx68ntc0f7w9t6r8p344zkrn · vr_01kx68ntc0esavjfwg7da8675y · vr_01ky9xn1r0ev0rsh3bxh6p44gc   → routingcat show <id>

Here plan-week was promoted, and your templates still make current the default. A routing setting declared in the config’s slots can drift too, and so can a variant’s version or state: a paused variant always appears, since a pause is set with the command and holds until resume, and so does a retired one still in your templates. status --json carries drift on every page, slot and variant, and plan --json lists what would still differ once your templates reach production.