Skip to content

Site Content Management Commands

The site content command group provides comprehensive file and directory management capabilities for site content.

Overview

Content commands allow you to: - Upload files and directories to a site - Download files and directories from a site - List files with metadata - Delete files and directories - Create and manage symbolic links

All content commands require specifying the site with --space and --name flags, plus authentication.

Global Flags

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

Site-Specific Flags

Content commands require these flags to identify the site:

  • --space (required) - Site space identifier
  • --name (required) - Site name
  • --api-authentication-token, --token, --aut - Master token or HTTP access token
  • Can also be set via environment variables: API_AUTHENTICATION_TOKEN, MASTER_TOKEN, HTTP_ACCESS_TOKEN
  • Or configured with sitesctl auth site-token
  • --v1 - Use API v1 instead of v2 (limited metadata)

Commands

sitesctl site content upload

Upload local files or directories to a site.

Usage: 

sitesctl site --space <space> --name <name> content upload --source <path> [flags]

Flags:

  • --source, -s (required) - Local path to upload
  • Can be a file or directory

  • If directory, use --match and/or --recursive to select files

  • --destination, --dest - Remote destination directory

  • Default: /

  • Must be an absolute path starting with /

  • --match, -m - Glob pattern to filter source files

  • Example: **/*.png, *.html, data/**/*.csv

  • --recursive - Recurse into subdirectories when source is a directory

  • Default: false

  • --ignore-errors - Continue uploading when a file fails

  • Default: false

  • --quiet - Suppress API response output for each file

  • Default: false

  • --if-exists-rename-to - Rename existing remote file before upload

  • Prevents overwriting by moving the old file

  • --if-exists-backup - Backup existing remote file before upload

  • Creates a timestamped backup copy

  • Default: false

  • --no-resume - Disable resumable uploads

  • Restarts from byte 0, overwrites remote file

  • Default: false (resumable uploads enabled)

  • --dry-run - List files that would be uploaded without uploading

  • Default: false

Examples:

# Upload a single file to root
sitesctl site --space myspace --name mysite \
  content upload --source ./index.html

# Upload a file to a specific directory
sitesctl site --space myspace --name mysite \
  content upload --source ./index.html --destination /public/

# Upload a directory recursively
sitesctl site --space myspace --name mysite \
  content upload --source ./myfiles --recursive

# Upload only PNG files from a directory
sitesctl site --space myspace --name mysite \
  content upload --source ./images --match "**/*.png" --recursive

# Upload with pattern matching
sitesctl site --space myspace --name mysite \
  content upload --source ./docs --match "*.md" --destination /documentation/

# Upload and backup existing files
sitesctl site --space myspace --name mysite \
  content upload --source ./data --recursive --if-exists-backup

# Upload large file without resume (restart from beginning)
sitesctl site --space myspace --name mysite \
  content upload --source ./bigfile.dat --no-resume

# Dry run to see what would be uploaded
sitesctl site --space myspace --name mysite \
  content upload --source ./myfiles --recursive --dry-run

# Upload and continue on errors
sitesctl site --space myspace --name mysite \
  content upload --source ./files --recursive --ignore-errors

# Quiet upload (minimal output)
sitesctl site --space myspace --name mysite \
  content upload --source ./files --recursive --quiet

Resumable Uploads:

For large files (API v2): - Uploads can be resumed if interrupted - Useful for large files or unreliable connections - Use --no-resume to restart from the beginning and overwrite

Glob Pattern Examples:

Pattern Matches
*.html All HTML files in the source directory
**/*.png All PNG files in source directory and subdirectories
data/*.csv CSV files in data subdirectory only
**/*.{jpg,png} All JPG and PNG files recursively

sitesctl site content download

Download files from a site to local storage.

Usage: 

sitesctl site --space <space> --name <name> content download --path <remote-path> [flags]

