---
title: "overlane bot register"
description: "Register a bot that can take tasks and answer approvals; the signing secret is shown once"
---

> 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 bot register

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

Registers a bot with a name, a platform (chatgpt-dots, grok-bot, slack, teams, generic) and an https webhook address. Overlane sends task assignments, approval questions and messages to the webhook as signed events. The signing secret is shown once, here and when the key is rotated. Registering a bot needs a role that manages policy and is in the bots autonomy class: an agent needs an independent approval first.

## Usage

```sh
overlane bot register --name NAME --platform PLATFORM --webhook-url URL [--service URL] [--team TENANT_ID] [--dry-run]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--name` | string | yes |  | What the bot is called |
| `--platform` | one of `chatgpt-dots`, `grok-bot`, `slack`, `teams`, `generic` | yes |  | chatgpt-dots, grok-bot, slack, teams, generic |
| `--webhook-url` | string | yes |  | The https address that receives the signed events |
| `--service` | string | no |  | The service address (default: OVERLANE_SERVICE_URL, then the project's binding, then the hosted service) |
| `--team` | string | no |  | The team (tenant) to act on (default: the one your token belongs to) |
| `--dry-run` | boolean | no |  | Print the requests and file changes this command would make, then stop. Needs no credentials. |

## Examples

```sh
overlane bot register --name "Release helper" --platform slack --webhook-url https://bots.example.com/overlane
overlane bot register --name Dots --platform chatgpt-dots --webhook-url https://example.com/hook --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 bot register`.

## 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": {
        "bot": {
          "type": "object",
          "properties": {
            "botId": {
              "type": "string",
              "pattern": "^bot_[A-Za-z0-9]{8,32}$",
              "description": "bot identifier"
            },
            "tenantId": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
              "description": "tenant identifier"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "platform": {
              "type": "string",
              "enum": [
                "chatgpt-dots",
                "grok-bot",
                "slack",
                "teams",
                "generic"
              ]
            },
            "webhookUrl": {
              "type": "string",
              "maxLength": 2000
            },
            "keyVersion": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            },
            "createdBy": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            },
            "createdAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "revokedAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            }
          },
          "required": [
            "botId",
            "tenantId",
            "name",
            "platform",
            "webhookUrl",
            "keyVersion",
            "createdBy",
            "createdAt"
          ],
          "additionalProperties": false
        },
        "signingSecret": {
          "type": "string",
          "minLength": 20
        }
      },
      "required": [
        "bot",
        "signingSecret"
      ],
      "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/bot-register/index.mdx