Utility commands
shc events --audit
Section titled “shc events --audit”View audit log entries (the audit chain lives under shc events):
shc events --auditshc events --audit --limit 5shc events --audit --allshc -s myapp events --auditshc events --audit --actor systemshc events --audit --event A200100STKINSshc 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 10shc -o json events --auditshc -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
Section titled “shc repo”Manage app repositories. Repos are remote-only (git or http(s)
URLs; file-path repos were removed, so install a local directory
directly with shc install ./path/to/app instead). The implicit
shipped 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 lsshc repo add myrepo "https://github.com/user/apps"shc repo add mirror "git+file:///srv/mirrors/apps.git" # local bare git remoteshc repo sync myreposhc repo rm myrepo -yshc ctx
Section titled “shc ctx”Manage context (tenant/stack/environment):
shc ctxshc ctx --tenant acme --environment prodshc ctx --stack nextcloudshc config
Section titled “shc config”Manage configuration:
shc config lsshc config ls --scope tenantshc config get backup.retention.dailyshc config get backup.retention.daily --scope globalshc config set backup.retention.daily 14 --scope tenantshc config set backup.repo /tmp/repo --scope globalshc config unset backup.schedule --scope stack -t acme -s myblogshc schedule
Section titled “shc schedule”Manage cron schedules:
shc -s nextcloud schedule add backup "@daily"shc schedule lsshc schedule enable daily-backupshc schedule disable daily-backupshc schedule rm daily-backupshc search
Section titled “shc search”Search app catalog:
shc searchshc search nextcloudshc search --output jsonshc validate
Section titled “shc validate”Validate app definitions:
shc validate apps/myapp/shc validate --stack mystackshc -o json validate apps/myapp/shc forward
Section titled “shc forward”Forward ports from container services to the local machine:
shc forward postgres db # Minimal - ports inferredshc forward postgres db:5432 # Remote port explicitshc forward postgres db:5432=5433 # Fully explicitshc forward myapp web:80=8080 db:5432=5433 # Multiple forwardsshc forward postgres db --address 0.0.0.0 # Custom bind addressshc forward postgres db -e prod # Specific environmentThe command blocks until Ctrl+C. For remote nodes, it uses WebSocket proxy; for local stacks, it uses socat.
shc tenant
Section titled “shc tenant”Manage tenants:
shc tenant ls # List tenantsshc tenant add acme # Add tenantshc tenant rm acme # Remove tenantshc ctx -t acme # Select the tenantshc tenant info # Show current tenant infoshc completion
Section titled “shc completion”Generate and install shell completion scripts for bash, zsh, and fish.
Basic Setup
Section titled “Basic Setup”# Generate completion script to stdoutshc completion --shell bashshc completion --shell zshshc completion --shell fish
# Install to default system locationshc completion --shell bash --installshc completion --shell zsh --installshc completion --shell fish --install
# Install to custom locationshc completion --shell bash --file /path/to/completions/shcShell-Specific Instructions
Section titled “Shell-Specific Instructions”Bash:
# Option 1: Install to system completion directoryshc completion --shell bash --install
# Option 2: Add to bashrcecho 'source <(shc completion --shell bash)' >> ~/.bashrcZsh:
# Option 1: Install to zsh functions directoryshc completion --shell zsh --install
# Option 2: Add to zshrc (ensure fpath is set first)echo 'eval "$(shc completion --shell zsh)"' >> ~/.zshrcFish:
# Option 1: Install to fish completionsshc completion --shell fish --install
# Option 2: Source directlyshc completion --shell fish | sourceDynamic Completions
Section titled “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 | docker, podman, incus, apple |
--role | static | primary, worker |
Positional arguments are also completed dynamically:
shc ls <TAB> # Shows stack namesshc install <TAB> # Shows app namesshc job run mystack <TAB> # Shows job names for mystackContext-Aware Filtering
Section titled “Context-Aware Filtering”Completions respect context from multiple sources:
-
Explicit flags on the command line take highest priority:
Terminal window shc ls --tenant acme --stack <TAB># Shows only stacks belonging to tenant "acme" -
Saved context from
shc ctxis used when flags aren’t specified:Terminal window shc ctx --tenant acmeshc ls --stack <TAB># Shows stacks for tenant "acme" (from saved context) -
No filter when neither is available:
Terminal window shc ls --stack <TAB># Shows all stacks (no tenant filter)
Configuration
Section titled “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 networksexport SHC_COMPLETION_TIMEOUT=1000Debug Mode
Section titled “Debug Mode”Enable debug logging to troubleshoot completion issues:
# Enable debug modeexport SHC_COMPLETION_DEBUG=/tmp/shc-completion.log
# Now use completions normallyshc ls --tenant <TAB>
# Check debug outputtail -f /tmp/shc-completion.logDebug 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,fabrikamTroubleshooting
Section titled “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_TIMEOUTvalue - 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