SiteGPT CLI

Official command-line interface for SiteGPT — build and manage AI support agents (chatbots) from your terminal, your scripts, and your AI coding agents.

Create chatbots, ingest knowledge from your website and documents, tune personas and instructions, triage conversations and leads, and manage your team and billing — without leaving the shell. Every command self-documents (--help), speaks structured JSON (--json), and fails with a reason and a fix.

Built for three audiences at once:

• People — readable tables, colored output, and a guided onboarding flow.
• Scripts — --json everywhere, stable exit codes, --dry-run previews.
• AI agents — a discoverable workflow (sitegpt agent-guide), a published agent skill, and --wait so an agent never has to poll.

Contents

• Install
• Quick start
• Authentication
• Commands
• Built for automation and AI agents
• Knowledge and training
• Reference values
• Shell completion
• Profiles
• Configuration and environment
• Help and discovery
• Troubleshooting
• FAQ
• Support

Install

Requires Node.js 18+.

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

Quick start

There are two ways to use the CLI. Pick the one that matches where you are.

I don't have a SiteGPT account yet

Spin up a real, working chatbot from any URL — no signup required — then preview and claim it:

# 1. Create a temporary chatbot from a website (returns a token + an onboarding URL)
sitegpt onboarding start https://example.com --json

# 2. Use the temporary token for setup
export SITEGPT_API_TOKEN=<temporary-token>
sitegpt onboarding status <workspace-id> --json     # setup checklist
sitegpt knowledge sitemap add --chatbot <chatbot-id> https://example.com/sitemap.xml --wait

# 3. Hand over the onboarding URL so the human can preview and claim it
sitegpt onboarding claim <workspace-id> --email [email protected] --plan GROWTH --interval MONTH --json

I have a SiteGPT account

sitegpt login                       # browser approval, token saved locally
sitegpt chatbots list
sitegpt knowledge website add --chatbot <chatbot-id> https://docs.example.com --wait
sitegpt messages send --chatbot <chatbot-id> "How do I reset my password?"

That last messages send is the fastest way to prove the bot works — it returns the AI's answer right in your terminal. Grab the embeddable widget with sitegpt installation snippet --chatbot <chatbot-id>.

Authentication

sitegpt login runs a browser device-approval flow and stores the token locally at ~/.config/sitegpt/config.json.

sitegpt login                                              # default: device login
sitegpt login --token <sgpt_...>                           # save an existing token, no browser
sitegpt login --full-access                                # request every self-service scope
sitegpt login --scope chatbots:read --scope knowledge:write   # least-privilege
sitegpt whoami                                             # confirm who you're logged in as
sitegpt logout

Tokens look like sgpt_xxxxxxxxx — treat them as opaque. For CI and automation, mint a scoped token with sitegpt tokens create and pass it via SITEGPT_API_TOKEN.

Commands

29 command groups. Run sitegpt <group> --help for exact, always-current syntax (help is generated from the code, so it never drifts).

Auth & profiles

• login / logout / whoami — device login (or --token), with --full-access or repeated --scope for least-privilege.
• profiles — named local configs for multiple accounts or environments.
• tokens — create, list, rotate, and revoke scoped API tokens.

Onboarding (no account needed)

• onboarding — start, status (with a setup checklist), claim, and delete a temporary pre-claim chatbot.

Chatbots

• chatbots — list, get, create, update, delete.
• dashboard — open or print the dashboard URL.
• installation — the embed/install snippet for your site.
• icons — upload or remove visual icons.

Knowledge (sitegpt knowledge …)

• documents — list/get/stats/edit/resync/delete/update-config the trained items. Supports bulk selectors (--state, --source, --all, …) and --dry-run.
• links / website / sitemap / youtube / files / text — add knowledge from each source. Add --wait to block until trained.
• sources — external connectors (Google Drive, Notion, Dropbox, OneDrive, Box, SharePoint, Confluence, GitHub).
• sync-jobs — recurring refresh/scan schedules.
• custom-responses — manual question-and-answer overrides.
• wait — block until in-flight training settles (exits non-zero if any failed).

Customize

