Starts a run when none is active. If this working copy holds a task, runs each of its verification commands on the committed work (a failure stops here and the task stays yours), submits it, records the results as evidence, pushes the branch and opens the pull request; the task closes only when that evidence verifies it. Then claims the next runnable task in one atomic step: two agents running this at once never get the same task, and a task whose dependencies are not verified is never handed out. A stop (policy paused, a budget spent, nothing runnable) exits 6 with the reason in the error code and the exact overlane run end --reason ... as the hint.
Usage
overlane run next [--executor claude-code|codex|gemini-cli|cursor] [--trigger schedule|interactive|event] [--dry-run]Flags
| Flag | Type | Required | Default | Description |
|---|---|---|---|---|
--executor |
one of claude-code, codex, gemini-cli, cursor |
no | Which agent this is (default: detected from the environment) | |
--trigger |
one of schedule, interactive, event |
no | schedule |
What started the run, when this call starts one |
--dry-run |
boolean | no | Print the requests and file changes this command would make, then stop. Needs no credentials. |
Examples
overlane run next
overlane run next --executor codex
overlane run next --dry-runBehavior
- Effect:
write(changes local or hosted state). - Needs credentials: yes. Uses the network: yes.
- Supports
--dry-run: yes. Accepts--force: no. - Machine-readable description:
overlane schema run next.
Result
With --json (the default when stdout is not a terminal) the command prints this JSON Schema’s shape on stdout.
{
"anyOf": [
{
"type": "object",
"properties": {
"runId": {
"type": "string"
},
"started": {
"type": "boolean"
},
"finished": {
"anyOf": [
{
"type": "object",
"properties": {
"taskId": {
"type": "string"
},
"commitSha": {
"type": "string"
},
"branch": {
"type": "string"
},
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string"
},
"exitStatus": {
"type": "number"
}
},
"required": [
"command",
"exitStatus"
],
"additionalProperties": false
}
},
"state": {
"type": "string"
},
"pull": {
"anyOf": [
{
"type": "object",
"properties": {
"state": {
"type": "string",
"enum": [
"opened",
"exists"
]
},
"number": {
"type": "number"
},
"url": {
"type": "string"
}
},
"required": [
"state",
"number",
"url"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"taskId",
"commitSha",
"branch",
"checks",
"state",
"pull"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"claimed": {
"anyOf": [
{
"type": "object",
"properties": {
"taskId": {
"type": "string"
},
"outcome": {
"type": "string"
},
"allowedPaths": {
"type": "array",
"items": {
"type": "string"
}
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "string"
}
},
"verificationCommands": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"planFile": {
"type": "string"
}
},
"required": [
"taskId",
"outcome",
"allowedPaths",
"acceptanceCriteria",
"verificationCommands",
"planFile"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"skipped": {
"type": "array",
"items": {
"type": "object",
"properties": {
"taskId": {
"type": "string"
},
"reason": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"required": [
"taskId",
"reason"
],
"additionalProperties": false
}
},
"stop": {
"type": "object",
"properties": {
"reason": {
"type": "string"
},
"detail": {
"type": "string"
},
"finishWith": {
"type": "string"
}
},
"required": [
"reason",
"detail",
"finishWith"
],
"additionalProperties": false
},
"next": {
"type": "string"
}
},
"required": [
"runId",
"started",
"finished",
"claimed",
"skipped",
"next"
],
"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.