docs(insta): document template upgrade and rollback

CA
5d ago
+2-0

What

Documents insta template upgrade and insta template rollback in the agent-facing CLI reference.

Paired with insta-cli #367, which is where the commands live.

How

Two rows after the template deploy row, written the way the rest of that file is: what the
command does, what it prints, what it asks, and what it answers when it refuses.

The parts an agent gets wrong without being told:

  • the commands address a service name, not a deployment id
  • an upgrade rewrites every setting the new version declares, which is the image, the start
    command, the port, always-on, public access, the volume and its mount path, plus the variables
  • on a storage service a public access change reaches that bucket on every branch that has a
    copy, so it is not a per-service setting the way the others are
  • --json alone prints the plan and does not upgrade, while --json --yes upgrades
  • a rollback is one step, and it does not restore data

template_no_step_back has two causes, never upgraded and already rolled back, so the row says
both. An agent told only the first reads the second as a contradiction and retries.

Verify

  • python3 .github/check-markdown.py passes, which is what CI runs: fences pair and every table
    row matches its header
  • the unresolved-conflict-marker grep passes
  • every flag named here exists in insta-cli #367

🤖 Generated with Claude Code

Summary by cubic

Documents insta template upgrade and insta template rollback in the agent-facing CLI reference, paired with the insta-cli change that implements both commands.

The rows cover the behavior that isn't obvious from the command syntax:

  • Both address a service name, not a deployment id.
  • An upgrade rewrites every setting the new version declares, can create a newly declared service (new billed service) or leave a dropped one running until removed by hand.
  • --json alone prints the plan and does not upgrade; --json --yes upgrades.
  • A rollback is one step, never restores data, and template_no_step_back has two causes (never upgraded, or already rolled back).