Use SiteGPT CLI with AI agents

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.

Use MCP Server

Best for Claude and other AI apps that support remote MCP with browser-based OAuth approval.

Use the CLI

Best for local agents that can run terminal commands and use saved SiteGPT profiles.

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

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:

Install the CLI on the machine where the agent runs.
Log in with a named, scoped profile.
Give the agent the SiteGPT CLI skill file.
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:

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

Install the CLI

npm install -g @sitegpt/cli
sitegpt --version

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.

sitegpt login --profile sitegpt-agent

The browser approval page lets you review the access being requested before creating the token.

Verify the profile

sitegpt --profile sitegpt-agent whoami
sitegpt profiles list

Give the agent the skill file

Tell your agent to read this URL before using SiteGPT:

https://sitegpt.ai/agents/sitegpt-cli-skill.md

Ask for JSON output

Tell the agent to use --json whenever it needs IDs or structured data.

sitegpt --profile sitegpt-agent chatbots list --json

Copy-ready agent instruction

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

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:

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:

sitegpt login --profile setup-agent --full-access

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

Manual token setup

If you prefer to choose permissions in the dashboard first:

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.

Copy the token once

SiteGPT shows the plaintext token only once. Store it somewhere safe before closing the modal.

Save it into an agent profile

sitegpt login --profile sitegpt-agent --token <sitegpt-api-token>

Verify it

sitegpt --profile sitegpt-agent whoami

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

Example prompts for your agent

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.

Create a chatbot in an existing account

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.

Add and verify knowledge

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

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

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

Use MCP Server

Use the CLI

​Choose the right agent flow

​What your agent needs

​Recommended setup

​Copy-ready agent instruction

​Safer authentication choices

​Manual token setup

​Example prompts for your agent

​Try SiteGPT before signup

​Create a chatbot in an existing account

​Add and verify knowledge

​Review recent support activity

​Update bot behavior

​What agents can manage

​Best practices

​Troubleshooting

Choose the right agent flow

What your agent needs

Recommended setup

Copy-ready agent instruction

Safer authentication choices

Manual token setup

Example prompts for your agent

Try SiteGPT before signup

Create a chatbot in an existing account

Add and verify knowledge

Review recent support activity

Update bot behavior

What agents can manage

Best practices

Troubleshooting