Sites CLI Documentation¶

Complete command reference for the Sites Command Line Interface (CLI).

Table of Contents¶

• Getting Started
• Command Reference
• Quick Links
• Common Workflows
• Support

Overview¶

The Sites CLI (SitesCTL) is a command-line tool for managing sites and their content on the ECMWF Sites platform. It provides comprehensive functionality for:

• Site lifecycle management (create, update, delete)
• Content management (upload, download, list, delete files)
• Access control and authentication
• Token management
• Signed URLs for sharing
• Configuration management

Token lifecycle note: Rotating or revoking a site's master token invalidates all HTTP access tokens and signed URLs derived from it.

Getting Started¶

Installation¶

Download the CLI from the ECMWF repository:

Linux:

curl -L https://get.ecmwf.int/repository/sites-cli/linux/sites-linux-amd64-20260331.1126 --output sitesctl
chmod +x sitesctl
sudo mv sitesctl /usr/local/bin/sitesctl

macOS:

curl -L https://get.ecmwf.int/repository/sites-cli/darwin/sites-darwin-amd64-20260331.1126 --output sitesctl
chmod +x sitesctl
sudo mv sitesctl /usr/local/bin/sitesctl

First Steps¶

1. Login:

   sitesctl auth login --username your-username
   

2. List your sites:

   sitesctl list --owner your-username
   

3. Create a site:

   sitesctl create --name mysite --template iver
   

4. Upload content:

   sitesctl site --space myspace --name mysite content upload --source ./myfiles
   

Configuration¶

Configure CLI defaults:

sitesctl config show                          # View current config
sitesctl config output --value json           # Set default output format
sitesctl config auto-upgrade --value true     # Enable auto-upgrade checks

Command Reference¶

Authentication & Configuration¶

Full Documentation: - Authentication Commands - Configuration Commands

Site Management¶

Full Documentation: - List Sites - Browse and filter sites - Create Site - Create new sites - Delete Site - Remove sites

Content Management¶

Full Documentation: - Site Content Commands - Complete file management guide

Site Configuration Updates¶

Full Documentation: - Site Update Commands - Comprehensive configuration management

Token Management¶

Full Documentation: - Site Token Management - Master tokens, HTTP access tokens, revocation, and token history

Signed URLs¶

Full Documentation: - Signed URLs - Time-limited file access

Utility Commands¶

Full Documentation: - CLI Upgrade - Keeping the CLI up to date - Miscellaneous Commands - Utility functions

Quick Links¶

By Task¶

I want to...

• Get started: Authentication → Create Site → Upload Content
• Upload files: Content Upload
• Download files: Content Download
• Share a file temporarily: Signed URLs
• Share site access: HTTP Access Tokens
• Update site settings: Site Update Commands
• Control who can access: Access Control
• Check site status: Health Check
• Troubleshoot: Check specific command documentation for troubleshooting sections

By Role¶

Site Owner: - Create Sites - Manage Access Control - Token Management - Delete Sites

Content Manager: - Upload Files - Download Files - Manage Files - Create Symlinks

Collaborator: - List Sites - View/Download Content - Use Shared Tokens

Developer: - API Authentication - Signed URLs for Integration - Custom Applications - Automation Scripts

Common Workflows¶

Initial Setup¶

# 1. Login
sitesctl auth login --username myuser

# 2. Configure preferences
sitesctl config output --value json
sitesctl config auto-upgrade --value true

# 3. Create a site
sitesctl create --name mysite --template iver --quota 5

# 4. Save the master token
sitesctl auth site-token --space myuser --name mysite --token <token-from-creation>

Daily Content Management¶

# Upload changes
sitesctl site --space myspace --name mysite \
  content upload --source ./public --recursive

# Check site health
sitesctl site --space myspace --name mysite health

# List files
sitesctl site --space myspace --name mysite \
  content list --path / --recursive

Sharing and Collaboration¶

# Create time-limited access token
sitesctl site --space myspace --name mysite \
  tokens access-token create \
  --identifier "colleague-temp" \
  --duration 604800 \
  --permission r

# Create signed URL for specific file
sitesctl site --space myspace --name mysite \
  signed-urls create \
  --url https://sites.ecmwf.int/myspace/mysite/report.pdf \
  --duration 86400

