List Sites Command¶

The list command retrieves and displays sites with optional filtering and sorting.

Overview¶

The list command allows you to: - View all accessible sites - Filter sites by various criteria - Sort results - Check individual site health status

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 list`¶

List all sites you have access to, with optional filters and sorting.

Usage:

sitesctl list [flags]

Flags:

--enabled-only - Only include enabled (non-archived) sites
Type: Boolean
Default: false
--query - Free-text search across owner, name, space, and description
Type: String
--type - Filter by site type
Type: String
Values: private or public
--owner - Filter by owner username
Type: String
--space - Filter by space identifier
Type: String
--name - Filter by site name
Type: String
--sort-by - Field to sort by
Type: String
Values: name, owner, space, creation_date, retention_date
--order-by - Sort order
Type: String
Values: asc (ascending) or desc (descending)

Examples:

# List all accessible sites
sitesctl list

# List only enabled (non-archived) sites
sitesctl list --enabled-only

# Filter by owner
sitesctl list --owner symm

# Filter by space and type
sitesctl list --space test --type public

# Filter by name
sitesctl list --name mysite

# Free-text search
sitesctl list --query "weather data"

# Sort by owner in ascending order
sitesctl list --sort-by owner --order-by asc

# Sort by creation date, newest first
sitesctl list --sort-by creation_date --order-by desc

# Combine multiple filters
sitesctl list --owner symm --type private --enabled-only --sort-by name

# Output as JSON for scripting
sitesctl list --output json

# Output as YAML
sitesctl list --output yaml

What it does: - Queries the Sites Hub API for matching sites - Applies filters on the server side for efficient searching - Returns site metadata including: - Owner - Space - Name - Type (private/public) - Description - Creation date - Retention date - Enabled status - Master token (Base64-encoded) - Quota information

Output Columns (table format):

Column	Description
Owner	Site owner username
Space	Site space identifier
Name	Site name
Type	`private` or `public`
Enabled	Whether the site is active
Created	Creation timestamp
Retention	Retention date (when site may be deleted)
Description	Site description

Note on Master Tokens: The list output includes master tokens in Base64-encoded format. To use a master token for content operations: 1. Decode the Base64 token 2. Use it with auth site-token or --api-authentication-token flag 3. Or retrieve the decoded token with sitesctl site --space X --name Y tokens master-token show

`sitesctl list health`¶

Check the health status of a specific site.

Usage:

sitesctl list health --space <space> --name <name>

Flags: - --space (required) - Site space identifier - --name (required) - Site name

Examples:

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

# Check health with JSON output
sitesctl list health --space myspace --name mysite --output json

What it does: - Checks the health of the site's web service - Checks the health of the site's storage backend - Returns status for each component

Output Information: - Web Health: Status of the web server/application - Storage Health: Status of the storage backend - Returns OK or error information for each component

Use Cases: - Troubleshooting site accessibility issues - Monitoring site status - Verifying site is operational after creation or updates - Checking storage availability before large uploads

Filtering Tips¶

Combining Filters¶

Filters are applied as AND conditions. For example:

sitesctl list --owner john --type private --enabled-only

Returns only private, enabled sites owned by john.

Free-text Search¶

The --query flag searches across multiple fields: - Owner username - Site name - Space identifier - Description text

Example:

sitesctl list --query "climate model"

Matches sites with "climate model" in any of these fields.

Case Sensitivity¶

Filter values are typically case-insensitive
Exact behavior depends on the API implementation

Performance Considerations¶

Filtering is done server-side for efficiency
Large result sets may take longer to retrieve
Consider using specific filters when you know what you're looking for
Use --enabled-only to exclude archived sites from results

Scripting Examples¶

Get all sites as JSON¶

sitesctl list --output json > sites.json

Filter sites owned by current user¶

current_user=$(whoami)
sitesctl list --owner "$current_user"

Get site count¶

# Using jq to count JSON results
sitesctl list --output json | jq '. | length'

Find sites expiring soon¶

# Get sites sorted by retention date
sitesctl list --sort-by retention_date --order-by asc --output json

Check health of all your sites¶

# Bash script example
sitesctl list --owner $(whoami) --output json | \
  jq -r '.[] | "\(.space) \(.name)"' | \
  while read space name; do
    echo "Checking $space/$name..."
    sitesctl list health --space "$space" --name "$name"
  done

Return Status¶

Success: Exit code 0, sites displayed
Authentication Error: Exit code 1, check your credentials
API Error: Exit code 1, check connectivity and API status
Invalid Filter: Exit code 1, verify filter parameters