Flags:

  • --path (required) - Remote file or directory path to download

  • Must start with /

  • --match - Glob pattern to filter files

  • Example: *.grib, **/*.json

  • --archive - Download as archive

  • Values: zip, tar, or tgz

  • Default: zip (if flag is used without value)

  • --recursive - Recurse into subdirectories

  • Default: false

  • --overwrite - Overwrite local files even when size matches

  • Default: false

  • --dry-run - List files that would be downloaded without downloading

  • Default: false

Examples:

# Download a single file
sitesctl site --space myspace --name mysite \
  content download --path /index.html

# Download entire site recursively
sitesctl site --space myspace --name mysite \
  content download --path / --recursive

# Download as ZIP archive
sitesctl site --space myspace --name mysite \
  content download --path / --recursive --archive zip

# Download as TAR archive
sitesctl site --space myspace --name mysite \
  content download --path /data --archive tar

# Download only GRIB files
sitesctl site --space myspace --name mysite \
  content download --path /data --match "*.grib" --recursive

# Download and overwrite local files
sitesctl site --space myspace --name mysite \
  content download --path / --recursive --overwrite

# Dry run to see what would be downloaded
sitesctl site --space myspace --name mysite \
  content download --path /data --recursive --dry-run

Download Location:

Files are downloaded to: 

./{space}/{name}/

Example: ./myspace/mysite/index.html

Archive Downloads:

When using --archive: - Files are compressed before download - Faster for many small files - Single download instead of multiple requests - Archive is saved and then extracted locally

sitesctl site content list

List files and directories in a site.

Usage: 

sitesctl site --space <space> --name <name> content list [--path <path>] [flags]

Flags:

  • --path - Remote path to list

  • Default: / (root)

  • --match - Glob pattern to filter files

  • --type - Filter by type

  • Values: f (files only), d (directories only)

  • Default: all types

  • --recursive - Recurse into subdirectories

  • Default: false

  • --list-limit - Limit number of results per request

  • Default: 0 (server default)

Examples:

# List root directory
sitesctl site --space myspace --name mysite content list

# List specific directory
sitesctl site --space myspace --name mysite \
  content list --path /data

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

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

# List only directories
sitesctl site --space myspace --name mysite \
  content list --path / --type d

# List with pattern matching
sitesctl site --space myspace --name mysite \
  content list --path /data --match "*.grib"

# List with JSON output
sitesctl site --space myspace --name mysite \
  content list --path / --recursive --output json

# Limited results
sitesctl site --space myspace --name mysite \
  content list --path / --list-limit 100

# Use API v1 (simple list, less metadata)
sitesctl site --space myspace --name mysite --v1 \
  content list

Output (API v2):

Includes rich metadata: - File/directory name - Size (in bytes) - Modification time - Type (file/directory)

Output (API v1):

Simple list of paths only, no metadata.

sitesctl site content delete

Delete files or directories from a site.

Usage: 

sitesctl site --space <space> --name <name> content delete --path <path> [flags]

Flags:

  • --path (required) - Remote path to delete from

  • --match - Glob pattern to match files

  • --recursive - Recurse into subdirectories

  • Default: false

Examples:

# Delete a single file
sitesctl site --space myspace --name mysite \
  content delete --path /oldfile.txt

# Delete a directory
sitesctl site --space myspace --name mysite \
  content delete --path /olddir --recursive

# Delete all JPG files in a directory
sitesctl site --space myspace --name mysite \
  content delete --path /images --match "*.jpg"

# Delete everything recursively (⚠️ dangerous!)
sitesctl site --space myspace --name mysite \
  content delete --path / --recursive --force

# Delete with pattern matching
sitesctl site --space myspace --name mysite \
  content delete --path /temp --match "*.tmp" --recursive

⚠️ Warning: - Deletion is permanent - Use --force to skip confirmation - Test with content list first to verify what will be deleted

sitesctl site content checksum

Fetch metadata for a remote file and, when available, its SHA-256 checksum.

This command performs a HEAD request and reads the server's Repr-Digest header as defined by RFC 9530. Use it when you want to inspect a remote file before downloading it, or when you want to compare the server's digest with a local checksum.

If the server does not return a digest, the command still shows the file metadata and reports the checksum as (not available).

Usage: 

sitesctl site --space <space> --name <name> content checksum --path <remote-file>

Flags:

  • --path (required) - Remote file path
  • Must point to a file, not a directory

Examples:

# Show checksum and metadata for a remote file
sitesctl site --space myspace --name mysite \
  content checksum --path /data/report.pdf

# Check a file at the site root
sitesctl site --space myspace --name mysite \
  content checksum --path /index.html

# Return the result as JSON
sitesctl site --space myspace --name mysite \
  content checksum --path /index.html --output json

Related: - Use content download --verify-checksum to validate file integrity while downloading

sitesctl site content symlink create

Create a symbolic link to a file or directory.

Usage: 

sitesctl site --space <space> --name <name> content symlink create --link <link-path> --target <target-path>

Flags:

  • --link, -l (required) - Link path to create
  • --target, -m (required) - Target file or directory path

Examples:

# Create a symlink
sitesctl site --space myspace --name mysite \
  content symlink create \
  --link logo.svg \
  --target brands/acme/logo.svg

# Create directory symlink
sitesctl site --space myspace --name mysite \
  content symlink create \
  --link latest \
  --target releases/v2.0

# Create at specific path
sitesctl site --space myspace --name mysite \
  content symlink create \
  --link /public/index.html \
  --target /releases/latest/index.html

Use Cases: - Creating aliases for frequently accessed files - Maintaining "latest" links to versioned content - Simplifying complex directory structures - URL shortcuts

sitesctl site content symlink check

Show information about a symbolic link.

Usage: 

sitesctl site --space <space> --name <name> content symlink check --link <link-path>

Flags:

  • --link, -l (required) - Link path to check

Examples:

# Check a symlink
sitesctl site --space myspace --name mysite \
  content symlink check --link logo.svg

# Check with JSON output
sitesctl site --space myspace --name mysite \
  content symlink check --link latest --output json

Output: - Link path - Target path - Whether target exists - Link validity

sitesctl site content symlink delete

Delete a symbolic link.

Usage: 

sitesctl site --space <space> --name <name> content symlink delete --link <link-path>

Flags:

  • --link, -l (required) - Link path to delete

Examples:

# Delete a symlink
sitesctl site --space myspace --name mysite \
  content symlink delete --link logo.svg

# Delete without confirmation
sitesctl site --space myspace --name mysite \
  content symlink delete --link logo.svg --force

Note: This deletes only the symlink, not the target file/directory.

Site Health Check

sitesctl site health

Check the health status of a site.

Usage: 

sitesctl site --space <space> --name <name> health

Examples:

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

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

Output: - Web service health status - Storage backend health status - Any error messages or warnings

Authentication for Content Operations

Content operations require authentication. The CLI looks for tokens in this order:

  1. --api-authentication-token flag
  2. Site-specific token (from auth site-token)
  3. OIDC token (from auth login)
  4. Environment variables

Setup Authentication:

Option 1: Use site-token (recommended for automation) 

# Save token for the site
sitesctl auth site-token --space myspace --name mysite --token <master-token>

# Now content commands work without token flag
sitesctl site --space myspace --name mysite content list

Option 2: Use command-line flag 

sitesctl site --space myspace --name mysite \
  --api-authentication-token <token> \
  content list

Option 3: Use environment variable 

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

Option 4: Use OIDC token 

sitesctl auth login --username myuser
sitesctl site --space myspace --name mysite content list

Scripting Examples

Sync Local Directory to Site

#!/bin/bash
# Upload all changes to site

sitesctl site --space myspace --name mysite \
  content upload \
  --source ./public \
  --destination / \
  --recursive \
  --if-exists-backup \
  --quiet

Backup Site Content

#!/bin/bash
# Download entire site

backup_dir="backups/$(date +%Y%m%d)"
mkdir -p "$backup_dir"

sitesctl site --space myspace --name mysite \
  content download \
  --path / \
  --recursive \
  --archive zip

mv myspace/mysite "$backup_dir/"

Clean Old Files

#!/bin/bash
# Delete files older than 30 days

sitesctl site --space myspace --name mysite \
  content delete \
  --path /logs \
  --match "*.log" \
  --recursive \
  --force

Mirror Content Between Sites

#!/bin/bash
# Copy content from one site to another

source_space="staging"
source_name="mysite"
dest_space="production"
dest_name="mysite"

# Download from source
sitesctl site --space "$source_space" --name "$source_name" \
  content download --path / --recursive

# Upload to destination
sitesctl site --space "$dest_space" --name "$dest_name" \
  content upload \
  --source "./${source_space}/${source_name}" \
  --destination / \
  --recursive \
  --force

Best Practices

  1. Use --dry-run before large operations to verify scope
  2. Enable --if-exists-backup for important file updates
  3. Use glob patterns to selectively upload/download files
  4. Compress before uploading large files when possible
  5. Use --archive for downloading many small files
  6. Set up auth site-token for seamless automation
  7. Test with --recursive on small directories first
  8. Monitor uploads of large files, use --no-resume if needed
  9. Use symlinks for version management and aliases
  10. Regular backups with content download --recursive --archive

See Also