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

# Use SiteGPT CLI with AI agents

> Give a personal AI agent the SiteGPT CLI so it can manage your chatbots safely through scoped profiles and command-line workflows.

SiteGPT can be used by both people and personal AI agents. If your AI assistant can run terminal commands, give it SiteGPT CLI access. If your assistant supports remote MCP servers, connect it to the SiteGPT MCP server instead.

SiteGPT also publishes an agent-readable Auth.md file at `https://sitegpt.ai/auth.md`. Agents can use it to discover the anonymous try-before-signup onboarding flow without needing prior SiteGPT-specific instructions.

<CardGroup cols={2}>
  <Card title="Use MCP Server" icon="plug" href="/cli/mcp-server">
    Best for Claude and other AI apps that support remote MCP with browser-based
    OAuth approval.
  </Card>

  <Card title="Use the CLI" icon="terminal">
    Best for local agents that can run terminal commands and use saved SiteGPT
    profiles.
  </Card>
</CardGroup>

## Choose the right agent flow

| Situation                                                                                  | Best flow                                 |
| ------------------------------------------------------------------------------------------ | ----------------------------------------- |
| The user does not have a SiteGPT account yet and wants to try a chatbot from a website URL | [Agent-first onboarding](/cli/onboarding) |
| The user already has a SiteGPT account, API token, or saved CLI profile                    | Authenticated CLI profile                 |
| The AI app supports remote MCP with browser OAuth                                          | [MCP Server](/cli/mcp-server)             |

Choose the flow before making authentication a blocker. For agent-first onboarding, `PROFILE_NOT_CONFIGURED` simply means no saved CLI profile exists; the agent should continue with `sitegpt onboarding start` instead of asking the user to sign in.

For no-account onboarding, do not ask the user to log in first. Let the agent create a temporary chatbot, configure and test it, then share the onboarding URL for preview and claim.

For existing accounts, the recommended pattern is:

1. Install the CLI on the machine where the agent runs.
2. Log in with a named, scoped profile.
3. Give the agent the SiteGPT CLI skill file.
4. Ask the agent to use `sitegpt ... --json` commands and confirm destructive actions.

## What your agent needs

Your AI agent needs three things:

| Requirement                                         | Why it matters                                                                                                         |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Terminal access                                     | The agent uses the `sitegpt` command to perform actions.                                                               |
| A SiteGPT CLI profile or temporary onboarding token | Existing accounts use profiles. No-account onboarding uses the temporary token returned by `sitegpt onboarding start`. |
| CLI instructions                                    | The skill file teaches the agent the command groups, safe workflows, and playbooks.                                    |

The public SiteGPT CLI skill file is available at:

```text theme={null}
https://sitegpt.ai/agents/sitegpt-cli-skill.md
```

Some AI products call this a skill file, project instruction, custom instruction, memory, or tool guide. The name varies, but the idea is the same: give the agent this document before asking it to manage SiteGPT.

## Recommended setup

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @sitegpt/cli
    sitegpt --version
    ```
  </Step>

  <Step title="Create a dedicated profile for the agent">
    Use a named profile instead of your default profile. This makes it obvious when the agent is operating SiteGPT.

    ```bash theme={null}
    sitegpt login --profile sitegpt-agent
    ```

    The browser approval page lets you review the access being requested before creating the token.
  </Step>

  <Step title="Verify the profile">
    ```bash theme={null}
    sitegpt --profile sitegpt-agent whoami
    sitegpt profiles list
    ```
  </Step>

  <Step title="Give the agent the skill file">
    Tell your agent to read this URL before using SiteGPT:

    ```text theme={null}
    https://sitegpt.ai/agents/sitegpt-cli-skill.md
    ```
  </Step>

  <Step title="Ask for JSON output">
    Tell the agent to use `--json` whenever it needs IDs or structured data.

    ```bash theme={null}
    sitegpt --profile sitegpt-agent chatbots list --json
    ```
  </Step>
</Steps>

## Copy-ready agent instruction

Paste this into your personal AI agent's instructions, project knowledge, or chat before asking it to work with SiteGPT:

```text theme={null}
You can manage my SiteGPT account with the SiteGPT CLI.

