Skip to main content

Plan and apply

Every mutation worth confirming is worth confirming against the state it will actually run on. vagaris plan asks the server what a change would do and prints the answer; vagaris apply performs it, and refuses if anything the plan depended on has changed since.

That refusal is the point. Between the moment you read a preview and the moment you apply it, another operator, an agent, or a reconciler can write to the same thing. Applying anyway would apply a change computed against a world that no longer exists.

Preview a change​

vagaris plan --company-id acme --namespace company --operation update --set seats=5
Plan 6f2c1e70-...
expires 2026-09-08T19:45:00.000Z
state   sha256:9f2a...

  update company/acme#seats
    - 3
    + 5

Apply with:  vagaris apply --company-id acme --token <planToken>

--set is repeatable (--set seats=5 --set name=acme-eu). Values that look like numbers or booleans are sent as numbers and booleans, so a field the server stores as a number is not silently compared as a string.

The preview is derived by the server, not computed by the CLI. The before values come from the current stored record, and nothing in the preview is the instruction that gets applied — the server recomputes the effect at apply time.

Apply it​

vagaris apply --company-id acme --token <planToken>

You are asked to confirm. Pass -y / --yes to skip the prompt.

warning

--yes confirms; it does not authorize. It suppresses the interactive prompt and nothing else. It is never sent to the server — the apply request carries only the plan — and permission is decided server-side on every apply, including on a retry. A plan you are not entitled to apply is refused with or without the flag.

With --json, --yes is required. A script that cannot display a prompt and did not pass --yes has not confirmed anything, and treating "no terminal" as consent would be the wrong default.

When the state has moved​

The state this plan was produced against has changed — someone or something else wrote to it first.
Nothing was applied.

state changed since this plan was produced (plan sha256:9f2a..., live sha256:41bd...); re-plan and
review the new preview before applying

Run `vagaris plan` again and read the NEW preview before applying: the change you reviewed may no
longer be the change that would happen.

The command exits non-zero and nothing is written. Re-run vagaris plan and read the new preview — the change you approved a minute ago may not be the change that would happen now.

A plan is bound only to the fields its operation would write, so an unrelated edit to the same record does not invalidate it. Renaming a company does not stale a plan that only changes seat count.

Repeating an apply is safe​

Each plan carries a server-minted idempotency key. If a request is delivered twice — a flaky connection, a retrying script — the mutation happens once and the second response reports replayed. Reusing a key for a genuinely different plan is refused rather than silently deduplicated, because returning the first result would hide the second operation entirely.

Authorization is still re-checked on a replay. A cached success is not served to an actor whose permission was revoked in between.

Plans expire, and are not transferable​

A plan is valid for 15 minutes and is issued to one actor in one company. Handing your plan token to a colleague does not let them apply it; they produce their own. Both refusals report distinct errors, so an audit trail can tell a race apart from an attempt to use someone else's authority.

What can be planned​

vagaris plan --help

Operations are registered server-side; company.update is available today. Namespaces adopt the contract by contributing four functions — how to read the state a change depends on, how to preview it, who may perform it, and how to execute it — rather than by adding their own endpoint. One apply path means the staleness rule is written once and cannot rot in one namespace while holding in another.

  • Permissions — who may perform an operation
  • Approvals — what happens when an act exceeds an actor's authority
  • Security model — how authority is established and carried