cgctl is the panel's command-line client, installed on the server in /usr/local/bin. For scripts it uses an API token: a cgt_… credential that acts as the administrator who created it, with no password and no code on every call.

A token can do everything its owner can, except manage accounts, users, tokens and the site shell: those need a session signed in with a password. So a stolen token cannot create another token or an administrator.

Create a token

Tokens are created signed in with the password, because a token cannot create others.

1. In the panel open Security (your account's menu), API tokens card.
2. Type the Name, a label of 1 to 64 characters to recognise the token in the list.
3. In Expires pick 30 days, 90 days, 365 days or never expires.
4. Press Create token.

The panel shows the cgt_… value once. Copy it now: the panel never shows it again. It keeps only a fingerprint of it.

With cgctl, on the server as root:

bash

export CLOUDGROUND_EMAIL='<email>'
read -rs CLOUDGROUND_PASSWORD && export CLOUDGROUND_PASSWORD
cgctl tokens create "<name>" 90

• 90 is the lifetime in days, 1 to 365. Without a lifetime, or with 0, the token never expires.
• If your account has two-step verification, add CLOUDGROUND_TOTP='<code>' with a code from the app.

The answer holds the token field, with the cgt_… value.

Set cgctl up

On the server, write the token into cgctl's configuration file, readable by root only:

bash

install -m 0600 /dev/null /etc/cloudground/cgctl.env
echo "CLOUDGROUND_TOKEN=cgt_…" > /etc/cloudground/cgctl.env
cgctl status

Without CLOUDGROUND_URL, cgctl talks to the panel on the local socket unix:///run/cloudground/api.sock. Environment variables win over the file: for a single command, CLOUDGROUND_TOKEN=cgt_… cgctl status is enough. Instead of the token you can name a file that holds it, with CLOUDGROUND_TOKEN_FILE.

Use cgctl from another computer

Copy cgctl to your computer and give it the panel's HTTPS address:

bash

export CLOUDGROUND_URL='https://<panel-domain>'
export CLOUDGROUND_TOKEN='cgt_…'
cgctl sites list

cgctl verifies the certificate. On the https://<ip>:8443 address, whose certificate is self-signed, it needs CLOUDGROUND_INSECURE=1: better to give the panel a domain. http:// is accepted only to an address local to the computer.

Wait for a task to finish

Many commands start a background task. With --wait cgctl follows it to the end and exits with code 0 only if it succeeded:

bash

cgctl --wait backup run <site-id>

The full list of commands, variables and exit codes is in the CLI reference.

List and revoke tokens

bash

cgctl tokens list
cgctl tokens revoke <token-id>

These commands also need email and password and, like tokens create, must run with CLOUDGROUND_URL='https://127.0.0.1:8443'. In the panel, Revoke on the token's row in Security does the same. Any administrator can revoke any token. The panel revokes an account's tokens by itself when its password is changed or reset, when it turns two-step verification off, when it is disabled, demoted or deleted, and with panel-api recover-admin.

Creation, revocation and every action taken with a token appear in the Audit log, with the token's name.

Next step

Limit who can reach the server with the firewall.