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

# Agent-first onboarding

> Let an AI agent create, configure, test, and hand off a temporary SiteGPT chatbot before the user has a SiteGPT account.

Agent-first onboarding is for people who want to try SiteGPT before creating an
account. An AI agent can start with only a website URL, create a temporary
chatbot, configure it with normal CLI commands, test it, and then share one
onboarding URL where the human can preview and claim the chatbot.

Agents that support Auth.md-style discovery can also start from:

```text theme={null}
https://sitegpt.ai/auth.md
```

That file points agents to the same anonymous registration flow. Use the CLI
commands on this page when the agent can run terminal commands.

Use this flow when the user says something like:

```text theme={null}
Try SiteGPT for https://example.com and show me a working chatbot.
```

If the user already has a SiteGPT account and wants changes inside that account,
use [Install and log in](/cli/install-login), then run normal chatbot commands.

## How it works

<Steps>
  <Step title="Start from a website URL">
    ```bash theme={null}
    sitegpt onboarding start https://example.com --json
    ```

    This command is public. It does not require login.
  </Step>

  <Step title="Capture the returned setup details">
    The response includes:

    | Field                      | Use                                              |
    | -------------------------- | ------------------------------------------------ |
    | `data.workspace.id`        | The onboarding workspace ID.                     |
    | `data.workspace.chatbotId` | The temporary chatbot ID.                        |
    | `data.apiToken`            | A temporary token scoped only to this chatbot.   |
    | `data.onboardingUrl`       | The single preview and claim page for the human. |
    | `data.statusUrl`           | API status URL for automation.                   |
  </Step>

  <Step title="Use the temporary token for setup">
    Use the returned token as `SITEGPT_API_TOKEN` for all setup commands:

    ```bash theme={null}
    SITEGPT_API_TOKEN=<temporary-token> sitegpt onboarding status <workspace-id> --json
    SITEGPT_API_TOKEN=<temporary-token> sitegpt knowledge sitemap add --chatbot <chatbot-id> https://example.com/sitemap.xml --json
    ```

    You can also export it in the shell where the agent is working:

    ```bash theme={null}
    export SITEGPT_API_TOKEN=<temporary-token>
    ```
  </Step>

  <Step title="Configure and test the chatbot">
    Add knowledge, persona, instructions, settings, starters, followups, and
    icons with the normal CLI command groups.

    Before sharing the onboarding URL, check setup progress:

    ```bash theme={null}
    sitegpt onboarding status <workspace-id> --json
    ```
  </Step>

  <Step title="Share the onboarding URL">
    Give the human `data.onboardingUrl` after the chatbot is useful. The page
    lets them test the chatbot and claim it.
  </Step>
</Steps>

## Setup checklist

`sitegpt onboarding status --json` includes `data.setupChecklist`.

Use this as the agent's progress signal before sharing the onboarding URL:

| State     | Meaning                                                       |
| --------- | ------------------------------------------------------------- |
| `DONE`    | The setup item is present.                                    |
| `PENDING` | The agent should configure this before handoff when possible. |
| `WARNING` | The item exists but may need review.                          |
| `UNKNOWN` | SiteGPT could not confirm the item; inspect manually.         |

Checklist items cover knowledge, persona, instructions, conversation starters,
follow-up prompts, and brand styling.

## Claiming the chatbot

After the human tests the chatbot, ask whether they want to claim it. If yes,
ask for:

| Field    | Values                                         |
| -------- | ---------------------------------------------- |
| Email    | The email that should own the SiteGPT account. |
| Plan     | `STARTER`, `GROWTH`, or `SCALE`.               |
| Interval | `MONTH` or `YEAR`.                             |

Then run:

```bash theme={null}
SITEGPT_API_TOKEN=<temporary-token> sitegpt onboarding claim <workspace-id> \
  --email user@example.com \
  --plan GROWTH \
  --interval MONTH \
  --json
```

For new customers, the response returns a checkout URL. The checkout opens on
SiteGPT's pricing page. After the free trial starts, SiteGPT transfers the
temporary chatbot into the claimed email's account.

If the email already has an active SiteGPT subscription, the user should open
the onboarding URL while signed in and claim from the page. SiteGPT will attach
the chatbot directly when the account has an available chatbot slot.

## Temporary token behavior

The temporary token is scoped only to the onboarding chatbot.

When the chatbot is claimed, SiteGPT transfers that token to the claimed user
instead of revoking it. The token remains scoped only to that chatbot and keeps
its original expiry, so the AI agent can continue final setup after claim.

Temporary onboarding tokens expire automatically. Deleted onboarding workspaces revoke the temporary token immediately.

## Delete an unclaimed workspace

If the setup is wrong or the user does not want the chatbot:

```bash theme={null}
SITEGPT_API_TOKEN=<temporary-token> sitegpt onboarding delete <workspace-id> --yes
```

This deletes the unclaimed temporary chatbot and revokes the temporary token.