> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# gavai patch

> Apply RFC 6902 JSON Patch operations to a page draft.

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

export const BrandCard = ({eyebrow, title, href, icon, badge, cta, featured = false, horizontal = false, children}) => {
  const classes = ["gv-card", featured && "gv-card--featured", horizontal && "gv-card--horizontal"].filter(Boolean).join(" ");
  const inner = <>
      {icon && <span className="gv-card__icon" aria-hidden="true">
          <Icon icon={icon} />
        </span>}
      <div className="gv-card__main">
        {(eyebrow || badge) && <div className="gv-card__meta">
            {eyebrow && <Eyebrow label={eyebrow} tone="muted" />}
            {badge && <span className="gv-card__badge">{badge}</span>}
          </div>}
        <h3 className="gv-card__title">{title}</h3>
        {children && <div className="gv-card__body">{children}</div>}
        {cta && <span className="gv-card__cta">
            {cta}
            <svg className="gv-card__cta-arrow" viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <line x1="7" y1="17" x2="17" y2="7" />
              <polyline points="7 7 17 7 17 17" />
            </svg>
          </span>}
      </div>
    </>;
  return href ? <a className={classes} href={href}>
      {inner}
    </a> : <div className={classes}>{inner}</div>;
};

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="CLI" />

Read a JSON Patch operations array from a file and apply it to the current draft of a page in the active workspace. The patch creates a new draft version; the live site is unchanged until you run `gavai publish`. This guide covers the synopsis, the input file format, and the exit codes you should branch on in CI.

## Synopsis

```bash theme={null}
gavai patch <id> --ops <patches.json>
```

## Arguments

<DefList>
  <Def term="<id>" type="string" required>
    The page ID. Format: `page_01HXR...`.
  </Def>
</DefList>

## Flags

<DefList>
  <Def term="--ops" type="path" required>
    Path to a file containing a JSON array of RFC 6902 operations.
  </Def>
</DefList>

<Note>
  Run `gavai patch --help` for the authoritative flag list. The CLI is the source of truth.
</Note>

## Behavior

The command reads the file you pass to `--ops`, validates it as a JSON Patch array, and sends `PATCH /v1/workspaces/{slug}/pages/{id}` with the operations as the request body. Each operation follows [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) — an `op` (e.g. `replace`, `add`, `remove`), a JSON Pointer `path` into the page document, and (where applicable) a `value`.

The server applies operations atomically. If any operation fails — invalid pointer, schema violation, conflict with a concurrent edit — the entire patch is rejected with exit code `6` and the draft is left unchanged.

## Example

A `patches.json` that retitles a hero headline and toggles a feature flag:

```json patches.json theme={null}
[
  {
    "op": "replace",
    "path": "/tree/children/0/props/headline",
    "value": "Welcome to Acme"
  },
  {
    "op": "add",
    "path": "/metadata/flags/show_pricing",
    "value": true
  }
]
```

Apply it:

```bash theme={null}
gavai patch page_01HXR8K2M4 --ops patches.json
```

<Tip>
  Run `gavai get <id> > page.json` first to inspect the block tree and compute the right JSON Pointer paths before writing the ops file. Pointer mistakes are the most common cause of a rejected patch.
</Tip>

## Exit codes

<ErrorTable
  errors={[
{ code: "0", cause: "Patch applied. New draft version created.", fix: "—" },
{ code: "2", cause: "Invalid arguments or malformed `--ops` file.", fix: "Validate the JSON. Confirm every entry has `op`, `path`, and (where required) `value`." },
{ code: "3", cause: "Not authenticated.", fix: "Run `gavai login`." },
{ code: "4", cause: "Insufficient scope for this page.", fix: "Mint a token with `pages:write`." },
{ code: "5", cause: "Page not found in the active workspace.", fix: "Confirm the ID and the workspace with `gavai whoami`." },
{ code: "6", cause: "Pointer invalid, schema violated, or concurrent edit.", fix: "Re-fetch with `gavai get`, recompute pointers, re-apply." },
{ code: "7", cause: "Network or API server error.", fix: "Retry with backoff." },
]}
/>

See [CLI overview — exit codes](/cli/overview#exit-codes) for the full table.

<BrandCard eyebrow="NEXT" title="gavai publish" href="/cli/commands/publish">
  Promote the patched draft to live once you're satisfied with the changes.
</BrandCard>