• settings — sectioned config: general, appearance, chat-mode, localization, advanced, user-data, lead-form, human-support, webhooks.
• personas — role, tone, identity (one active).
• instructions — behavior, grounding, safety, and temperature (one active).
• starters / followups — prompt buttons (followups can be a prompt, a link, or an escalation).

Inbox

• conversations — list/get/update threads; star, resolve, read, escalate, switch-to-ai, and bulk (--dry-run).
• messages — list, send (as the visitor; no thread ID starts a new conversation), react, edit.
• tags — label conversations.
• leads — captured contacts; update, star, archive, delete, and bulk (--dry-run).

Team & account

• members / member-invites — team access.
• account — your SiteGPT profile (name, picture).
• usage / limits / billing — usage totals, plan limits, subscription, and invoices.

Integrations & agents

• mcp — run the SiteGPT MCP (Model Context Protocol) server for MCP-aware assistants.
• agent-guide — print the end-to-end agent workflow and command map.
• completion — bash/zsh shell completion.

Built for automation and AI agents

This is where the CLI earns its keep in scripts and agent loops.

Structured JSON on every command

Add --json and you get a stable envelope — never scrape human text:

// success — exit code 0
{ "ok": true, "data": { /* command result */ } }

// failure — non-zero exit code
{
  "ok": false,
  "error": { "code": "CHATBOT_NOT_FOUND", "message": "…", "hint": "…", "details": {} },
  "meta": { "requestId": "…" }
}

Extract IDs with jq, branch on .ok, log error.code:

id=$(sitegpt chatbots create "Support Bot" --json | jq -r '.data.chatbot.id')

Stable exit codes

0 on success, non-zero on failure — so &&, set -e, and CI just work.

--wait: never poll for training

Training is asynchronous. Instead of looping on status, block until it settles:

sitegpt knowledge website add --chatbot <id> https://docs.example.com --wait --timeout 600
sitegpt knowledge wait --chatbot <id>      # wait on everything currently training

--wait exits non-zero if a document fails or the timeout is hit — exactly what an agent needs before it can honestly say "your chatbot is ready."

--dry-run: preview destructive and bulk ops

sitegpt knowledge documents delete --chatbot <id> --state failed --dry-run
sitegpt leads bulk --chatbot <id> --action archive --lead <lead-id> --dry-run

Shows exactly what would be affected, changes nothing.

Failures that help instead of just failing

• Did-you-mean on typos: sitegpt chatbts suggests chatbots.
• Actionable hints: errors print a → line with the next step (for example, how to find a chatbot ID).
• --debug / --verbose trace each request to stderr; --quiet / -q suppress progress output.

For AI agents

sitegpt agent-guide      # machine-readable, end-to-end workflow + command map

SiteGPT publishes an installable agent skill at https://sitegpt.ai/agents/sitegpt-cli-skill.md and an Auth.md discovery flow at https://sitegpt.ai/auth.md. The skill teaches an agent the full build-a-chatbot workflow; this CLI is its recommended execution path.

Knowledge and training

Add knowledge from links, a crawl, a sitemap, files, YouTube, plain text, or a connected source — then wait for it to train:

sitegpt knowledge documents list --chatbot <id> --state failed
sitegpt knowledge links add --chatbot <id> https://example.com/a https://example.com/b --wait
sitegpt knowledge files add --chatbot <id> ./handbook.pdf --wait
sitegpt knowledge documents resync --chatbot <id> --state failed --wait
sitegpt knowledge custom-responses add --chatbot <id> --question "Do you offer refunds?" --answer "Yes, within 30 days."

Connect external sources — Google Drive, Notion, Dropbox, OneDrive, Box, SharePoint, Confluence, GitHub — with sitegpt knowledge sources (run sitegpt knowledge sources --help).

Reference values

For the exact enums on any command, run its --help. Common cross-command values:

