---
title: "overlane run next"
description: "One step of the agent loop: finish the held task, open its pull request, claim the next one"
---

> 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 run next

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

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

```sh
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

```sh
overlane run next
overlane run next --executor codex
overlane run next --dry-run
```

## Behavior

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

```json
{
  "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](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/run-next/index.mdx