Start with the basics:
Use --json when you need exact error details:
The CLI opens the wrong SiteGPT URL
Check your active profile:
If a local profile is default, switch back to production:
Or log in again with the production API base:
Environment variables override saved profiles:
Unset them if they point to a local environment.
Then retry:
Unexpected token '<' ... is not valid JSON
This usually means the CLI expected an API JSON response but received an HTML page. Common causes:
SITEGPT_API_BASE points to the wrong host.- A saved profile uses a local API base.
- You are using an old CLI version.
- The API route is not deployed yet in the selected environment.
Fix:
Permission or scope errors
Example:
Check the command’s required area and create a token with the right scopes:
If the token is chatbot-scoped, confirm the chatbot is included:
Token creation is role-aware. If your dashboard role cannot access a chatbot or action, your token cannot grant that access either.
A command says UNKNOWN_COMMAND
Use contextual help at the level you are on:
Also verify the command name. For example:
IDs are shortened in table output
Human table output may shorten long IDs. Use JSON for complete IDs:
Profiles from local testing still appear
This is expected. Profiles are stored locally at:
Delete profiles you no longer use:
This only deletes local credentials. Revoke the server-side token separately if needed:
Knowledge documents are still processing
Check dashboard summary and document status:
Resync failed documents:
Raw or parsed file URLs are empty
rawFileUrl and parsedTextFileUrl are available only when the underlying ingested document has those files. For some sources or older documents, these fields can be null.
To fetch document details and content when available:
Source connection authorized but no documents show
For picker-based connectors, rerun authorization on the existing source to select more files:
For Notion, page/database selection happens inside Notion authorization. If no pages were selected, documents may remain empty until you authorize again and select pages.
File upload command fails
Use local file paths:
If the asset is remote, download it first and then pass the local path.
Token was created but the CLI still uses an old token
Creating a token does not automatically switch your local profile. Save it with:
Or create a separate profile:
Need a clean production profile
Useful debug commands
