Skip to content

Configuration Commands

The config command group manages the CLI's global configuration settings stored in ~/.sites-cli.

Overview

Configuration commands allow you to: - View current configuration settings - Set the base URL for the Sites service - Configure default output format - Enable/disable automatic upgrade checks - Control TLS certificate verification

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 config show

Display the current CLI configuration.

Usage: 

sitesctl config show

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

Examples: 

# Show current configuration
sitesctl config show

# Show configuration as JSON
sitesctl config show --output json

# Show configuration as YAML
sitesctl config show --output yaml

What it does: - Reads and displays settings from ~/.sites-cli - Shows base URL, output format, auto-upgrade status, and other settings - Does not display sensitive tokens (use with caution in shared environments)

Configuration File Location: - Linux/macOS: ~/.sites-cli - The file is created automatically on first use with default settings - File permissions are set to 0600 (read/write for owner only)

sitesctl config base-url

Set the base URL for the Sites service.

Usage: 

sitesctl config base-url --value <url>

Flags: - --value, -v (required) - Base URL for the Sites service

Examples: 

# Set production URL (default)
sitesctl config base-url --value=https://sites.ecmwf.int

# Set staging URL
sitesctl config base-url --value=https://sites-stage.ecmwf.int

# Set custom URL
sitesctl config base-url --value=https://custom-sites.example.com

What it does: - Sets the base URL used for all API requests - Updates ~/.sites-cli configuration file - Default value: https://sites.ecmwf.int

Use Cases: - Testing against staging environments - Using custom Sites deployments - Development and testing

sitesctl config output

Set the default output format for all commands.

Usage: 

sitesctl config output --value <format>

Flags: - --value, -v (required) - Output format: json, yaml, or table

Examples: 

# Set output to JSON
sitesctl config output --value=json

# Set output to YAML
sitesctl config output --value=yaml

# Set output to table (default, human-readable)
sitesctl config output --value=table

What it does: - Sets the default output format for all commands - Updates ~/.sites-cli configuration file - Can be overridden per-command with --output flag

Output Format Details:

  • table (default)
  • Human-readable tabular output
  • Best for interactive terminal use

  • Headers and formatted columns

  • json

  • Machine-readable JSON format
  • Best for scripting and automation

  • Easy to parse with tools like jq

  • yaml

  • Human-readable YAML format
  • Good balance between readability and structure
  • Useful for configuration files

sitesctl config auto-upgrade

Enable or disable automatic upgrade checks.

Usage: 

sitesctl config auto-upgrade --value <true|false>

Flags: - --value, -v (required) - Enable (true) or disable (false) auto-upgrade

Examples: 

# Enable automatic upgrade checks (default)
sitesctl config auto-upgrade --value=true

# Disable automatic upgrade checks
sitesctl config auto-upgrade --value=false

What it does: - Controls whether the CLI checks for updates automatically - When enabled, checks occur randomly (~10% of command executions) - Updates ~/.sites-cli configuration file - Default value: true

Behavior: - If auto-upgrade is enabled, the CLI occasionally checks for newer versions - Automatic checks only happen on a small percentage of runs to avoid slowdowns - If a newer version is found during a check, the CLI downloads and replaces the binary - The new version takes effect on the next CLI invocation - Manual upgrades are always available via sitesctl upgrade-cli

sitesctl config insecure

Enable or disable TLS certificate verification.

Usage: 

sitesctl config insecure --value <true|false>

Flags: - --value, -v (required) - Skip verification (true) or enforce verification (false)

Examples: 

# Disable TLS verification (insecure, not recommended)
sitesctl config insecure --value=true

# Enable TLS verification (default, recommended)
sitesctl config insecure --value=false

What it does: - Controls whether TLS/SSL certificates are verified - Updates ~/.sites-cli configuration file - Default value: false (verification enabled)

⚠️ Security Warning:

Setting this to true disables TLS certificate verification, which: - Makes connections vulnerable to man-in-the-middle attacks - Should only be used in controlled development environments - Is NOT recommended for production use - Can expose your credentials and data

When to use: - Testing with self-signed certificates - Development environments with custom CAs - Troubleshooting certificate issues (temporarily)

Alternative: Instead of disabling verification, consider: - Adding the CA certificate to your system's trust store - Using a properly signed certificate - Using the --insecure flag for one-off commands instead of global config

Configuration File

The configuration is stored in ~/.sites-cli as a YAML file.

Example configuration: 

global:
  baseURL: https://sites.ecmwf.int
  output: table
  autoUpgrade: true
  insecureSkipVerify: false
oidc:
  token: eyJhbGc...  # OIDC token from auth login
tokens:
  myspace/mysite: abc123...  # Site-specific tokens

File Permissions: - The file is created with 0600 permissions (owner read/write only) - Keep this file secure as it contains authentication tokens - Do not commit it to version control

Resetting Configuration: - To reset to defaults, delete the file: rm ~/.sites-cli - The file will be recreated with defaults on next use - This will also remove all stored tokens (you'll need to login again)

Configuration Precedence

Configuration values are resolved in this order (highest priority first):

  1. Command-line flags (e.g., --output json)
  2. Environment variables (e.g., ECMWF_USERNAME)
  3. Configuration file (~/.sites-cli)
  4. Built-in defaults

Example: 

# Config file has output=table
# This command uses JSON (flag overrides config)
sitesctl list --output json

See Also