• Token scopes — <area>:<read|write|delete> for account, tokens, chatbots, knowledge, personas, instructions, starters, followups, conversations, leads, members, plus read/write pairs for settings, billing, and integrations. Use the narrowest set; --full-access requests every self-service scope.
• Onboarding claim — plans STARTER · GROWTH · SCALE; intervals MONTH · YEAR (new-customer checkout only).
• Sync / scan frequency — NEVER · DAILY · WEEKLY · MONTHLY (may be plan-gated).
• Knowledge connectors — NOTION · GOOGLE_DRIVE · DROPBOX · ONEDRIVE · BOX · SHAREPOINT · CONFLUENCE · GITHUB.
• Icon types — bot · person · agent · watermark · chat-bubble.
• Message reactions — POSITIVE · NEGATIVE · NEUTRAL.
• Member roles — AGENT · MANAGER · ADMIN · SUPER_ADMIN.

Shell completion

# zsh
source <(sitegpt completion zsh)

# bash
source <(sitegpt completion bash)

Add the line to your ~/.zshrc or ~/.bashrc to make it permanent.

Profiles

Work across multiple accounts or environments from one machine:

sitegpt login --profile work
sitegpt profiles list
sitegpt chatbots list --profile work
sitegpt profiles use work          # make a profile the default

Configuration and environment

| Variable | Purpose | | ------------------- | ---------------------------------------------------- | | SITEGPT_API_TOKEN | Token override for a single command (ideal for CI) | | SITEGPT_API_BASE | API base URL override (default https://sitegpt.ai) | | SITEGPT_PROFILE | Profile override |

Global flags available on every command: --json, --profile/-p, --api-base, --quiet/-q, --verbose, --debug, --help/-h, --version.

Config and tokens are stored at ~/.config/sitegpt/config.json.

Help and discovery

Help is generated from the code, so it can never drift:

sitegpt --help
sitegpt knowledge --help
sitegpt knowledge documents --help
sitegpt settings appearance --help

Troubleshooting

• Wrong account or environment → sitegpt profiles list, then sitegpt profiles use <profile>.
• A command seems to hang → it's likely --wait blocking on training; add --timeout <seconds> or drop --wait.
• See what the CLI is doing → add --debug to trace each request (method, URL, status, timing) to stderr.

Common error codes:

• TOKEN_SCOPE_NOT_VALID — the scope string is not supported.
• TOKEN_SCOPE_NOT_ALLOWED — the current token lacks the required scope; run sitegpt login and approve it, or mint a scoped token with sitegpt tokens create.
• AUTHORIZATION_HEADER_REQUIRED or TOKEN_NOT_VALID — log in again or switch profiles.
• UNKNOWN_COMMAND with a "Did you mean" suggestion — a near-match name was typed; use the suggested name, or run the nearest --help.

FAQ

How do I add an AI chatbot to my website from the command line?

Install the CLI (npm install -g @sitegpt/cli), then create a chatbot and train it on your site:

# no account needed:
sitegpt onboarding start https://yoursite.com --json
# or, with an account:
sitegpt chatbots create "Support Bot"
sitegpt knowledge website add --chatbot <id> https://yoursite.com --wait

Then get the embeddable widget with sitegpt installation snippet --chatbot <id>.

Can an AI agent build and configure a SiteGPT chatbot?

Yes — it's a primary design goal. Agent-first onboarding (sitegpt onboarding start <url>) needs no login, every command supports --json, --wait removes polling, and sitegpt agent-guide prints the full workflow. SiteGPT also ships an installable agent skill at https://sitegpt.ai/agents/sitegpt-cli-skill.md.

How do I use SiteGPT in a script or CI/CD pipeline?

Mint a scoped token (sitegpt tokens create …) and pass it via SITEGPT_API_TOKEN, add --json to every command, branch on the ok field, and rely on exit codes (0 success, non-zero failure).

Does the SiteGPT CLI work without a SiteGPT account?

Yes. sitegpt onboarding start <url> creates a real, working chatbot from a URL with no signup, and returns an onboarding URL where you can preview and claim it later.

Is there a SiteGPT MCP server?

Yes — sitegpt mcp runs the SiteGPT MCP (Model Context Protocol) server so MCP-aware assistants can call SiteGPT directly.

How do I add knowledge to a chatbot?

sitegpt knowledge adds content from links, a website crawl, a sitemap, files, YouTube, plain text, or connected sources (Google Drive, Notion, Confluence, GitHub, and more). Add --wait to block until training finishes.

Support

Questions or issues? Email [email protected].

License

MIT © SiteGPT