Before running commands, read the SiteGPT CLI skill file:
https://sitegpt.ai/agents/sitegpt-cli-skill.md

If I do not have a SiteGPT account yet, use agent-first onboarding: run sitegpt onboarding start with my website URL, configure and test the temporary chatbot, then give me the onboarding URL to preview and claim.
If I already have a SiteGPT account, use the profile named sitegpt-agent unless I tell you otherwise.
Prefer --json for commands where you need IDs or structured output.
Do not ask me to paste API tokens into chat. Use the saved CLI profile for existing accounts, or the temporary onboarding token returned by onboarding start.
Confirm before deleting chatbots, deleting knowledge, revoking tokens, removing members, or making broad account changes.
When creating a chatbot from a website, first confirm or infer the chatbot purpose: customer support, marketing/site guide, lead generation, docs/help, onboarding, or a mix. Then inspect the website, prefer sitemap knowledge when available, extract brand colors/icons from raw HTML/assets, and configure knowledge, persona, instructions, appearance, starters, and followups.
For agent-first onboarding, PROFILE_NOT_CONFIGURED is expected and should not stop the work. Do not batch optional auth checks with required website inspection or onboarding commands.
```

If you use a different profile name, replace `sitegpt-agent` in the instruction.

## Safer authentication choices

Use the smallest access level that can complete the job.

| Agent type                  | Suggested profile | Suggested access                                                                          |
| --------------------------- | ----------------- | ----------------------------------------------------------------------------------------- |
| Chatbot setup agent         | `setup-agent`     | Chatbot, knowledge, settings, personas, instructions, starters, and followups read/write. |
| Knowledge maintenance agent | `knowledge-agent` | Chatbot read plus knowledge read/write/delete for selected chatbots.                      |
| Support operations agent    | `support-agent`   | Conversations, messages, tags, leads, and chatbot read access.                            |
| Account review agent        | `account-agent`   | Account, usage, billing, and member read access.                                          |

For a chatbot-scoped knowledge profile:

```bash theme={null}
sitegpt login \
  --profile knowledge-agent \
  --chatbot <chatbot-id> \
  --scope account:read \
  --scope chatbots:read \
  --scope knowledge:read \
  --scope knowledge:write \
  --scope knowledge:delete
