Chatbot CLI: Provision a Support Chatbot From Your Terminal

Standing up a support chatbot usually means a signup form, a dashboard tour, a crawl you watch a progress bar for, and a copy-paste snippet at the end. Fifteen minutes, most of it waiting.

The same thing is one command from a terminal, and the first working bot happens before anyone has signed up for anything.

What the CLI is for, and who it is not for

The CLI covers the work that is annoying to do by hand and worse to do repeatedly: provisioning, training, configuration, and the checks you want to run before shipping.

It is the right tool if you are one of these people.

It is the wrong tool for browsing conversations, reading analytics visually, or tuning appearance by eye. Those are dashboard jobs. The CLI can read conversations and leads, but a terminal is a poor place to skim fifty transcripts.

Install and authenticate

The package is public on npm and needs Node 18 or newer.

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

0.2.3

There are two ways to authenticate, and the difference matters more than it looks.

No account yet. Skip login entirely. The onboarding flow in the next section returns its own token, scoped to the temporary workspace it creates.

Account you already own. Run sitegpt login, or set SITEGPT_API_TOKEN in the environment. Keep the token out of the command line itself, where it lands in shell history and CI logs. Scoped tokens are created with sitegpt tokens create, which takes repeatable --scope and --chatbot flags plus --expires-in-days, so an automation token can be restricted to one bot and expire on its own.

If you run a command with no credentials, the failure is explicit rather than a stack trace:

sitegpt whoami --json

{
  "ok": false,
  "error": {
    "code": "PROFILE_NOT_CONFIGURED",
    "message": "Run `sitegpt login --token <token>` or set SITEGPT_API_TOKEN.",
    "hint": "No account yet? `sitegpt onboarding start <website-url>` is public and returns a temporary token, build a preview chatbot with no login."
  }
}

Named profiles (sitegpt profiles, then -p <name> on any command) keep a client account and your own account apart, which is the difference between a clean agency workflow and a nervous one.

Zero to a trained bot in one command

This is the command that removes the signup from the critical path:

sitegpt onboarding start https://sitegpt.ai --json

Real output, trimmed to the fields you actually use downstream, with the token truncated:

{
  "ok": true,
  "data": {
    "workspace": {
      "id": "7bb665c3-cd09-4404-85e1-47f948b3b778",
      "chatbotId": "b454b036-6a68-4088-81eb-817ed2adba64",
      "status": "CREATED",
      "createdVia": "AGENT",
      "expiresAt": "2026-08-26T08:12:59.144Z",
      "chatbot": {
        "title": "sitegpt.ai AI",
        "description": "AI customer support chatbot prepared from https://sitegpt.ai/"
      }
    },
    "apiToken": "sgpt_ee3a87f7f091_...",
    "mcpUrl": "https://sitegpt.ai/mcp",
    "onboardingUrl": "https://sitegpt.ai/onboarding/preview/7bb665c3-cd09-4404-85e1-47f948b3b778",
    "expiresAt": "2026-08-26T08:12:59.144Z"
  }
}

Four things came back that a script needs: a workspace id, a chatbot id, a token scoped to that workspace, and a URL a human can open to see the bot and claim it.

The preview is real, not a mock. It also has real limits, which is the honest way to read it: running sitegpt limits against that workspace on 2026-08-19 showed a 200 page and 50 message allowance, and the workspace expires seven days after creation. It exists so somebody can see a working bot on their own content before deciding anything.

Three commands manage the rest of that lifecycle: sitegpt onboarding status <workspace-id> prints a setup checklist, sitegpt onboarding claim <workspace-id> moves it into a real account, and sitegpt onboarding delete <workspace-id> --yes throws it away and revokes the token.

Adding knowledge, and waiting for training to finish

sitegpt knowledge is the biggest command group, because content is the product: website, sitemap, links, youtube, text, files, documents, sources for connections like GitHub and Confluence, and custom-responses for answers that must be exactly right.

A crawl, capped and blocking until it settles:

export SITEGPT_API_TOKEN=sgpt_...
sitegpt knowledge website add https://sitegpt.ai \
  --chatbot "$CHATBOT_ID" --depth 1 --max-links 20 --wait --timeout 420 --json

{
  "ok": true,
  "data": {
    "ingestJobRunId": "fc6145ca-e067-4b43-a061-8c100eb942fc",
    "source": "WEBSITE",
    "requested": { "url": "https://sitegpt.ai", "maxDepth": 1, "maxLinks": 20 },
    "training": { "settled": true, "pending": 0, "trained": 20, "failed": 0, "total": 20 }
  }
}

That training block is the whole reason to use --wait. Without it, the command returns as soon as the ingest job is queued, and the next line of your script reads a chatbot with nothing in it yet. With it, the process blocks until settled is true, and trained, failed, and total tell you whether to ship or investigate.

--wait is available on the add commands, and sitegpt knowledge wait --chatbot <id> does the same thing standalone. Both accept --timeout <seconds>, defaulting to 600.

The crawl flags are worth knowing before you point this at a large site:

--sync is the flag most people skip and then regret. Content that is not refreshed is the most common reason a bot that tested well starts hedging three months later.

Getting the embed snippet and shipping it

sitegpt installation snippet --chatbot "$CHATBOT_ID"

