CLI authentication

This page covers CLI behavior only. Tokens, scopes, access levels, and the device login flow are described in Authentication. To log in for the first time, see Install the CLI and log in.

Credential sources

Commands that read or change your account send an API token. sitegpt onboarding start does not need a token. The CLI gets the token from one of these sources.

Source	How you set it	Typical use
Device login	`sitegpt login`	Your own computer with a browser.
Saved token	`sitegpt login --token YOUR_API_TOKEN`	Servers, CI, and machines without a browser.
Environment variable	`SITEGPT_API_TOKEN=YOUR_API_TOKEN sitegpt ...`	One-off scripts, containers, and onboarding tokens.

Which token and URL the CLI uses

Condition	Token	API base URL
`SITEGPT_API_TOKEN` is set	`SITEGPT_API_TOKEN`. Saved profiles are ignored.	`--api-base`, else `SITEGPT_API_BASE`, else `https://sitegpt.ai`
`SITEGPT_API_TOKEN` is not set	The token in the selected profile	`--api-base`, else `SITEGPT_API_BASE`, else the URL saved in the profile
No token and no saved profile	None. The command fails with `PROFILE_NOT_CONFIGURED`.

The selected profile is --profile, else SITEGPT_PROFILE, else the default profile. See Profiles.

Option	Applies to	Description
`--profile <name>`	Both	Save the token in this profile. The profile becomes the default.
`--api-base <url>`	Both	Save this API base URL in the profile. The default is `https://sitegpt.ai`.
`--token <token>`	Saved token	Save an existing token. No browser approval.
`--full-access`	Device login	Ask for full account access.
`--scope <scope>`	Device login	Ask for one scope. Repeat for more scopes.
`--chatbot <chatbot-id>`	Device login	Limit the token to one chatbot. Repeat for more chatbots.
`--name <name>`	Device login	Token name. The default is `SiteGPT CLI (<profile>)`.
`--expires-in-days <days>`	Device login	Token lifetime in days, from 1 to 365. The default is 90.

With no access option, device login asks for standard CLI access. Authentication lists the scopes in each access level.

Option rules

Rule	Error code
`--full-access` and `--scope` cannot be used together.	`OPTIONS_CONFLICT`
`--token` cannot be used with `--full-access`, `--scope`, `--chatbot`, `--name`, or `--expires-in-days`.	`OPTIONS_CONFLICT`

sitegpt login prints these lines to the terminal. It does not open a browser.

Line	Meaning
`Requesting Standard CLI access.`	The access level asked for. It shows `Full account access` or `Custom permissions` when you use `--full-access` or `--scope`.
`Open <url>`	The approval page. Open it in any browser.
`Enter code: <code>`	The code shown on the approval page.
`Waiting for approval...`	The CLI checks for your approval until the code expires.
`Logged in to <api-base> as profile "<name>".`	Approval is complete and the token is saved.

If the code expires first, the command fails with DEVICE_LOGIN_EXPIRED. With --json, the progress lines go to stderr and the result shows the token ID, name, prefix, scopes, chatbot IDs, and expiry.

Where tokens are stored

Item	Value
Config file	`~/.config/sitegpt/config.json`
Config file with `XDG_CONFIG_HOME` set	`$XDG_CONFIG_HOME/sitegpt/config.json`
File permissions	The CLI creates the file as readable and writable by your user only (`0600`).
Contents	Each profile’s name, API base URL, and token, plus the default profile name

Do not commit this file to source control.

Log out and revoke

Action	Command	Effect
Log out	`sitegpt logout`	Deletes the active profile from the config file. The token still works in SiteGPT.
Revoke	`sitegpt tokens revoke <token-id>`	Stops the token in SiteGPT. You can also revoke it on the Agents page.

Token commands

Command	Description
`sitegpt tokens list`	List your API tokens. Add `--include-revoked` to show revoked tokens.
`sitegpt tokens create`	Create a token. The new token shows once.
`sitegpt tokens rotate <token-id>`	Issue a new secret for a token. The new secret shows once.
`sitegpt tokens revoke <token-id>`	Revoke a token.

list needs the tokens:read scope. create, rotate, and revoke need tokens:write. Standard CLI access does not include tokens:write. Creating a token does not switch the CLI to it. Save it with sitegpt login --token, or set SITEGPT_API_TOKEN. All options are in the command reference.

Scope sets for common jobs

Use the smallest set that does the job. Add --chatbot <chatbot-id> to limit a token to one chatbot.

Job	Suggested profile name	Scopes
List chatbots only	`inventory`	`account:read`, `chatbots:read`
Set up a chatbot	`setup-agent`	`chatbots:read`, `chatbots:write`, `knowledge:read`, `knowledge:write`, `settings:write`, `personas:write`, `instructions:write`, `starters:write`, `followups:write`
Maintain content	`knowledge-agent`	`account:read`, `chatbots:read`, `knowledge:read`, `knowledge:write`, `knowledge:delete`
Handle support	`support-agent`	`account:read`, `chatbots:read`, `conversations:read`, `conversations:write`, `leads:read`, `leads:write`
Review account and team	`account-agent`	`account:read`, `chatbots:read`, `billing:read`, `members:read`

A token cannot do more than your dashboard role allows. The full scope list is on Authentication.

Get started

Chatbot setup

Operations

Agent playbooks

Reference

Credential sources

Which token and URL the CLI uses

Option rules

Where tokens are stored

Log out and revoke

Token commands

Scope sets for common jobs

​Credential sources

​Which token and URL the CLI uses

​Login options

​Option rules

​Device login output

​Where tokens are stored

​Log out and revoke

​Token commands

​Scope sets for common jobs

Credential sources

Which token and URL the CLI uses

Login options

Option rules

Device login output

Where tokens are stored

Log out and revoke

Token commands

Scope sets for common jobs