```

For broad end-to-end chatbot creation, use browser approval and review the permissions shown on the approval page:

```bash theme={null}
sitegpt login --profile setup-agent --full-access
```

<Warning>
  Full access is convenient for trusted local agents, but least-privilege scoped
  profiles are better for repeated workflows.
</Warning>

## Manual token setup

If you prefer to choose permissions in the dashboard first:

<Steps>
  <Step title="Create a token in SiteGPT">
    Open the SiteGPT dashboard, go to **Agents**, click **Create token**, choose the access level or custom scopes, and optionally restrict the token to specific chatbots.
  </Step>

  <Step title="Copy the token once">
    SiteGPT shows the plaintext token only once. Store it somewhere safe before closing the modal.
  </Step>

  <Step title="Save it into an agent profile">
    ```bash theme={null}
    sitegpt login --profile sitegpt-agent --token <sitegpt-api-token>
    ```
  </Step>

  <Step title="Verify it">
    ```bash theme={null}
    sitegpt --profile sitegpt-agent whoami
    ```
  </Step>
</Steps>

After this, your agent can use the profile without seeing the raw token.

## Example prompts for your agent

### Try SiteGPT before signup

```text theme={null}
Try SiteGPT for https://example.com. Use agent-first onboarding, inspect the site first, prefer sitemap knowledge if available, extract the brand color and icon from raw HTML/assets, then configure persona, instructions, appearance, conversation starters, followups, and run test messages. Give me the onboarding URL when it is ready to preview and claim.
```

Detailed playbook: [New customer onboarding](/cli/playbooks/agent-first-onboarding-chatbot).

### Create a chatbot in an existing account

```text theme={null}
Use the SiteGPT CLI with profile setup-agent. Create a new customer-support chatbot for https://example.com in my SiteGPT account. Inspect the site first, prefer sitemap knowledge if available, extract the brand color and icon from raw HTML/assets, then configure persona, instructions, appearance, conversation starters, followups, and run a test message. Show me the final chatbot ID, dashboard link, and what you configured.
```

Detailed playbook: [Existing account setup](/cli/playbooks/account-chatbot-setup).

### Add and verify knowledge

```text theme={null}
Use the SiteGPT CLI with profile knowledge-agent. Add this documentation sitemap to chatbot <chatbot-id>: https://docs.example.com/sitemap.xml. Then list the new knowledge documents, wait for ingestion if needed, and resync any failed documents. Use JSON output for document IDs.
```

### Review recent support activity

```text theme={null}
Use the SiteGPT CLI with profile support-agent. Review recent conversations for chatbot <chatbot-id>, summarize open issues, list new leads, and tag conversations that need human follow-up. Do not delete anything without asking me first.
```

### Update bot behavior

```text theme={null}
Use the SiteGPT CLI with profile setup-agent. Review the current persona, instructions, starters, and followups for chatbot <chatbot-id>. Suggest improvements for a concise support tone, then apply the approved changes.
```

## What agents can manage

| Area          | What the agent can do                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Chatbots      | Create, list, inspect, update, delete, open dashboard links, fetch install snippets, upload icons.                                          |
| Knowledge     | Add links, websites, sitemaps, files, YouTube videos, text, cloud data sources, custom responses, resync documents, update document config. |
| Customization | Manage personas, instructions, settings, starters, followups, and visual appearance.                                                        |
| Support       | List conversations, inspect messages, send visitor messages, escalate threads, manage tags, and review leads.                               |
| Account       | View usage, limits, billing invoices, members, invites, and API tokens when scoped.                                                         |

Use the [command reference](/cli/command-reference) for the complete command surface.

## Best practices

* Use named profiles for agents, such as `setup-agent`, `knowledge-agent`, and `support-agent`.
* Prefer `--json` when the agent needs IDs, document states, token IDs, or nested data.
* Ask or infer the chatbot purpose before setup so the persona, instructions, starters, followups, and lead capture match the job.
* For no-account onboarding, ask agents to run `sitegpt onboarding status --json` and inspect `setupChecklist` before sharing the onboarding URL.
* For existing accounts, ask agents to run `sitegpt profiles list` and `sitegpt whoami` before making changes.
* For no-account onboarding, do not treat `PROFILE_NOT_CONFIGURED` as a failure; continue with onboarding.
* Restrict tokens to specific chatbots when the agent only needs one chatbot.
* Confirm before destructive commands such as delete, revoke, remove, or bulk cleanup.
* Rotate or revoke tokens after demos, shared sessions, or experiments.
* Do not paste raw SiteGPT API tokens into chats unless you fully trust the environment.

## Troubleshooting

| Problem                         | What to ask the agent to check                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| Agent uses the wrong account    | Run `sitegpt profiles list` and `sitegpt --profile <name> whoami`.                        |
| Agent cannot access a chatbot   | Check whether the token is chatbot-restricted and includes the required scopes.           |
| Command output is hard to parse | Add `--json` to the command.                                                              |
| Agent cannot find a command     | Run contextual help, such as `sitegpt knowledge --help` or `sitegpt settings --help`.     |
| Production vs local confusion   | Check `SITEGPT_API_BASE` and the profile API base with `sitegpt profiles show <profile>`. |

For more fixes, see [Troubleshooting](/cli/troubleshooting).