--- name: sitegpt-cli description: Use when an AI agent needs to manage SiteGPT through the SiteGPT CLI, including authentication, profiles, chatbots, knowledge sources, custom responses, settings, personas, instructions, conversations, messages, leads, members, billing, tokens, or troubleshooting CLI command usage. --- # SiteGPT CLI Use the SiteGPT CLI to manage SiteGPT accounts and chatbots from a terminal or agent environment. Prefer CLI commands for direct operations, scripting, file uploads, and reliable terminal output. The installed command is `sitegpt`. SiteGPT also publishes an agent auth discovery file at `https://sitegpt.ai/auth.md`. Use it when an agent environment wants a standard, machine-readable description of the anonymous onboarding registration flow. The CLI commands below remain the preferred implementation path when a terminal is available. ## Prerequisite Check whether the CLI is installed before starting: ```bash sitegpt --version ``` If `sitegpt` is missing, ask the user before installing it: ```bash npm install -g @sitegpt/cli ``` ## Agent Operating Mode You own the outcome: a working, branded, accurate chatbot the human is glad to claim — not a list of commands run. Act like a SiteGPT implementation engineer. - Understand the business from its website, docs, audience, and support needs. - Resolve the canonical website URL first and reuse it everywhere (see "Resolve The Canonical Website URL First"). - Build a discovery brief and **ask it before you create or train the chatbot** — use case, industry, audience, persona, primary goal, escalation (see "Build A Discovery Brief First"). Creating the chatbot and ingesting knowledge before you ask reads as never having asked, even if you ask afterward. - Create or update the right SiteGPT resources through the CLI; prefer `--json` for IDs and status; parallelize independent work after required IDs exist. - Treat the website as messy: handle bare/non-canonical domains, JS-rendered pages, anti-bot blocks, and missing sitemaps without giving up (see "Robustness And Recovery"). - The value moment is a correct answer to a question the human did not script. Do not hand over a preview until you have verified that (see "The Aha Test"). - Stay visible on anything longer than a few seconds, and finish with a crisp handoff: what you built, test questions to try, and the claim/dashboard link. - Never invent company facts, pricing, policies, or capabilities; never echo tokens; confirm before anything destructive. If web/browser/fetch tools are available, inspect the website before creating the chatbot — the SiteGPT CLI manages SiteGPT, it does not understand websites. With no web tools, create a conservative chatbot, ingest the sitemap/website, and tell the user that deeper brand-specific customization needs website inspection. ## Quick Start — The Happy Path For the most common request — "create / try a SiteGPT chatbot for ``" with no account or token provided — do exactly this, in order. Do not improvise command names, and do not explore by trial and error. 1. Confirm the CLI: `sitegpt --version` (install only if missing). 2. **Pick the flow — ask, don't assume.** If a human is present and gave no token, your **first** question to them is: **"Do you already have a SiteGPT account?"** Not being logged in is ambiguous — the human might have no account, one account, or several. Don't guess which, and don't choose the flow for them based on anything you think you know about who they are; ask, and let them decide. Being logged out / having no saved profile is exactly why you ask, not a reason to skip to the preview (see "Choose The Right CLI Flow First"). - **Yes** → run `sitegpt login` (a one-time browser approve) and build **in their account** (**Account Chatbot Setup**). Do **not** hand an account-holder a throwaway preview to claim later just to skip logging in. - **No / just trying** → the no-login preview path, steps 3–7 below. - No human to ask (headless) → default to the preview path. 3. Resolve the canonical website URL and inspect the site **just enough to pre-fill the brief** (the two sections below) — homepage content, brand, and whether a sitemap exists. Save deep work (logo extraction, sizing every sitemap) for after the human answers. 4. **Ask the human the discovery brief** as multiple-choice questions and **wait for the answers — before you create or train anything.** This is the human's first interaction; do not build first and ask at the end. 5. Create the preview **once**: `sitegpt onboarding start --json`. It is public — no login. Capture the workspace id, chatbot id, temporary token, and onboarding URL. **Never re-run this on a retry** — reuse the ids you already got, or you will create duplicate workspaces. 6. Configure from the answers — knowledge (sitemap), persona, instructions, starters/followups, appearance/icon. Discover exact flags with `sitegpt --help`. 7. Run the aha test, then share the onboarding URL and offer to claim. **Command rule.** The **CLI is the source of truth for command syntax**; this skill is the source of truth for *workflow*. Discover commands with `sitegpt agent-guide` (workflow + command map) and exact flags with `sitegpt --help` / `sitegpt --help`. Never guess a name like `chatbot create` or `source add-website`; if a command or flag is rejected, read its `--help` instead. Errors are structured — in `--json` they carry an `error.code` and often an `error.hint`; read the hint and do exactly what it says before retrying (it usually names the command that fixes it, e.g. how to get a missing id or which auth step to run). **Token rule.** Keep the temporary token out of command lines and logs — write it to an env file and `source` it (`export SITEGPT_API_TOKEN=…` in a file), so it is never echoed inline. ## Choose The Right CLI Flow First Decide the flow before doing the work: - **The human gave a token/profile, said they already use SiteGPT, or asked to update an existing chatbot/account** → **Account Chatbot Setup**: check auth and manage resources directly in that account. - **No token/profile, and a human is present** → do not assume. Ask one quick multiple-choice question and branch on the answer: > Do you already have a SiteGPT account? > • **Yes — build it in my account** → I'll log you in and create it there. > • **No / just trying — build a free preview I can claim** → I'll build a > working chatbot with no login, and you claim it afterward (an existing > account can claim it too). - **Yes** → run `sitegpt login`, then **Account Chatbot Setup**. - **No / just trying** → **Agent-First Onboarding** (`sitegpt onboarding start`, no login, then preview and claim). - **No token/profile and no human to ask** (autonomous/headless run) → default to **Agent-First Onboarding**, since it creates value before signup. `PROFILE_NOT_CONFIGURED` (or any logged-out / no-token state) is not an error and never a reason to stop — it only means no saved profile exists. **It does not mean the human has no SiteGPT account**: they may have one and simply need to `sitegpt login`. So a logged-out CLI is never a reason to skip the account question and jump to the preview — when there is no token and a human is present, you must ask first. Do not run `whoami` and treat its failure as "no account". ## Resolve The Canonical Website URL First A human often gives a bare or non-canonical domain — `example.com`, `www.example.com`, `http://example.com`, or a deep link. Normalize it once, before inspection, before `onboarding start`, and before knowledge ingestion, then reuse the same canonical URL everywhere so pages are not missed or duplicated. - If no scheme is given, try `https://` first; fall back to `http://` only if HTTPS fails. - Check for a redirect to find the host the site actually serves from: ```bash curl -sIL "https://example.com" | grep -iE '^HTTP/|^location:' ``` - **If the site redirects** (`example.com` 301s to `www.example.com`, or the reverse), use the final redirect target as canonical. - **If there is no redirect and both hosts respond** — a common setup where `example.com` and `www.example.com` each serve the site independently — figure out the canonical host; do not guess. In order: 1. Declared canonical on the homepage: ``, `og:url`, or JSON-LD `url`/`@id`: ```bash curl -sL "https://example.com" | grep -iE 'rel="canonical"|og:url|"@id"|"url"' ``` 2. If none is declared, infer it: the host used in the sitemap's `` URLs and in the homepage's own internal absolute links reveals the site's preferred host. 3. If still unknown, fetch both hosts and compare. If they serve the **same** site, either works — keep the host the human gave and use it consistently. If they serve **different** content (one is parked, blank, or a different site), use the host with the real site. 4. State the chosen host and any assumption in your report. Pick one host and use it **consistently** for onboarding and every knowledge source, so the crawl is never split across www and non-www. - Use that one canonical origin for the robots.txt and sitemap checks below, for `sitegpt onboarding start`, and for the website/sitemap knowledge sources. - If neither scheme is reachable, or the domain redirects off to a parked / for-sale / unrelated page, stop and tell the human instead of building a chatbot for the wrong site. ## Build A Discovery Brief First **Gather a short discovery brief — and ask it before you create the chatbot or start ingestion, not after.** The brief drives persona, instructions, starter prompts, lead capture, escalation, tone, and which pages matter most. Inspect the site only enough to pre-fill the answers; creating the chatbot, ingesting knowledge, and configuring everything else all come **after** the human replies. Creating the bot and kicking off ingestion first — then asking at the end — reads as "it never asked me" even though you did, and it is the most common way this skill disappoints a human. A tailored result the human helped shape is what makes them claim it; a generic one built without them undersells. **You must ask, not assume.** When a human is in the loop and you can put a question to them — any interactive session, including Claude Code, Cursor, or a chat UI — **ask the discovery brief as multiple-choice questions and wait for the answers before you configure the chatbot**. Silently inferring the brief and building anyway is a failure of this skill: the human chose to be involved, and the brief is the one place their choice matters most. Only skip the questions when there is genuinely no human to answer (a headless, CI, or batch run) or the human explicitly said "just build it" / "use your best guesses". Make it effortless, not an interrogation. Inspect the website first so you can **pre-fill the most likely answer** to every question; the human mostly taps to accept. Selecting an option is not friction — only typing is. - **Use your environment's question tool** (for example Claude's AskUserQuestion) to present the brief as multiple-choice questions with the inferred answer pre-selected and an "Other" option for typing. Do not just print the questions and answer them yourself — put them to the human and wait for a reply. - **If you only have plain text** (no question tool), present the inferred brief as one compact confirm-or-edit message and wait for the reply. - **Only if there is no human at all** (autonomous/headless run): proceed with the inferred brief and clearly state every assumption in your final report. Ask about six things, ordered by impact. Each is multiple-choice with the inferred default pre-selected; include an "Other" choice so the human can type when the options do not fit: 1. **Primary use case** — Customer support · Sales / lead-gen · Onboarding / product guide · Docs / technical · Marketing guide · A mix. 2. **Industry** — SaaS · Ecommerce · Healthcare · Legal · Finance · Education · Agency · Local services · Other. Drives tone and safety guardrails. 3. **Audience** — Prospects · Existing customers · Developers · Patients · Students · Mixed. 4. **Primary goal** — Deflect support tickets · Book a demo · Capture leads · Start a trial · Help find docs/answers. 5. **Tone** — Friendly · Formal · Technical · Playful · Enterprise · Caring / cautious. 6. **Escalation and contact** — Support email · Sales email · Human handoff · None found. Use a text field for the actual address, pre-filled if the site published one. Optional, skippable follow-ups: bot/persona name (pre-fill ` Assistant`), languages, priority pages to weight in knowledge, and anything the bot must not say. Keep it to one short pass and pre-select everything, so a human who agrees just confirms. **Translate the brief into the persona, instructions, and settings — do not paste the raw brief into the instruction set.** The instruction set is the bot's runtime prompt; a `Discovery brief (set by the owner): use case = …, lead form = off` header there is redundant with the behavior you already wrote from it, is noise the model re-reads on every answer, and leaks operational details if a user asks the bot about itself. Instead, put a clean human-readable summary of the bot's purpose in the **chatbot description** (metadata, not the prompt), and **recap the choices you made to the human in your handoff** so they can see and adjust them. The answers are also useful signal — in an account context they can feed analytics on which use cases and industries convert best. Then translate the brief into configuration using the use-case presets and industry guardrails below. ## Use-Case Presets Map the brief's primary use case to a configuration bundle. Treat these as strong defaults, then adjust to the specific website. - **Support** - Persona: brand support specialist; friendly, concise. - Starters: "How do I …", "Troubleshoot …", "Pricing and plans", "Contact support". - Lead form: off unless the goal also includes leads. - Escalation/CTA: escalate to the support email; offer human handoff when stuck. - Instruction emphasis: accuracy, grounded answers, uncertainty handling, escalation. - **Sales / lead-gen** - Persona: sales-aware advisor; helpful, confident. - Starters: "What does do?", "Plans and pricing", "Book a demo", "Is it right for me?". - Lead form: on, with one or two qualification fields. - Escalation/CTA: book-a-demo or contact-sales link. - Instruction emphasis: qualify, capture contact, route to sales, never invent pricing. - **Onboarding / product guide** - Persona: onboarding guide; encouraging, step-by-step. - Starters: "Getting started", "Set it up", "Key features", "Best practices". - Lead form: optional. - Escalation/CTA: link to setup docs or support. - Instruction emphasis: step-by-step guidance, link to docs, reduce time-to-value. - **Docs / technical** - Persona: docs assistant; precise, technical. - Starters: "How to …", "API / reference", "Examples", "Limits and quotas". - Lead form: off. - Escalation/CTA: link to the most relevant docs. - Instruction emphasis: cite sources, careful unknowns, no invented behavior. - **Marketing guide** - Persona: friendly product guide. - Starters: "What is ?", "Who is it for?", "Pricing", "How does it compare?". - Lead form: optional. - Escalation/CTA: CTA to start a trial or book a demo. - Instruction emphasis: clear value proposition, help visitors navigate, honest comparisons. For a mix, lead with the primary use case and fold in the secondary one's starters and escalation without overcomplicating the persona. Let the **primary goal** drive lead capture: if the goal is leads, enable the lead form and qualification even when you must ask the human for the sales email — do not wait for the website to volunteer it. ## Industry Guardrails Bake industry-appropriate tone and safety into the instruction set: - **Healthcare** — caring, cautious. No medical advice or diagnosis; urge contacting a qualified professional; be privacy-aware. - **Legal** — formal, cautious. No legal advice; general information only; suggest consulting a lawyer. - **Finance** — precise, cautious. No financial or investment advice; no guarantees of returns. - **Ecommerce** — friendly. Handle orders, returns, and shipping only from published policy; never invent stock, prices, or delivery dates. - **SaaS / tech** — technical, concise. Ground answers in docs; cite; be careful with API behavior and limits. - **Education** — encouraging. Keep it age-appropriate; cite sources. - **Local services** — warm, simple. Give hours, location, and booking from the site; collect contact details for quotes. When the industry is sensitive (healthcare, legal, finance), make the "do not invent / not professional advice" rules explicit in the instructions and prefer escalation to a human over guessing. ## Robustness And Recovery Real websites and networks are messy. A world-class run degrades gracefully and never strands the human. - **Idempotency.** Do not create duplicates on a re-run. Reuse the workspace and chatbot ID you already have this session; run `onboarding start` once per site per session; list existing knowledge/personas/instructions before adding to an account chatbot. - **Transient errors.** On HTTP 429 or 5xx, back off and retry a few times before surfacing the failure. Ingestion is asynchronous — block until it settles with `sitegpt knowledge wait --chatbot --json` (or pass `--wait` to an add command); it exits non-zero on timeout and reports trained/failed counts. Don't assume training finished, and don't hand-roll a poll loop. - **Partial failures.** If some documents fail, report which and the `knowledge documents resync` command; do not claim the bot is fully trained. - **Plan limits.** Sync/scan frequencies and source counts may be downgraded with an API warning — surface these instead of silently dropping them. - **Hard websites.** JS-rendered (SPA) pages, anti-bot/403 blocks, and missing sitemaps are common — the inspection step shows how to detect and work around each. Always still produce a working bot, and note where appearance or knowledge was set conservatively. - **Subdomains and walled content.** Knowledge often lives on `docs.`, `help.`, `app.`, or `blog.` subdomains — include the ones that match the use case. Login-walled docs cannot be crawled; suggest a connector (Notion, Drive, GitHub, Confluence) instead. - **Stay visible.** Anything longer than a few seconds (crawl, indexing) gets a short progress note. Never go silent through a multi-minute build. - **Degrade by capability.** No question tool → one confirm message for the brief. No web tools → conservative bot + sitemap ingest. No human → infer and proceed, stating assumptions. - **Freshness needs a re-syncable source.** Recurring auto-sync/scan attaches to **WEBSITE or SITEMAP** sources, not to individual `links add` (URLS_LIST) docs. If the knowledge must stay current (pricing, features), ingest the main source as a sitemap/website so it can auto-sync; for facts that must never drift (pricing, contact), also seed a custom response. - **Expected ingestion failures.** Some JS-rendered pages fail to ingest. If a failed page is redundant — its content already covered by another source you ingested — remove it and move on; do not treat it as a blocker or retry it endlessly. - **No busywork, and trust your output.** Command output is reliable: never run empty "sync"/"checkpoint"/"noop" commands to flush it. Before retrying a command, check status (`status` / `documents stats`) — do not re-run something that already succeeded just because a count or message looked off, and never re-run `onboarding start` (it creates a duplicate). ## First Moves For agent-first onboarding, start with the website URL, not an account login. It is fine to check `sitegpt --version` and inspect the website first, but do not run `sitegpt whoami` as a required step. If a human is present, **ask the discovery brief and wait for the answers before this step** (see "Build A Discovery Brief First") — do not create the workspace and build first: ```bash sitegpt onboarding start https://example.com --json ``` This does not require login. It returns a temporary one-chatbot token, chatbot ID, and onboarding URL. Use the temporary token to finish setup, then check readiness: ```bash SITEGPT_API_TOKEN="" sitegpt onboarding status --json ``` After capturing the temporary token, keep using it through `SITEGPT_API_TOKEN` instead of logging in. Do not echo the token, do not include the full token in final output, and do not ask the human to create a token unless the onboarding start command fails. The status response includes `data.setupChecklist`; fix pending, warning, or unknown checklist items when possible before sharing the onboarding URL. Give the human the onboarding URL only after you have configured and tested the chatbot. Do not ask the human to sign in before a chatbot preview exists unless the user explicitly wants to manage an existing SiteGPT account. After the human claims the chatbot, the same temporary token is transferred to the claimed SiteGPT user. It stays scoped only to that chatbot and keeps its original expiry. Continue using it for final checks or small post-claim edits unless the user asks you to stop. After the human reviews the preview, ask whether they want to claim it, then run the claim — the full flow (email/plan/interval, checkout, and the existing-subscriber case) is in **Playbook: Agent-First Onboarding Chatbot**. For existing accounts or direct account management, use the **Account Chatbot Setup** playbook (it starts with `whoami` / `login` / `profiles`). Use `--json` whenever you need IDs, pagination cursors, full nested data, or reliable parsing, and discover exact syntax with `sitegpt --help`. ### Avoid Cancelled Setup Work Some agent runtimes cancel parallel tool calls when one command returns a non-zero exit code. Do not put optional auth checks in the same shell command or parallel batch as required website inspection. Good: ```bash sitegpt --version sitegpt whoami --json || true ``` Then independently inspect the website and continue with onboarding if auth is not configured. Bad: ```bash sitegpt whoami --json && curl -sL https://example.com -o /tmp/page.html ``` For agent-first onboarding, missing auth is expected. Website inspection and `sitegpt onboarding start` should still continue. ## Playbook: Agent-First Onboarding Chatbot Use this workflow when the user asks something like "Try SiteGPT for https://example.com" and they have not provided an existing SiteGPT token/profile. The goal is to create a working preview before signup. If the user already has a SiteGPT token/profile and wants the chatbot created directly inside their account, use the **Account Chatbot Setup** playbook below instead. ### Configuration Mindset Configure the temporary chatbot as a polished first preview. The human has not created a SiteGPT account yet, so the preview must demonstrate value before signup: - **Knowledge**: add the best source first, usually sitemap. Wait for training when practical and use `onboarding status` to inspect `setupChecklist`. - **Brand settings**: upload a real brand icon/chat bubble and apply extracted colors before sharing the preview. The user should immediately recognize the website's brand in the preview page and launcher. - **Persona**: create one clear persona matching the chatbot purpose. Avoid overcomplicated persona variants; the user needs one strong default. - **Instructions**: create one active instruction set with grounding, uncertainty, escalation/contact behavior, and purpose-specific rules. - **Starters/followups**: add broad visitor questions that make the preview easy to test without the user thinking of prompts. - **Lead/support settings**: enable only when the website or user provides the needed contact/sales details. - **Handoff**: final output should focus on the onboarding URL, setup checklist status, what was configured, and what the human can claim. ### 1. Inspect The Website Use raw HTML (`curl` + search) for structured signals like colors, icons, manifests, and sitemap links. Use WebFetch/browser tools for prose-heavy understanding like value proposition, navigation, audience, and tone. Gather: - Brand or product name. - Homepage title, meta description, and core value proposition. - Main navigation labels and important URLs. - Docs, pricing, contact, support, FAQ, blog, terms, privacy, and login URLs when visible. - Support email, sales email, phone number, or contact form URL if published. - Logo, favicon, or simple brand mark that can be saved as an image file. - Brand colors from the required raw HTML extraction procedure below. - Open Graph/Twitter images, app icons, and product screenshots that can inform the chatbot's visual setup. - Sitemap URLs from `robots.txt`, ``, `/sitemap.xml`, `/sitemap_index.xml`, or obvious CMS sitemap paths. - Tone: formal, friendly, technical, playful, enterprise, healthcare/legal cautious, etc. Do not invent company facts, pricing, policies, emails, or guarantees. If something is not visible, configure the chatbot to say it does not know and offer escalation/contact. ### 1A. Extract Structural Signals From Raw HTML (Required) Summarizing tools are useful for understanding prose, but they often strip or blur exact metadata such as hex colors, icon links, manifests, and sitemap links. Do not trust qualitative output like "appears to be blue-based" for appearance setup. Always inspect raw HTML before choosing brand colors or icons. Use a raw-HTML pass: ```bash SITE_URL="https://example.com" # Use a real browser User-Agent — default curl is blocked by many sites and CDNs. UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36" curl -sL -A "$UA" "$SITE_URL" -o /tmp/sitegpt-page.html # Detect a JS-rendered (SPA) shell: tiny body + a root mount node and little real text. # If so, raw HTML has no content/colors/links — render with a browser/WebFetch tool, # or rely on the sitemap for URLs. wc -c /tmp/sitegpt-page.html grep -ciE 'id="root"|id="__next"|__NEXT_DATA__|` lists child sitemaps — follow them to reach the actual page URLs. Pass a working sitemap URL to `sitegpt knowledge sitemap add`; if it does not expand a nested index, add the child sitemaps or fall back to the website crawl. If a manifest is linked, fetch it and inspect colors/icons: ```bash curl -sL "$SITE_URL/manifest.json" ``` Download the chosen icon or image to a local file and confirm format/dimensions before upload: ```bash curl -sL "https://example.com/logo-icon.png" -o /tmp/sitegpt-brand-icon.png file /tmp/sitegpt-brand-icon.png ``` Prefer assets in this order: 1. `apple-touch-icon` or large app icon. 2. Manifest icon with square dimensions. 3. Clean logo mark or favicon PNG/SVG converted to PNG. 4. Open Graph/Twitter image only if it contains a clear brand mark and can be cropped. Only fall back to visual guesses or WebFetch's qualitative color description when raw HTML, CSS-visible variables, manifest, theme-color, and icon links provide no usable signal. If you pick a generic default such as `#2563EB`, treat that as a warning and re-check raw HTML before proceeding. ### 1B. Decide Brand Assets Create an asset plan before creating the chatbot so the finished bot feels branded immediately: - Primary color: choose the strongest brand/action color, usually from `theme-color`, primary buttons, CSS variables such as `--primary`, or the logo. - Text-on-brand color: choose `#ffffff` for dark/saturated colors and `#111827` or similar for light colors. - Link color: usually the primary brand color unless the site uses a separate link color. - Icon background color: usually the primary brand color. - Icon shape/position/size: use normal product defaults unless the site clearly uses rounded/square visual language. - Bot/chat-bubble image: prefer favicon, app icon, simple logo mark, or a clean cropped logo. Avoid wide wordmarks as tiny icons. - Watermark/person/agent images: only set when you have high-quality assets and the user expects them. If image tooling is available, crop/convert the best logo or favicon into a square PNG with transparent or clean background before upload. If only a remote image URL is available, download it to a local file first, then upload the file. Do not pass remote URLs to `sitegpt icons upload`. ### 2. Ask The Discovery Brief, Then Draft The Blueprint You have now inspected enough to pre-fill the brief, so **ask the human the discovery brief and wait for the answers before you start the workspace or configure anything** (see "Build A Discovery Brief First"). Do not run `onboarding start` and build the whole bot first, then ask at the end — that reads as never having asked. The only exception is a headless run with no human. Then, driven by the confirmed brief (apply the matching use-case preset and industry guardrails), decide before mutating SiteGPT: - Primary use case and the rest of the brief: industry, audience, persona/voice, primary goal, and escalation. Secondary use cases can layer on starters/CTAs. - Chatbot title that fits the brief's role — ` Assistant`, ` Guide`, or ` Support`; do not default to "Support" for a sales/marketing/docs bot. - Chatbot description, one sentence about what it helps with. - Best knowledge source: sitemap first, website crawl second, selected links third. - Persona: the bot's role and voice. - Instructions: grounding, uncertainty, escalation, privacy, lead capture, and forbidden behavior. - Starter prompts: 3-5 first-click questions a visitor would naturally ask. - Followup prompts: 3-5 useful next actions, including contact/support when appropriate. - Settings: chat mode, support email, lead form/human support if appropriate, and any appearance/icon updates. - Brand assets: primary color, readable brand text color, link color, icon background, and local icon file paths. ### 3. Start The Temporary Workspace Start onboarding: ```bash sitegpt onboarding start https://example.com --agent-name "" --json ``` Capture: - `data.workspace.id` as ``. - `data.workspace.chatbotId` as ``. - `data.apiToken` as the temporary setup token. - `data.onboardingUrl` for the human. This single page lets the human test the chatbot and claim it. Run setup commands with the temporary token: ```bash SITEGPT_API_TOKEN="" sitegpt chatbots get --json ``` Check the workspace readiness after major setup steps: ```bash SITEGPT_API_TOKEN="" sitegpt onboarding status --json ``` Inspect `data.setupChecklist`. The checklist reports whether knowledge, persona, instructions, conversation starters, follow-up prompts, and brand styling are done, pending, unknown, or need review. Fix pending or warning items before sharing the onboarding URL unless the user explicitly asks for a rough draft. After setup, test the chatbot with a few realistic visitor messages. If it answers from the added knowledge and the setup checklist is acceptable, tell the user the chatbot is ready and share `data.onboardingUrl` for manual testing. Ask whether they want to claim it now. If the user wants to claim it, **first ask whether they are claiming into an existing SiteGPT account or as a new customer — do not assume new and jump to plan/interval.** - **Existing account** (e.g. they already use SiteGPT) → they claim from the onboarding page **while signed in**; SiteGPT attaches the chatbot directly to their account with **no checkout and no plan/interval**. The CLI's temporary token cannot prove ownership of an existing account, so don't ask for plan/interval — just point them to the page. - **New customer** → ask for email, plan, and interval, then start the claim: ```bash SITEGPT_API_TOKEN="" sitegpt onboarding claim --email user@example.com --plan GROWTH --interval MONTH --json ``` If `data.checkoutUrl` is present, return it and explain that checkout happens on SiteGPT's pricing page. Once the free trial starts, SiteGPT transfers the temporary chatbot into that email's dashboard account. If checkout is already pending, reuse the returned checkout URL and do not ask for a different email or plan. If the response says the email already has an active subscription, ask the human to open the onboarding URL while signed in and claim from the page. If the setup is wrong or the human does not want the workspace, delete it: ```bash SITEGPT_API_TOKEN="" sitegpt onboarding delete --yes ``` This deletes the temporary chatbot and onboarding workspace. The workspace is no longer available after deletion. ## Playbook: Account Chatbot Setup Use this workflow when the user gives you a SiteGPT token/profile or asks to manage an existing SiteGPT account. This also works for a new SiteGPT customer who already wants to authenticate first and create their first chatbot directly in their account. ### Configuration Mindset Configure inside a real SiteGPT account. Be more careful with existing state than in onboarding because the account may already have chatbots, knowledge, settings, tokens, or team workflows: - **Knowledge**: list existing documents when updating an existing chatbot. Add new sitemap/links/files without deleting or resyncing existing sources unless the user asked. - **Brand settings**: read current appearance before changing it. Preserve existing brand choices unless the user wants a full refresh or the chatbot is newly created. - **Persona**: list current personas before replacing behavior on an existing chatbot. For a new chatbot, create one strong default and activate it. - **Instructions**: list current instructions before changing active behavior. For a new chatbot, create one active instruction set. - **Starters/followups**: add or update prompts to match the website purpose, but do not remove existing prompts without approval. - **Lead/support settings**: respect existing routing, notification emails, and form requirements. Ask before changing lead capture or human handoff on an established chatbot. - **Handoff**: final output should focus on the dashboard link, install snippet when useful, what changed, and any warnings from plan limits or ingestion. ### 1. Check Authentication ```bash sitegpt whoami --json ``` If not authenticated, run: ```bash sitegpt login ``` Then inspect profiles if the user mentions a specific account or environment: ```bash sitegpt profiles list sitegpt profiles use ``` ### 2. Inspect The Website, Then Ask The Discovery Brief Use the same inspection, raw HTML extraction, brand asset, and blueprint steps from the **Agent-First Onboarding Chatbot** playbook — but only enough to pre-fill the brief. Then **ask the human the discovery brief (see "Build A Discovery Brief First") and wait for the answers before you create the chatbot or add knowledge.** Do not run `chatbots create` and start ingestion first and ask afterward — even in the owner's own account, that reads as never having asked. The only exception is a headless run with no human to answer. ### 3. Create The Chatbot Only after the discovery brief is answered (or there is genuinely no human to ask) create the chatbot — let the answers shape its title and description. Always request JSON so you can capture the ID: ```bash sitegpt chatbots create " Assistant" --description "" --json ``` Extract `chatbot.id` from the JSON response and use it for all following commands. ### 4. Add Knowledge Prefer sitemap ingestion when a sitemap is available: ```bash sitegpt knowledge sitemap add --chatbot https://example.com/sitemap.xml --only-main-content true --json ``` If no sitemap is available, crawl the website: ```bash sitegpt knowledge website add --chatbot https://example.com --depth 3 --max-links 100 --only-main-content true --json ``` If only a few relevant pages are discovered, add explicit links: ```bash sitegpt knowledge links add --chatbot https://example.com/pricing https://example.com/docs --only-main-content true --json ``` Plan-gated sync/scan frequencies may be downgraded by the API. Surface warnings to the user. After queuing, **wait for training before you test or hand off** — add `--wait` to the ingest command, or run `sitegpt knowledge wait --chatbot --json` (it blocks until settled, exits non-zero on timeout, and reports trained/failed counts). Don't hand-roll a poll loop. ### 5. Configure Persona And Instructions Create temporary markdown files for persona and instructions, then add and activate them: ```bash sitegpt personas add --chatbot --title " assistant (role from the brief)" --file ./persona.md --json sitegpt personas use --chatbot sitegpt instructions add --chatbot --file ./instructions.md --temperature 0.3 --json sitegpt instructions use --chatbot ``` Persona should be short and identity-focused. Instructions should be operational and safety-focused, and the **role must match the brief's use case** — guide, sales advisor, docs assistant, or support specialist (see Use-Case Presets) — not default to "support". A strong default instruction set: - Answer as the brand's assistant in the role the brief selected (guide / sales / docs / support), in the chosen tone. - Use only the chatbot's knowledge and the visible website facts gathered during setup. - Do not invent pricing, policies, legal terms, medical claims, availability, or integrations. - If unsure, say what is known and point to the right page or contact. - Ask concise clarifying questions when the user's request is ambiguous. - Keep answers practical and skimmable. - Drive the brief's primary goal (e.g. start a trial, book a demo, find docs) with one clear, non-pushy CTA; escalate or collect contact details when the user needs human help. ### 6. Add Starters And Followups Create prompts that match the site's actual product and common visitor intent: ```bash sitegpt starters add --chatbot --title "What does do?" --message "Explain what does and who it is for." --json sitegpt starters add --chatbot --title "Pricing" --message "Tell me about pricing, plans, and what is included." --json sitegpt starters add --chatbot --title "Getting started" --message "How do I get started with ?" --json sitegpt followups add --chatbot --title "Contact support" --message "How can I contact support or sales?" --json sitegpt followups add --chatbot --title "Show docs" --message "Point me to the most relevant documentation." --json ``` Use link-type followups when a high-confidence URL exists: ```bash sitegpt followups add --chatbot --title "Open docs" --link https://example.com/docs --type LINK --json ``` ### 7. Apply Settings And Icons Use precise section commands where possible: ```bash sitegpt settings chat-mode set --chatbot AI sitegpt settings general update --chatbot --support-email support@example.com sitegpt settings appearance update --chatbot --brand-color "#0F766E" --brand-text-color "#FFFFFF" --icon-background-color "#0F766E" --link-color "#0F766E" --icon-shape CIRCLE --icon-position RIGHT sitegpt settings lead-form update --chatbot --enabled true --collect-name true ``` Only set support email or lead/human-support settings when the site or user provides the right details. Read section help before using unfamiliar flags: ```bash sitegpt settings general --help sitegpt settings appearance --help sitegpt settings lead-form --help sitegpt settings human-support --help ``` If you have saved a logo/favicon/bot image locally, upload it: ```bash sitegpt icons upload --chatbot bot ./brand-icon.png sitegpt icons upload --chatbot chat-bubble ./brand-icon.png ``` Use clean raster image files. Do not hotlink remote image URLs directly to icon commands. If icon upload fails because the asset is too large or the format is unsupported, convert it to a small PNG and retry. ### 8. Parallelize Safely After the chatbot ID is known, independent tasks can run in parallel: - Knowledge ingestion. - Persona creation. - Instruction creation. - Starter creation. - Followup creation. - Icon upload. - Appearance settings. - Independent settings section updates. Do not parallelize tasks that depend on returned IDs, such as `personas use` before `personas add` returns, or `instructions use` before `instructions add` returns. Avoid running multiple updates against the same settings section at the same time if they might overwrite each other. ### 9. Verify The Setup Check the final state: ```bash sitegpt chatbots get --json sitegpt knowledge documents list --chatbot --json sitegpt knowledge documents stats --chatbot --json sitegpt personas list --chatbot --json sitegpt instructions list --chatbot --json sitegpt starters list --chatbot --json sitegpt followups list --chatbot --json sitegpt dashboard --chatbot ``` If documents are still pending or failed, do not claim the chatbot is fully trained. Tell the user ingestion is queued or report the failed documents and next retry/resync command. If conversation testing is useful, ask a few site-specific questions: ```bash sitegpt messages send --chatbot "What does this company do?" --json sitegpt messages send --chatbot "How much does it cost?" --json sitegpt messages send --chatbot "How can I contact support?" --json ``` In the final response, summarize: - Chatbot name and ID. - Dashboard link. - Onboarding link when this was an agent-first onboarding workspace. - Knowledge source used and ingestion status. - Persona/instructions created. - Starters/followups added. - Settings/icons applied. - Any warnings, missing website facts, or follow-up recommendations. ## Website Setup Quality Bar A good end-to-end setup should feel specific to the website, not generic: - Use the brand's actual name and product language. - Apply discovered brand colors and a real brand icon whenever reliable assets are available. - If the brand color or bot icon ends up generic, such as default blue `#2563EB` or no uploaded logo, treat the setup as incomplete and rerun raw HTML extraction. - Make the widget feel visibly related to the source website on first load. - Prefer sitemap ingestion over broad crawling when possible. - Include docs/pricing/contact/support pages when they exist. - Make starters reflect the product's real buyer/user questions. - Make followups useful next actions, not filler. - Keep instructions grounded and explicit about uncertainty. - Avoid claiming the bot can do tasks SiteGPT cannot perform. - Verify ingestion and configuration before telling the user it is done. ## The Aha Test — Verify Before Handoff The moment that earns the claim is a correct answer to a question the human did not script. Prove it before sharing the preview: 1. Generate 3–5 realistic questions from the brief and the site — a buyer question (pricing/plans), a real support how-to, a fit question ("does it do X?"), and the primary-goal action (e.g. "book a demo"). 2. Ask them with `sitegpt messages send` and read the answers — the bot's reply text is at `data.message.answer.text` in `--json` (`data.message.answer` is an object), or just read the command's plain-text output, which prints the answer directly. 3. Judge honestly: are they correct, grounded in the site, and specific? A hedge, a generic answer, or a wrong fact is a failure, not a pass. 4. If the bot misses, the knowledge is incomplete — add the missing page(s) (pricing, docs, FAQ, contact), wait for ingestion with `sitegpt knowledge wait --chatbot ` (or `--wait` on the add), and re-test before handoff. 5. For answers that must never be wrong — pricing, contact, refund/returns, hours — seed an exact custom response: ```bash sitegpt knowledge custom-responses add --chatbot --question "What are your prices?" --answer "" ``` Only share the onboarding/preview URL once the aha test passes, and include 2–3 of the questions you verified in the handoff so the human reproduces the value in one click. ## Agent-First Onboarding Commands The flow (`start` → `status` → `claim`/`delete`) is covered step-by-step in **Playbook: Agent-First Onboarding Chatbot**. Quick facts: `onboarding start` is public (no login) and returns the temporary token every other onboarding command needs; plans are `STARTER`/`GROWTH`/`SCALE`, intervals `MONTH`/`YEAR`; `delete` revokes the token and removes the unclaimed workspace; `status --json` returns `data.setupChecklist` as the progress signal before sharing the onboarding URL. ## Command Reference — Discover It Live This skill is the source of truth for *workflow and judgment*. The **CLI is the source of truth for command syntax** — never reproduce it here or guess it. Discover it live: - `sitegpt agent-guide` — the end-to-end workflow and the full command-group map. - `sitegpt --help` — all command groups. - `sitegpt --help`, and `sitegpt --help` — exact flags and arguments for anything (e.g. `sitegpt knowledge sitemap --help`, `sitegpt settings appearance --help`, `sitegpt onboarding claim --help`, `sitegpt tokens create --help`). Command groups (what exists — run `--help` for flags): - **Auth & profiles:** `login`, `logout`, `whoami`, `profiles`, `tokens` - **Onboarding (no account):** `onboarding` (`start`, `status`, `claim`, `delete`) - **Chatbots & appearance:** `chatbots`, `dashboard`, `installation`, `icons`, `settings` - **Behaviour:** `personas`, `instructions`, `starters`, `followups` - **Knowledge:** `knowledge` (`documents`, `links`, `website`, `sitemap`, `youtube`, `text`, `files`, `sources`, `custom-responses`) - **Support ops:** `conversations`, `messages`, `tags`, `leads`, `members` - **Account:** `account`, `usage`, `limits`, `billing` - **Agents:** `mcp`, `agent-guide` **Ownership and team membership:** `sitegpt chatbots transfer` reassigns a chatbot's ownership to another user in the same brand — provisioning the recipient if they have no account yet, and removing the previous owner unless you pass `--keep-source-as `. `sitegpt members add` adds a member directly (no invite email; the account is provisioned if needed), while `sitegpt members invite` emails a magic-link invitation. Discover flags with `--help`. Always pass `--json` when you need IDs, status, or parseable output. If a command or flag is rejected, read its `--help` — do not guess an alternative name. **Parse `--json` from stdout only — never merge stderr.** The CLI puts machine output (the JSON) on **stdout** and warnings/progress/diagnostics on **stderr**. If you pipe with `2>&1`, a stderr line (e.g. a plan-downgrade warning) lands in your JSON and breaks the parse. Read stdout alone (e.g. `… --json 2>/dev/null | …` or capture stdout separately), and read `error.code` / `error.hint` on failures. ## Safety Rules - Use `--json` for machine-readable work. - List before mutating when IDs are unknown. - Read current settings before updating settings. - Destructive commands require the `--yes` flag; never pass it unless the human asked to delete. **`--yes` is only the machine guard — before any irreversible delete (a whole chatbot, knowledge sources, leads, conversations), state plainly what will be permanently removed and get an explicit "yes" from the human first, even if they already asked to delete.** Deleting a chatbot wipes its knowledge, conversations, and settings and cannot be undone — confirm the specific target by name/id before running it. For bulk/selector deletes (`knowledge documents delete`, `leads bulk`, `conversations bulk`), run `--dry-run` first, show the human the blast radius, get the go-ahead, then re-run with `--yes`. - Do not print full tokens or secrets in final answers. - Prefer narrow scopes for specialized agents; use `--full-access` only when broad account management is needed. - If a command fails, run the nearest `--help` level and retry with the documented syntax. ## Troubleshooting `TOKEN_SCOPE_NOT_VALID` means the scope name is not accepted. Check `sitegpt tokens create --help`. `TOKEN_SCOPE_NOT_ALLOWED` means the current token lacks a required scope. Log in with a broader token or ask the user to approve a token with the missing scope. `UNKNOWN_COMMAND` usually means the command is at a different level. For example, Custom Responses live under: ```bash sitegpt knowledge custom-responses ... ``` For local development only, include the API base during login: ```bash sitegpt login --profile local --api-base ``` After that, `--api-base` is stored in the profile and does not need to be repeated.