Skip to content
SHC Docs

shc clone

The shc clone command creates a duplicate of a running stack, enabling testing, staging environments, or development copies.

Overview

Section titled “Overview”

Clone creates a copy of a stack while keeping the original intact. It shares infrastructure with the move command but preserves the source stack.

OperationFlowOriginal Stack
CloneBackup -> RecoverKept
MoveBackup -> Uninstall -> RecoverDeleted

shc clone

Section titled “shc clone”

Create a duplicate of a stack:

Terminal window
# Clone to same node with new name
shc clone myapp myapp-clone


# Clone to different node
shc clone myapp myapp-prod --node node-abc123


# Clone with all connected stacks (integrations)
shc clone myapp myapp-prod --node node-abc123 --all-connections


# Clone to different environment
shc clone myapp myapp-staging --target-environment staging


# Clone to different tenant (requires permission)
shc clone myapp myapp-copy --target-tenant other-org


# Dry run (preview without executing)
shc clone myapp myapp-clone --dry-run

Arguments

Section titled “Arguments”
ArgumentRequiredDescription
<source>YesSource stack name
<new-name>YesTarget stack name (positional)

Flags

Section titled “Flags”
FlagDefaultDescription
--node, -nsameTarget node (or swarm for Swarm)
--target-environmentsameTarget environment
--target-tenantsameTarget tenant (requires permission)
--all-connections, -afalseClone entire integration graph
--rename, -rnoneRename dependencies: old:new,old2:new2
--dry-runfalseShow what would be cloned

Examples

Section titled “Examples”

Basic Clone

Section titled “Basic Clone”
Terminal window
# Create a test copy of production database
shc clone postgres postgres-test


# Output:
# Cloning postgres -> postgres-test
#   v Backing up postgres
#   v Recovering postgres-test
# Clone complete

Clone with Integrations

Section titled “Clone with Integrations”

When a stack has integrations (plugs/sockets), you must use --all-connections to clone the entire graph:

Terminal window
# Clone app and its database together
shc clone myapp myapp-staging --all-connections


# Clone with dependency renaming
shc clone myapp myapp-test --all-connections --rename postgres:postgres-test

Without --all-connections, cloning a stack with dependencies will fail:

Terminal window
$ shc clone nextcloud nextcloud-test
Error: Stack 'nextcloud' has dependencies that would be orphaned:
  - postgres (provides: postgres-socket)


Use --all-connections to clone the entire integration graph, or
unplug dependencies first.

Clone to Different Node

Section titled “Clone to Different Node”
Terminal window
# Clone to a specific node
shc clone myapp myapp-prod --node node-abc123 --all-connections


# Clone to Swarm (spans all Swarm nodes)
shc clone myapp myapp-prod --node swarm --all-connections


# This performs a full backup -> recover cycle
# Data is transferred to the target node

Clone to Different Environment

Section titled “Clone to Different Environment”
Terminal window
# Create staging copy from production
shc clone myapp myapp --target-environment staging


# Note: Same stack name is allowed when environment differs

Same-Node Optimization

Section titled “Same-Node Optimization”

When cloning to the same node (only name change), SHC uses a fast rename path instead of full backup/recover. This renames:

ResourcePattern
Database stack recordname column
Deployment directory{base}/deployments/{tenant}/{stack}/{environment}/
App directory{base}/apps/{tenant}/{stack}/
Docker Compose project{tenant}_{environment}_{stack}
Docker volumes{tenant}_{environment}_{stack}_{volume}
Vault secretstenants/{tenant}/stacks/{stack}/...
Schedule recordsschedules.stack column
Backup cachebackup_cache.stack column

Integration Handling

Section titled “Integration Handling”
ScenarioBehavior
Same node, no --all-connectionsReintegrates with existing providers (shares integrations)
Different node, no --all-connectionsFAILS if stack has connections (explicit safety)
Different node, --all-connectionsClones all connected stacks (full backup + recover)
Auto-suffix on collisionDependencies get -1, -2, etc. suffix

Name Collision Rules

Section titled “Name Collision Rules”

Clone always requires a different name, environment, or tenant from the source:

Terminal window
# These will fail (same name in same scope)
$ shc clone myapp myapp
Error: Target stack 'myapp' already exists in tenant 'default', environment 'default'


# These work (different scope)
shc clone myapp myapp --target-environment staging     # Different environment
shc clone myapp myapp --target-tenant other-org        # Different tenant
shc clone myapp myapp-copy                      # Different name

Process Flow

Section titled “Process Flow”
  1. Preflight - Validate target doesn’t exist, check quota
  2. Backup - Create coordinated backup of source stack(s)
  3. Recover - Deploy to target with new name/location
  4. Integrate - Re-establish integrations (if applicable)

See Also

Section titled “See Also”