> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawup.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# onboard

> Run plugin onboard hooks for interactive first-time setup

<Warning>
  Plugin hooks are **experimental** and subject to change. The API may evolve in future releases.
</Warning>

Runs onboard hooks interactively. Onboard hooks are scripts (defined at the swarm, identity, or plugin level) that handle first-time setup tasks like creating webhook endpoints, generating signing secrets, or configuring external services.

For a comprehensive guide to all hook types, see [Lifecycle Hooks](/guides/hooks).

## Usage

```bash theme={null}
clawup onboard [options]
```

## Options

| Option              | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `--env-file <path>` | Path to `.env` file (defaults to `.env` in project root) |

## What It Does

1. Loads `clawup.yaml` and resolves agent identities
2. Loads `.env` and resolves secrets
3. Runs each plugin's `onboard` hook (if defined) with the resolved context
4. Hooks can prompt for input, call external APIs, and display follow-up instructions

## When to Use

Run `clawup onboard` after your first `clawup deploy` if any plugins have onboard hooks that need interactive setup. For example, a plugin might need to register webhook URLs that are only available after deployment.

You can also pass `--onboard` to `clawup deploy` to run onboard hooks during the deploy phase.

## Plugin Manifest Example

Onboard hooks are defined in a plugin's manifest file. Here's a minimal example:

```yaml theme={null}
hooks:
  onboard:
    description: "Register webhook with external service"
    inputs:
      configToken:
        envVar: MY_CONFIG_TOKEN
        prompt: "Enter your config token"
        instructions: "Generate at https://example.com/settings/tokens"
        validator: "tok_"
    script: |
      WEBHOOK_URL="https://$(hostname).tail1234.ts.net/hooks/my-plugin"
      curl -s -X POST https://api.example.com/webhooks \
        -H "Authorization: Bearer $MY_CONFIG_TOKEN" \
        -d "{\"url\": \"$WEBHOOK_URL\"}"
      echo "Webhook registered at $WEBHOOK_URL"
    runOnce: true
```

When `runOnce` is `true`, the hook is skipped if all required secrets for the plugin are already configured.

## Examples

```bash theme={null}
# Run onboard hooks
clawup onboard

# Run with custom .env location
clawup onboard --env-file /path/to/.env
```

<Note>
  Onboard hooks can be defined at the swarm level (`clawup.yaml`), identity level (`identity.yaml`), or plugin level. Not all levels require onboard hooks — only those that need interactive first-time configuration. See the [Lifecycle Hooks guide](/guides/hooks#onboard-hooks) for details on writing onboard hooks.
</Note>