Site Maintenance¶

# Update retention date
sitesctl site --space myspace --name mysite \
  update set:retentiondate --value 2027-12-31

# Restart site
sitesctl site --space myspace --name mysite \
  update restart

# Upgrade components
sitesctl site --space myspace --name mysite \
  update upgrade

Global Flags¶

All commands support these global flags:

Examples:

# Get detailed debug output
sitesctl list --debug

# Skip confirmation prompt
sitesctl delete --space test --name oldsite --force

# Get JSON output for scripting
sitesctl list --output json | jq '.[] | .name'

Environment Variables¶

The CLI supports these environment variables:

Example:

export ECMWF_USERNAME=myuser
export MASTER_TOKEN=abc123...
sitesctl site --space myspace --name mysite content list

Output Formats¶

The CLI supports three output formats:

Table (default)¶

Human-readable tabular output:

Owner    Space     Name      Type     Enabled
john     myspace   mysite    private  true

JSON¶

Machine-readable JSON:

[
  {
    "owner": "john",
    "space": "myspace",
    "name": "mysite",
    "type": "private",
    "enabled": true
  }
]

YAML¶

Human-readable structured format:

- owner: john
  space: myspace
  name: mysite
  type: private
  enabled: true

Set default:

sitesctl config output --value json

Override per command:

sitesctl list --output yaml

Scripting with the CLI¶

Best Practices¶

1. Use JSON output for easier parsing:

   sitesctl list --output json | jq '.[] | .name'
   

2. Check exit codes:

   if sitesctl auth whoami; then
     echo "Authenticated"
   else
     echo "Not authenticated"
     exit 1
   fi
   

3. Use --force in automation:

   sitesctl delete --space test --name temp --force
   

4. Store credentials securely:

   # Use environment variables
   export MASTER_TOKEN=$(pass sites/mysite/token)
   
   # Or use auth site-token
   sitesctl auth site-token --space myspace --name mysite --token <token>
   

5. Handle errors:

   if ! sitesctl site --space myspace --name mysite content upload --source ./files; then
     echo "Upload failed" >&2
     exit 1
   fi
   

Example Scripts¶

See the scripting examples sections in each command documentation: - Content Management Scripts - Token Management Scripts - Update Workflows

Troubleshooting¶

Common Issues¶

Authentication Errors:

# Check if logged in
sitesctl auth whoami

# Login if needed
sitesctl auth login --username myuser

Permission Denied: - Verify you have access: sitesctl list --space X --name Y - Check if you're an owner or admin - Ensure token has correct permissions

Command Not Found:

# Check installation
which sitesctl

# Verify PATH
echo $PATH

# Reinstall if needed

Connection Issues: - Check internet connectivity - Verify firewall allows HTTPS - Try with --debug for detailed error messages

Getting Help¶

Built-in help:

# General help
sitesctl --help

# Command help
sitesctl auth --help
sitesctl site content upload --help

# Version info
sitesctl --version

Documentation: - Command-specific: See individual documentation files - Examples: Each doc file includes examples and common workflows - Troubleshooting: Check troubleshooting sections in relevant docs

Support¶

Resources¶

• Full Documentation: https://sites.ecmwf.int/docs/sites/
• Support Portal: https://support.ecmwf.int
• CLI Version: sitesctl --version

Reporting Issues¶

When reporting issues, include:

1. CLI version: sitesctl --version
2. Command used: Full command line
3. Error message: Complete error output
4. Debug output: Run with --debug flag
5. Environment: OS, shell, network setup

Example:

# Get debug output
sitesctl list --debug > debug.log 2>&1

# Include in support request along with:
# - sitesctl --version
# - Description of expected vs actual behavior

Version Information¶

Current Documentation Version: 2024-02-27

CLI Updates: Use sitesctl upgrade-cli to get the latest version.

To check your CLI version:

sitesctl --version

Additional Resources¶

• ECMWF Sites User Documentation.
• ECMWF Sites SDK
• ECMWF Sites SDK - Python source documentation
• ECMWF Support Portal
• Sites Platform Web Interface
• API Documentation (in web interface)

Contributing¶

Found an error in the documentation? Have a suggestion? Contact ECMWF support at https://support.ecmwf.int