Skip to content
SHC Docs

Utility commands

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

Terminal window
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
FlagShortDescription
--all-aDrop the stack filter
--actorFilter by actor
--eventFilter by event code
--sinceFilter by start date/datetime
--untilFilter by end date/datetime
--limit-nLimit number of results
--follow-fPoll 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.

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.

Terminal window
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

Manage context (tenant/stack/environment):

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

Manage configuration:

Terminal window
shc config ls
shc config ls --scope tenant
shc config get backup.retention.daily
shc config get backup.retention.daily --scope global
shc config set backup.retention.daily 14 --scope tenant
shc config set backup.repo /tmp/repo --scope global
shc config unset backup.schedule --scope stack -t acme -s myblog

Manage cron schedules:

Terminal window
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

Search app catalog:

Terminal window
shc search
shc search nextcloud
shc search --output json

Validate app definitions:

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

Forward ports from container services to the local machine:

Terminal window
shc forward postgres db # Minimal - ports inferred
shc forward postgres db:5432 # Remote port explicit
shc forward postgres db:5432=5433 # Fully explicit
shc forward myapp web:80=8080 db:5432=5433 # 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.

Manage tenants:

Terminal window
shc tenant ls # List tenants
shc tenant add acme # Add tenant
shc tenant rm acme # Remove tenant
shc ctx -t acme # Select the tenant
shc tenant info # Show current tenant info

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

Terminal window
# 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

Bash:

Terminal window
# 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:

Terminal window
# 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:

Terminal window
# Option 1: Install to fish completions
shc completion --shell fish --install
# Option 2: Source directly
shc completion --shell fish | source

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

FlagCompletion TypeDescription
--tenant, -ttenantsAll tenant names
--stack, -sstacksStack names (filtered by tenant/environment)
--environment, -eenvironmentsEnvironment names (filtered by tenant)
--nodenodesNode names
--repo, -rreposRepository names (filtered by tenant)
--serviceservicesService/container names (filtered by stack)
--jobjobsJob names (filtered by stack)
--backup, -bbackupsBackup IDs (filtered by stack)
--scopestaticglobal, tenant, stack, environment, deployment
--output, -ostaticjson, table, text, yaml
--runtimestaticdocker, podman, incus, apple
--rolestaticprimary, worker

Positional arguments are also completed dynamically:

Terminal window
shc ls <TAB> # Shows stack names
shc install <TAB> # Shows app names
shc job run mystack <TAB> # Shows job names for mystack

Completions respect context from multiple sources:

  1. Explicit flags on the command line take highest priority:

    Terminal window
    shc ls --tenant acme --stack <TAB>
    # Shows only stacks belonging to tenant "acme"
  2. Saved context from shc ctx is used when flags aren’t specified:

    Terminal window
    shc ctx --tenant acme
    shc ls --stack <TAB>
    # Shows stacks for tenant "acme" (from saved context)
  3. No filter when neither is available:

    Terminal window
    shc ls --stack <TAB>
    # Shows all stacks (no tenant filter)

Configure completion behavior with environment variables:

VariableDefaultDescription
SHC_COMPLETION_TIMEOUT500Query timeout in milliseconds
SHC_COMPLETION_DEBUG(unset)Path to debug log file

Timeout Configuration:

Terminal window
# Increase timeout for slow networks
export SHC_COMPLETION_TIMEOUT=1000

Enable debug logging to troubleshoot completion issues:

Terminal window
# Enable debug mode
export SHC_COMPLETION_DEBUG=/tmp/shc-completion.log
# Now use completions normally
shc ls --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

Completions not appearing:

  1. Ensure the shc server is running: shc status
  2. Check completion script is loaded: type the command and press Tab
  3. Enable debug mode to see what’s happening
  4. 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