Core Commands

sftpwarden

Root command for the SFTPWarden CLI.

sftpwarden --help
sftpwarden --version
sftpwarden version

Root Options

Flag	Value	What it does
--version	flag	Prints the installed SFTPWarden version and exits.
--install-completion	flag	Installs shell completion for the current shell.
--show-completion	flag	Prints the shell completion script so you can inspect or install it manually.
--help	flag	Shows root command help.

sftpwarden version

Prints the installed SFTPWarden version and exits. This is the command form of the root --version option.

sftpwarden version
sftpwarden --version

Effects

Read-only. It does not read a project config, use a context, or contact any runtime infrastructure.

sftpwarden deploy

Applies deployment-level desired state for the selected context. This is the normal command for applying changes from sftpwarden.yaml after editing it manually or with sftpwarden config.

For Compose contexts, it runs Docker Compose. For Kubernetes manifest projects, it renders and applies manifests. For Helm projects, it writes values and runs Helm upgrade/install through the deployment service.

sftpwarden deploy
sftpwarden deploy --context prod
sftpwarden deploy --dry-run
sftpwarden deploy --dry-run --json
sftpwarden deploy --yes

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Selects a registered context.
--dry-run	flag	false	Prints the deployment plan and pending provider schema reconciliation without applying changes.
--json	flag	false	Prints deployment and schema plan data as JSON. Most useful with --dry-run.
--yes, -y	flag	false	Accepts critical-context confirmation and pending forward provider schema migration prompts.

Effects

• May write generated deployment files such as docker-compose.yml, kubernetes.yml, or values.yaml.

• May migrate provider users forward when provider.user_schema requests a newer schema than the stored provider data.

• May start, update, or restart runtime infrastructure.

• For Kubernetes YAML/CSV providers, syncs the local provider file into the provider PVC as part of rollout.

sftpwarden validate

Validates one project configuration file and resolves the provider path.

sftpwarden validate
sftpwarden validate --config ./sftpwarden.yaml
sftpwarden validate --json

Options

Flag	Value	Default	What it does
--config	PATH	sftpwarden.yaml	Config file to validate.
--json	flag	false	Prints validation result, project name, provider type, config path, and provider path as JSON.

Effects

This command does not write files or contact the runtime. Use it after editing sftpwarden.yaml and before committing examples.

sftpwarden compose

Renders the Docker Compose file for a project.

sftpwarden compose
sftpwarden compose --config ./sftpwarden.yaml
sftpwarden compose --write

Options

Flag	Value	Default	What it does
--config	PATH	sftpwarden.yaml	Config file used to render Compose.
--write	flag	false	Writes the generated Compose text to the configured compose file, normally docker-compose.yml. Without it, Compose text is printed.

Effects

Without --write, this command only prints. With --write, it updates the Compose file but does not start containers. Run sftpwarden deploy to apply the change.

sftpwarden plan

Shows the runtime user plan for a local context. It also reports deployment-level configuration drift so operators know whether refresh or deploy is the next right command.

sftpwarden plan
sftpwarden plan --context prod
sftpwarden plan --json

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Selects a registered context.
--config	PATH	none	Resolves a project directly from a config path.
--json	flag	false	Prints runtime plan and deploy drift data as JSON.

Effects

This command is read-only. It compares provider users to runtime state and tells you what sftpwarden refresh would apply.

sftpwarden refresh

Tells the running runtime to reload users now.

sftpwarden refresh
sftpwarden refresh --context prod
sftpwarden refresh --all
sftpwarden refresh --dry-run
sftpwarden refresh --json

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Refreshes one registered context.
--config	PATH	none	Resolves a context directly from a config path.
--all	flag	false	Refreshes all registered contexts. Cannot be combined with a single-context intent.
--dry-run	flag	false	Prints the refresh command that would run without executing it.
--json	flag	false	Prints refresh target results as JSON.

Effects

refresh applies user/provider changes that are already visible to the runtime. It does not apply sftpwarden.yaml deployment changes. For Kubernetes YAML/CSV providers, run sftpwarden deploy, sftpwarden kube apply, or sftpwarden helm upgrade because the local provider file must be copied into the provider PVC.

sftpwarden info

Shows the resolved context entry.

sftpwarden info
sftpwarden info --context prod
sftpwarden info --config ./sftpwarden.yaml
sftpwarden info --json

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Shows a registered context.
--config	PATH	none	Resolves and shows the context for a config path.
--json	flag	false	Prints the context model as JSON.

Effects

Read-only. Use it when you are not sure which context a command will use.

sftpwarden doctor

Checks whether local external tools are available.

sftpwarden doctor
sftpwarden doctor --json

Options

Flag	Value	Default	What it does
--json	flag	false	Prints tool availability as JSON.

Checks

It checks for tools used by deployment and remote workflows: docker, ssh, rsync or scp, kubectl, and helm.

sftpwarden health

Checks project and runtime health for a context.

sftpwarden health
sftpwarden health --context prod
sftpwarden health --json

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Selects a registered context.
--json	flag	false	Prints health checks as JSON and exits 0 for healthy, 1 for unhealthy.

Effects

Health is read-only. It validates config, provider readability, generated deployment drift, provider schema drift, runtime health when available, and remote availability for remote-only contexts.

If a remote-only context points at a remote root that was manually deleted, SFTPWarden removes only the stale local registry entry. If the remote server does not respond, the context is kept and the command reports the SSH connectivity failure clearly.

sftpwarden backup

Creates a .tar.gz backup of operational project state.

sftpwarden backup --output sftpwarden-prod.tar.gz --yes
sftpwarden backup --include-data --output full-backup.tar.gz
sftpwarden backup --dry-run --json

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Selects a registered context.
--output, -o	PATH	timestamped archive name	Archive path to create.
--include-data	flag	false	Includes SFTP user data under data/. Without it, operational state is backed up but user files are excluded.
--dry-run	flag	false	Prints backup entries without writing an archive.
--json	flag	false	Prints backup result and entries as JSON.
--yes, -y	flag	false	Accepts the --include-data confirmation prompt.

Effects

Backups may include config, generated deployment files, host keys, runtime state, raw local provider files, and a normalized provider user snapshot. Treat backups as sensitive.

sftpwarden restore

Restores a SFTPWarden backup into the selected context.

sftpwarden restore sftpwarden-prod.tar.gz
sftpwarden restore sftpwarden-prod.tar.gz --include-data --yes
sftpwarden restore sftpwarden-prod.tar.gz --dry-run --json

Arguments

Argument	Required	Value	What it means
backup_path	Yes	PATH	Backup archive to restore.

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Destination context.
--include-data	flag	false	Restores SFTP user data from the archive.
--dry-run	flag	false	Validates and reports restore entries without overwriting files.
--json	flag	false	Prints restore result, entries, and safety backup path as JSON.
--yes, -y	flag	false	Accepts restore confirmation prompts.

Effects

A real restore creates a safety backup before overwriting files. Restoring user data requires explicit confirmation unless --yes is used.