Skip to content

Authentication Commands

The auth command group provides authentication and token management functionality for the Sites CLI.

Overview

Authentication commands allow you to: - Login with ECMWF credentials - Logout and revoke tokens - Check your current authentication status - Store a platform-wide hub token - Store site-specific tokens

Global Flags

All commands support these global flags:

  • --debug, -d, --verbose - Show debug information
  • --insecure, -k - Skip TLS certificate verification (insecure)
  • --force, -f, -y, --yes - Force operations without prompting
  • --output, -o - Output format: json, yaml, or table (default: table)

Commands

sitesctl auth login

Authenticate with ECMWF credentials and save the OpenID Connect (OIDC) token.

Usage: 

sitesctl auth login --username <username> [--password <password>]

Flags: - --username, -u (required) - ECMWF username - Can also be set via ECMWF_USERNAME environment variable - --password, -p (optional) - ECMWF password - Can also be set via ECMWF_PASSWORD environment variable - If not provided, you will be prompted securely

Examples: 

# Login with username (will prompt for password)
sitesctl auth login --username myuser

# Login with username and password
sitesctl auth login --username myuser --password mypassword

# Using environment variables
export ECMWF_USERNAME=myuser
export ECMWF_PASSWORD=mypassword
sitesctl auth login --username $ECMWF_USERNAME --password $ECMWF_PASSWORD

What it does: - Authenticates with the ECMWF authentication service - Retrieves an OpenID Connect token - Stores the token in ~/.sites-cli configuration file - The token is used automatically for subsequent commands

sitesctl auth logout

Revoke the current OpenID Connect token and clear it from local storage.

Usage: 

sitesctl auth logout

Flags: - No additional flags (uses global flags only)

Examples: 

# Logout and revoke token
sitesctl auth logout

# Logout without confirmation prompt
sitesctl auth logout --force

What it does: - Revokes the current OIDC token on the server - Removes the token from ~/.sites-cli configuration file - You will need to login again to use authenticated commands

sitesctl auth whoami

Display information about the current authentication token and user.

Usage: 

sitesctl auth whoami

Flags: - No additional flags (uses global flags only)

Examples: 

# Check current authentication status
sitesctl auth whoami

# Check with JSON output
sitesctl auth whoami --output json

# Check with detailed debug information
sitesctl auth whoami --debug

What it does: - Verifies the current token with the authentication service - Displays user information associated with the token - Shows token expiration and validity status

sitesctl auth site-token

Store a site-specific token (master token or HTTP access token) in the local configuration for use with site content operations.

Usage: 

sitesctl auth site-token --space <space> --name <name> --token <token>

Flags: - --space (required) - Site space identifier - --name (required) - Site name - --token, -t, -v, --value (required) - Site authentication token or HTTP access token

Examples: 

# Save a site token
sitesctl auth site-token --space myspace --name mysite --token abc123token

# Using environment variable for token
export MASTER_TOKEN=abc123token
sitesctl auth site-token --space myspace --name mysite --token $MASTER_TOKEN

What it does: - Stores the token in ~/.sites-cli configuration file - The token is associated with the specific space/name combination - When you run site content commands, the CLI will automatically use this token if available - This is useful when you have a master token or HTTP access token for a specific site

Site Content Token Priority:

When performing site content operations, the CLI looks for tokens in this order: 1. --api-authentication-token flag (if provided) 2. Site-specific token (set via auth site-token) 3. OIDC token (from auth login) 4. Environment variables: API_AUTHENTICATION_TOKEN, MASTER_TOKEN, or HTTP_ACCESS_TOKEN

sitesctl auth hub-token

Store a platform-wide hub administrator token in the local configuration for hub API operations.

Usage: 

sitesctl auth hub-token --token <token>

Flags: - --token, -t, -v, --value (required) - Hub administrator token

Examples: 

# Save the platform hub token
sitesctl auth hub-token --token hub_admin_token

# Using environment variable input
export HUB_TOKEN=hub_admin_token
sitesctl auth hub-token --token $HUB_TOKEN

What it does: - Stores the token in ~/.sites-cli configuration file - Makes the token available for hub API operations such as list/create/delete/update site actions - Intended for hub administrators with platform-wide privileges

Hub Token Priority:

When performing hub operations, the CLI looks for tokens in this order: 1. --hub-token flag (if provided) 2. Stored hub token (set via auth hub-token) 3. OIDC token (from auth login)

Hub operations do not fall back to site-specific tokens.

Environment Variables

The following environment variables are supported:

  • ECMWF_USERNAME - Default username for login
  • ECMWF_PASSWORD - Default password for login
  • HUB_TOKEN - Hub administrator token for hub operations
  • API_AUTHENTICATION_TOKEN - Master token for site operations
  • MASTER_TOKEN - Alias for API_AUTHENTICATION_TOKEN
  • HTTP_ACCESS_TOKEN - HTTP access token for site operations

Token Storage

Tokens are stored in ~/.sites-cli configuration file with restricted permissions (0600). This file stores: - OpenID Connect token (from auth login) - Hub token (from auth hub-token) - Site-specific tokens (from auth site-token) - Other CLI configuration settings

Security Note: Keep your ~/.sites-cli file secure. Do not share it or commit it to version control.

See Also