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
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
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 --yesBehavior
- 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.
{
"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 for the status the process returns.