Chat URL: https://widget.sitegpt.ai/c/b454b036-6a68-4088-81eb-817ed2adba64
Widget script URL: https://widget.sitegpt.ai/widget/b454b036-6a68-4088-81eb-817ed2adba64.js

<script type="text/javascript">window.$sitegpt=[];(function(){d=document;s=d.createElement("script");s.src="https://widget.sitegpt.ai/widget/b454b036-6a68-4088-81eb-817ed2adba64.js";s.async=1;d.getElementsByTagName("head")[0].appendChild(s);})();</script>

Add --json and the same three values come back as chatUrl, widgetScriptUrl, and embedCode, which is what you want when a template or a deploy step is going to write the snippet into a layout file.

Before you paste it anywhere, ask the bot something from the terminal:

sitegpt messages send "What content sources can SiteGPT train on?" --chatbot "$CHATBOT_ID"

Started conversation dbc82b42-ee5d-40ed-b118-950dc60ea514 and sent message e2450d68-2556-4ae7-9ae5-77ef60c0cc2b.
SiteGPT can train on a wide range of content sources including website URLs, sitemaps, YouTube videos/playlists/channels, raw text, and file uploads such as CSV, TXT, PDF, DOCX, PPTX, and Markdown files. You can also connect sources like Notion, Google Drive, Dropbox, OneDrive, Box, and GitHub to import training data.

That is the acceptance test. If the answer hedges, the fix is knowledge, not prompt wording: add the missing source, or pin the answer with sitegpt knowledge custom-responses for facts that must never be paraphrased, such as pricing and contact details.

Scripting it: JSON output and exit codes

Every command accepts the global flags, and three of them carry the automation story.

Failures exit non-zero. A missing token, an unauthenticated read, and an unknown command all exited 1 when tested, and the JSON envelope carries the reason in error.code rather than in prose you would have to grep. That combination is what makes the sequence safe to put in a pipeline:

#!/usr/bin/env bash
set -euo pipefail

CHATBOT_ID=$(sitegpt chatbots create "$CLIENT" --json | jq -r .data.chatbot.id)

sitegpt knowledge sitemap add "$SITE/sitemap.xml" \
  --chatbot "$CHATBOT_ID" --sync weekly --wait --json > /dev/null

sitegpt installation snippet --chatbot "$CHATBOT_ID" --json | jq -r .data.embedCode

With set -e, any failed step stops the job instead of shipping a snippet for an untrained bot. Shell completion comes from sitegpt completion bash or sitegpt completion zsh, sourced from your shell rc.

Running it from a coding agent

The CLI was built with agents in mind, and it shows in two places most tools skip.

sitegpt agent-guide prints the workflow and command map an agent should follow, including the instruction to run sitegpt <group> --help for exact flags rather than guessing a command name. SiteGPT also publishes a skill file at sitegpt.ai/agents/sitegpt-cli-skill.md and an auth discovery file at sitegpt.ai/auth.md, so an assistant can learn the whole surface without a human pasting documentation into a chat.

The second piece is the missing login. Because onboarding start is public, an agent can go from a URL to a working, branded, tested chatbot and then hand a human the claim link. Nothing in that loop requires credentials the agent should not have.

SiteGPT publishes setup guides for the clients people drive it from: Claude Code in the terminal next to the repo, Cursor in the editor, Codex in CI pipelines, OpenClaw for always-on agents that own support ops, and Hermes for agents that hold the role across sessions. The wider picture of what an assistant can operate end to end lives on the agents page.

Local MCP against remote MCP

Both paths let an AI assistant operate SiteGPT. They are not interchangeable, and picking wrong costs an afternoon.

The remote server at sitegpt.ai/mcp-server is hosted, authenticates over browser-based OAuth, and needs no install. sitegpt mcp runs the same server locally over stdio for clients that spawn a process. Claude is the confirmed MCP client today. For what changes about the day-to-day work once an assistant can act rather than describe, see MCP for customer service, and for the Claude setup itself, the step-by-step guide.

Once the bot is live, the questions worth asking it are a separate skill, and these ten analytics questions are a good starting set.

Frequently asked questions

Do I need a SiteGPT account to use the CLI? Not to start. sitegpt onboarding start <website-url> is public and returns a temporary workspace, a trained preview chatbot, a scoped token, and a claim link. The workspace expires after seven days and carries a small allowance, 200 pages and 50 messages when tested on 2026-08-19.

Which plan do I need for CLI access to an existing account? Authenticating against an account you own uses an API token, and the pricing page lists API Access on Growth and above. Growth is $79 per month billed yearly, or $129 billed monthly, with a 7-day free trial on every plan.

How do I make a script wait for training? Pass --wait to a knowledge add command, or run sitegpt knowledge wait --chatbot <id>. Both accept --timeout <seconds> and default to 600.

Is the CLI free? Yes, it is published on npm as @sitegpt/cli. Running a production chatbot uses your plan.

Can it manage many chatbots at once? That is what it is for. Named profiles, scoped tokens, --json output, and non-zero exits on failure are all there so one script can provision and update dozens of bots.

The install is one line, and the first bot does not need the trial at all. npm install -g @sitegpt/cli, point it at a URL, and read the answer it gives you before deciding anything else.