Utility commands

shc events —audit

View audit log entries (the audit chain lives under shc events):

shc events --audit
shc events --audit --limit 5
shc events --audit --all
shc -s myapp events --audit
shc events --audit --actor system
shc events --audit --event A200100STKINS
shc events --audit --since "2020-01-01"
shc events --audit --until "2099-12-31"
shc events --audit --since "2020-01-01" --until "2099-12-31"
shc events --audit --all --actor system --limit 10
shc -o json events --audit
shc -o yaml events --audit

Flag	Short	Description
`--all`	`-a`	Drop the stack filter
`--actor`		Filter by actor
`--event`		Filter by event code
`--since`		Filter by start date/datetime
`--until`		Filter by end date/datetime
`--limit`	`-n`	Limit number of results
`--follow`	`-f`	Poll for new records every 3s

The stack filter is the global -s/--stack flag; tenant scope is the global -t/--tenant flag. See shc events for the live-stream mode.

shc repo

Manage app repositories. Repos are remote-only (git or http(s) URLs — file-path repos were removed; install a local directory directly with shc install ./path/to/app instead). The implicit builtin repo mirrors the apps shipped with the SHC package and is managed by the daemon — its name is reserved and it cannot be removed.

shc repo ls
shc repo add myrepo "https://github.com/user/apps"
shc repo add mirror "git+file:///srv/mirrors/apps.git"   # local bare git remote
shc repo sync myrepo
shc repo rm myrepo -y

shc ctx

Manage context (tenant/stack/environment):

shc ctx
shc ctx --tenant acme --environment prod
shc ctx --stack nextcloud

shc config

Manage configuration:

shc config ls
shc config ls --scope tenant
shc config get backup.retention_days
shc config get backup.retention_days --scope base
shc config set backup.retention_days 14 --scope tenant
shc config set backup.repo /tmp/repo --scope base
shc config unset backup.schedule --scope deployment

shc schedule

Manage cron schedules:

shc -s nextcloud schedule add backup "@daily"
shc schedule ls
shc schedule enable daily-backup
shc schedule disable daily-backup
shc schedule rm daily-backup

shc search

Search app catalog:

shc search
shc search nextcloud
shc search --output json

shc validate

Validate app definitions:

shc validate apps/myapp/
shc validate --stack mystack
shc -o json validate apps/myapp/

shc forward

Forward ports from container services to the local machine:

shc forward postgres db                    # Minimal - ports inferred
shc forward postgres db:5432               # Remote port explicit
shc forward postgres 5433:db:5432          # Fully explicit
shc forward myapp 8080:web:80 5433:db:5432 # Multiple forwards
shc forward postgres db --address 0.0.0.0  # Custom bind address
shc forward postgres db -e prod            # Specific environment

The command blocks until Ctrl+C. For remote nodes, it uses WebSocket proxy; for local stacks, it uses socat.

shc tenant

Manage tenants:

shc tenant ls                    # List tenants
shc tenant add acme              # Add tenant
shc tenant rm acme               # Remove tenant
shc tenant use acme              # Switch to tenant
shc tenant info                  # Show current tenant info

shc completion

Generate and install shell completion scripts for bash, zsh, and fish.

Basic Setup

# Generate completion script to stdout
shc completion --shell bash
shc completion --shell zsh
shc completion --shell fish

# Install to default system location
shc completion --shell bash --install
shc completion --shell zsh --install
shc completion --shell fish --install

# Install to custom location
shc completion --shell bash --file /path/to/completions/shc

Shell-Specific Instructions

Bash:

# Option 1: Install to system completion directory
shc completion --shell bash --install

# Option 2: Add to bashrc
echo 'source <(shc completion --shell bash)' >> ~/.bashrc

Zsh:

# Option 1: Install to zsh functions directory
shc completion --shell zsh --install

# Option 2: Add to zshrc (ensure fpath is set first)
echo 'eval "$(shc completion --shell zsh)"' >> ~/.zshrc

Fish:

# Option 1: Install to fish completions
shc completion --shell fish --install

# Option 2: Source directly
shc completion --shell fish | source

Dynamic Completions

Shell completions are context-aware and provide dynamic suggestions by querying the shc server:

Flag	Completion Type	Description
`--tenant, -t`	tenants	All tenant names
`--stack, -s`	stacks	Stack names (filtered by tenant/environment)
`--environment, -e`	environments	Environment names (filtered by tenant)
`--node`	nodes	Node names
`--repo, -r`	repos	Repository names (filtered by tenant)
`--service`	services	Service/container names (filtered by stack)
`--job`	jobs	Job names (filtered by stack)
`--backup, -b`	backups	Backup IDs (filtered by stack)
`--scope`	static	global, tenant, stack, environment, deployment
`--output, -o`	static	json, table, text, yaml
`--runtime`	static	compose, podman, swarm
`--role`	static	primary, worker

Positional arguments are also completed dynamically:

shc stack list <TAB>        # Shows stack names
shc install <TAB>           # Shows app names
shc tenant switch <TAB>     # Shows tenant names
shc job run mystack <TAB>   # Shows job names for mystack

Context-Aware Filtering

Completions respect context from multiple sources:

Explicit flags on the command line take highest priority:

shc stack list --tenant acme --stack <TAB>
# Shows only stacks belonging to tenant "acme"

Saved context from shc ctx is used when flags aren’t specified:

shc ctx --tenant acme
shc stack list --stack <TAB>
# Shows stacks for tenant "acme" (from saved context)

No filter when neither is available:

shc stack list --stack <TAB>
# Shows all stacks (no tenant filter)

Configuration

Configure completion behavior with environment variables:

Variable	Default	Description
`SHC_COMPLETION_TIMEOUT`	`500`	Query timeout in milliseconds
`SHC_COMPLETION_DEBUG`	(unset)	Path to debug log file

Timeout Configuration:

# Increase timeout for slow networks
export SHC_COMPLETION_TIMEOUT=1000

Debug Mode

Enable debug logging to troubleshoot completion issues:

# Enable debug mode
export SHC_COMPLETION_DEBUG=/tmp/shc-completion.log

# Now use completions normally
shc stack list --tenant <TAB>

# Check debug output
tail -f /tmp/shc-completion.log

Debug output includes:

Completion type requested
Context flags received
Saved context loaded from shc ctx
API endpoint called
Response time in milliseconds
Results returned (or errors)

Example debug output:

[2026-01-27 10:15:32] type=tenants context={'tenant': None, 'stack': None}
[2026-01-27 10:15:32] endpoint=/api/resource/Tenant
[2026-01-27 10:15:32] response_time=45ms count=3
[2026-01-27 10:15:32] results=acme,contoso,fabrikam

Troubleshooting

Completions not appearing:

Ensure the shc server is running: shc status
Check completion script is loaded: type the command and press Tab
Enable debug mode to see what’s happening
Verify timeout isn’t too short for your network

Empty completions:

Server may not be reachable (completions fail silently)
No entities of that type exist yet
Auth token may be expired (run any shc command to refresh)

Slow completions:

Increase SHC_COMPLETION_TIMEOUT value
Check network latency to server
Check server performance

Context not being used:

Verify saved context: shc ctx
Check explicit flags aren’t overriding it
Enable debug mode to see resolved context