---
title: "overlane connect"
description: "Connect this project (native Overlane, or your GitHub repository): sign in, bind it, register the plugin; --kit also sets up a plan"
---

> 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 connect

{/* 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`. */}

Works in any git project, with no GitHub account: without a GitHub origin the project is a native Overlane project named after the folder (--name renames it). With a github.com origin it binds that repository instead (--provider overlane keeps it native). Detects the installed agents, previews the plan, then (with --yes) signs in through the browser, creates or looks up the project on the service, runs the agents' native plugin commands, writes the no-prompt permission preset and the attribution-off setting into .claude/settings.json and .codex/config.toml (merged into what is there; deny rules are never removed; --no-preset skips it), writes .overlane/state/project.json and records what it added in .overlane/state/owned.json so `overlane disconnect` removes only that. With --kit existing|new it also drafts the plan files, CI and a pull request. Without a terminal it never prompts: pass --yes, or --dry-run to preview.

## Usage

```sh
overlane connect [--service URL] [--marketplace-root DIR] [--agents claude,codex] [--dry-run] [--yes] [--name NAME] [--provider overlane|github] [--no-preset] [--kit existing|new] [--goal TEXT]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--service` | string | no |  | Service address (https); default is the hosted service or OVERLANE_SERVICE_URL |
| `--marketplace-root` | string | no |  | Folder holding the built claude/ and codex/ plugin marketplaces |
| `--agents` | string | no |  | Which agents to set up or check (default: both) |
| `--dry-run` | boolean | no |  | Print the plan, the requests it would send and the files it would write; change nothing. Needs no credentials. |
| `--yes` | boolean | no |  | Apply the plan without asking (required when there is no terminal) |
| `--name` | string | no |  | The project name (default: the GitHub repository name, else this folder's name) |
| `--provider` | one of `overlane`, `github` | no |  | Where the project lives: overlane (native, the default without a GitHub origin) or github (needs a github.com origin) |
| `--no-preset` | boolean | no |  | Skip the no-prompt permission preset and the attribution-off setting for Claude Code and Codex |
| `--kit` | one of `existing`, `new` | no |  | Also set up the project kit: plan files, CI, instruction blocks and one pull request |
| `--goal` | string | no |  | The project's goal; required with --kit new |

## Examples

```sh
overlane connect --dry-run
overlane connect --yes
overlane connect --yes --no-preset
overlane connect --name my-app --yes
overlane connect --provider github --yes
overlane connect --kit new --goal "A rundown service" --yes
overlane connect --kit existing --yes
```

## Behavior

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

## Result

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

```json
{
  "anyOf": [
    {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "project": {
              "type": "object",
              "properties": {
                "provider": {
                  "type": "string",
                  "enum": [
                    "overlane",
                    "github",
                    "gitlab"
                  ]
                },
                "owner": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "root": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "root"
              ],
              "additionalProperties": false
            },
            "serviceUrl": {
              "type": "string"
            },
            "tenantId": {
              "type": "string"
            },
            "projectId": {
              "type": "string"
            },
            "releaseDigest": {
              "type": "string"
            },
            "credentials": {
              "type": "string"
            },
            "agents": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "agent": {
                    "type": "string"
                  },
                  "installed": {
                    "type": "boolean"
                  },
                  "detail": {
                    "type": "string"
                  }
                },
                "required": [
                  "agent",
                  "installed",
                  "detail"
                ],
                "additionalProperties": false
              }
            },
            "applied": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "skipped": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "wrote": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "readiness": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "agent": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "detail": {
                    "type": "string"
                  },
                  "action": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "agent",
                  "state",
                  "detail",
                  "action"
                ],
                "additionalProperties": false
              }
            },
            "cancelled": {
              "type": "boolean"
            }
          },
          "required": [
            "project",
            "serviceUrl",
            "credentials",
            "agents",
            "applied",
            "skipped",
            "wrote",
            "readiness"
          ],
          "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
        }
      ]
    },
    {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "existing",
                "new"
              ]
            },
            "branch": {
              "type": "string"
            },
            "commit": {
              "type": "string"
            },
            "plan": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "milestones": {
                  "type": "number"
                },
                "tasks": {
                  "type": "number"
                }
              },
              "required": [
                "source",
                "milestones",
                "tasks"
              ],
              "additionalProperties": false
            },
            "ci": {
              "type": "string"
            },
            "instructionFiles": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "policy": {
              "type": "object",
              "properties": {
                "buildAheadLimit": {
                  "type": "string"
                }
              },
              "required": [
                "buildAheadLimit"
              ],
              "additionalProperties": false
            },
            "sync": {
              "type": "object",
              "properties": {
                "created": {
                  "type": "number"
                },
                "updated": {
                  "type": "number"
                },
                "unchanged": {
                  "type": "number"
                },
                "deferred": {
                  "type": "number"
                }
              },
              "required": [
                "created",
                "updated",
                "unchanged",
                "deferred"
              ],
              "additionalProperties": false
            },
            "pullRequest": {
              "type": [
                "string",
                "null"
              ]
            },
            "manualCommands": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "connect": {
              "type": "object",
              "properties": {
                "project": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string",
                      "enum": [
                        "overlane",
                        "github",
                        "gitlab"
                      ]
                    },
                    "owner": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "root": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "root"
                  ],
                  "additionalProperties": false
                },
                "serviceUrl": {
                  "type": "string"
                },
                "tenantId": {
                  "type": "string"
                },
                "projectId": {
                  "type": "string"
                },
                "releaseDigest": {
                  "type": "string"
                },
                "credentials": {
                  "type": "string"
                },
                "agents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "agent": {
                        "type": "string"
                      },
                      "installed": {
                        "type": "boolean"
                      },
                      "detail": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "agent",
                      "installed",
                      "detail"
                    ],
                    "additionalProperties": false
                  }
                },
                "applied": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "skipped": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "wrote": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "readiness": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "agent": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string"
                      },
                      "detail": {
                        "type": "string"
                      },
                      "action": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    },
                    "required": [
                      "agent",
                      "state",
                      "detail",
                      "action"
                    ],
                    "additionalProperties": false
                  }
                },
                "cancelled": {
                  "type": "boolean"
                }
              },
              "required": [
                "project",
                "serviceUrl",
                "credentials",
                "agents",
                "applied",
                "skipped",
                "wrote",
                "readiness"
              ],
              "additionalProperties": false
            },
            "cancelled": {
              "type": "boolean"
            }
          },
          "required": [
            "mode",
            "branch",
            "plan",
            "ci",
            "instructionFiles",
            "pullRequest",
            "manualCommands"
          ],
          "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/connect/index.mdx