---
title: "overlane rules sync"
description: "Write the project's rules source to AGENTS.md, CLAUDE.md, Cursor, Gemini and the Gemini settings"
---

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

# overlane rules sync

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Reads .overlane/rules.md and writes it into one managed region in each agent's file. Missing files are created, a hand-written file gets the region appended with every existing line kept, and an out-of-date region is updated. A region someone edited by hand is never overwritten silently: sync refuses with exit 5 and writes nothing, until the change is moved into the source or --overwrite-edits is given, which first prints the lines it replaces. The Gemini settings only gain the missing names in context.fileName. A symbolic link in the way is refused. When the project is connected and you are signed in, the same source is also sent to the project, so the rules reach the payload of every task; a project that is not connected, a sign-in that is missing or an unreachable service only says so and never fails the sync. --no-upload keeps everything local.

## Usage

```sh
overlane rules sync [--overwrite-edits] [--no-upload] [--dry-run]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--overwrite-edits` | boolean | no |  | Replace a region that was edited by hand (prints what it replaces first) |
| `--no-upload` | boolean | no |  | Do not send the rules to the connected project |
| `--dry-run` | boolean | no |  | Print the requests and file changes this command would make, then stop. Needs no credentials. |

## Examples

```sh
overlane rules sync
overlane rules sync --dry-run
overlane rules sync --overwrite-edits
overlane rules sync --no-upload
```

## Behavior

- Effect: `write` (changes local or hosted state).
- Needs credentials: no. Uses the network: no.
- Supports `--dry-run`: yes. Accepts `--force`: no.
- Machine-readable description: `overlane schema rules sync`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "revision": {
          "type": [
            "string",
            "null"
          ]
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "create",
                  "append",
                  "replace",
                  "none",
                  "refuse",
                  "force_replace"
                ]
              },
              "reason": {
                "type": "string"
              },
              "replaces": {
                "type": "object",
                "properties": {
                  "lines": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  "firstLines": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "lines",
                  "firstLines"
                ],
                "additionalProperties": false
              },
              "written": {
                "type": "boolean"
              }
            },
            "required": [
              "id",
              "path",
              "action",
              "reason",
              "written"
            ],
            "additionalProperties": {}
          }
        },
        "written": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "blocked": {
          "type": "boolean"
        },
        "upload": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "const": "uploaded"
                },
                "revision": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "changed": {
                  "type": "boolean"
                }
              },
              "required": [
                "status",
                "revision",
                "changed"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "const": "skipped"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [
                "status",
                "reason"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "const": "failed"
                },
                "reason": {
                  "type": "string"
                }
              },
              "required": [
                "status",
                "reason"
              ],
              "additionalProperties": false
            }
          ]
        }
      },
      "required": [
        "revision",
        "steps",
        "written",
        "blocked"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "dryRun": {
          "type": "boolean",
          "const": true
        },
        "service": {
          "type": "string"
        },
        "requests": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "method": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "body": {},
              "note": {
                "type": "string"
              }
            },
            "required": [
              "method",
              "path"
            ],
            "additionalProperties": false
          }
        },
        "commands": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "writes": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "action": {
                "type": "string",
                "enum": [
                  "write",
                  "append",
                  "delete"
                ]
              },
              "description": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "action",
              "description"
            ],
            "additionalProperties": false
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "dryRun",
        "requests",
        "commands",
        "writes",
        "notes"
      ],
      "additionalProperties": false
    }
  ]
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/rules-sync/index.mdx