Context Commands

A context is a named environment registered on the operator machine. It tells SFTPWarden where the project lives, which provider it uses, whether it is local or remote, and how remote sync should work.

sftpwarden context

Command group for the context registry. It also exposes dynamic field commands such as sftpwarden context root and sftpwarden context remote-root.

sftpwarden context --help

Subcommands:

• ls

• current

• use

• default

• show

• add

• rename

• remove

• clear

• dynamic field commands documented under sftpwarden context FIELD

sftpwarden context ls

Lists registered contexts.

sftpwarden context ls
sftpwarden context ls --json

Options

Flag	Value	Default	What it does
--json	flag	false	Prints the full context registry as JSON.

Cleanup Behavior

Before listing, SFTPWarden prunes local contexts whose local project folder was deleted manually. For remote local-sync contexts, this cleanup is local-only: it removes stale local registry and watcher traces but does not connect to the remote host or delete remote files.

Remote-only contexts have no local project folder to prune. Real remote commands such as deploy, refresh, health, or backup detect missing remote roots when they connect.

sftpwarden context current

Prints the active context name.

sftpwarden context current

Options

No command-specific options.

sftpwarden context use

Sets the active context.

sftpwarden context use dev

Arguments

Argument	Required	Value	What it means
name	Yes	TEXT	Existing registered context to make active.

Options

No command-specific options.

sftpwarden context default

Explicit form of sftpwarden context use.

sftpwarden context default prod

Arguments

Argument	Required	Value	What it means
name	Yes	TEXT	Existing registered context to make active.

Options

No command-specific options.

sftpwarden context show

Shows one context as JSON.

sftpwarden context show
sftpwarden context show prod

Arguments

Argument	Required	Value	What it means
name	No	TEXT	Context to show. If omitted, the active context is shown.

Options

No command-specific options.

sftpwarden context add

Registers an existing local or remote project.

sftpwarden context add dev
sftpwarden context add dev --root ~/sftpwarden-dev
sftpwarden context add prod [email protected]:/opt/sftpwarden --critical
sftpwarden context add archive [email protected]:/opt/sftpwarden --remote-only --critical

Arguments

Argument	Required	Value	What it means
name	Yes	TEXT	Context name to register.
remote_url	No	REMOTE	Optional user@host:/path remote URL. If omitted, SFTPWarden registers a local project.

Options

Flag	Value	Default	What it does
--root	PATH	.	Local project root for local and remote local-sync contexts.
--provider	yaml, csv, sqlite, mysql, mariadb, postgresql, mongodb	provider from local config, or global default for remote	Provider type stored in the registry.
--user	TEXT	parsed from remote URL or SSH default	Remote SSH user.
--port	INTEGER	global SSH default	Remote SSH port.
--remote-root	PATH	global remote root	Explicit remote project root.
--remote-only	flag	false	Registers a context that has no local project files.
--ssh-key	PATH	SSH default	Explicit SSH key for remote operations and Docker watcher mode.
--watcher	auto, systemd, openrc, runit, supervisord, launchd, windows-task, docker	auto when needed	Watcher backend to install or reuse for remote local-sync contexts.
--critical	flag	false	Marks the context as critical.
--skip-checks	flag	false	Skips remote prerequisite checks.
--yes, -y	flag	false	Accepts prompts, including production-like non-critical confirmation and watcher prompts.

When To Use It

Use context add when the SFTPWarden project already exists. Use sftpwarden init for new projects.

sftpwarden context rename

Renames a registered context.

sftpwarden context rename old-name new-name

Arguments

Argument	Required	Value	What it means
old_name	Yes	TEXT	Existing registered context.
new_name	Yes	TEXT	Replacement context name.

Options

No command-specific options.

sftpwarden context remove

Removes a context and cleans project-owned local resources.

sftpwarden context remove dev
sftpwarden context remove dev --yes
sftpwarden context remove prod --yes --delete-remote

Arguments

Argument	Required	Value	What it means
name	Yes	TEXT	Registered context to remove.

Options

Flag	Value	Default	What it does
--yes, -y	flag	false	Accepts local cleanup confirmation. For remote contexts, --yes keeps remote files unless --delete-remote is also used.
--delete-remote	flag	false	Also stops/removes remote runtime resources and deletes the remote project root for remote contexts.

Effects

For local Compose contexts, SFTPWarden stops the local Compose runtime when possible and removes project-owned local files when they are not shared with another context. For remote local-sync contexts, it removes the local synced project folder and watcher traces. Remote files are left untouched unless --delete-remote is explicitly requested or confirmed interactively.

sftpwarden context clear

Clears the active/default context.

sftpwarden context clear

Options

No command-specific options.

sftpwarden context FIELD

Reads or updates one field in the active context registry entry. If VALUE is omitted, the command prints the current value. If VALUE is supplied, the command updates the registry field.

sftpwarden context root
sftpwarden context root ~/sftpwarden-dev2 --yes
sftpwarden context remote-root /opt/sftpwarden-prod --yes
sftpwarden context type remote --remote [email protected]:/opt/sftpwarden --yes
sftpwarden context type local --yes

Arguments

Argument	Required	Value	What it means
FIELD	Yes	one supported field command	Registry field command, such as root, type, or remote-root.
VALUE	No	YAML-like scalar text	Replacement value. Omit it to read the current value.

Options

Flag	Value	Default	What it does
--context, -c	TEXT	active context	Context entry to read or edit.
--remote	REMOTE	prompt when converting to remote	Remote URL used when changing type to remote.
--root	PATH	existing root or generated default	Local root used by root moves or type conversion.
--user	TEXT	existing remote user or SSH default	Remote SSH user used by type conversion.
--port	INTEGER	existing or default SSH port	Remote SSH port used by type conversion.
--remote-root	PATH	existing or default remote root	Remote root used by type conversion.
--remote-only	flag	false	Creates a remote-only registry entry when converting to remote.
--delete-old-root	flag	false	Deletes the previous local root after copying it during root migration.
--yes, -y	flag	false	Accepts prompts for root copy/delete, remote-root updates, type conversion, and watcher cleanup.

Supported Field Commands

Command	Registry field	Notes
name	name	Renames the context and updates project.name in local sftpwarden.yaml when present.
type	type	Accepts local or remote. Type conversion may add or remove remote metadata.
root	root	Copies project files to the new root and updates the registered config path.
config	config	Direct registry config path. Use carefully.
provider	provider	Provider type stored in the registry.
critical	critical	Boolean critical-context flag.
storage	storage	Remote storage mode, normally local-sync or remote-only depending context type.
watcher-required, watcher_required	watcher_required	Boolean flag used by watcher planning.
remote-root, remote_root, remote.remote_root	remote.remote_root	Remote project root. Updates dependent remote config path.
remote-config, remote_config, remote.remote_config	remote.remote_config	Remote path to sftpwarden.yaml.
ssh-key, ssh_key, remote.ssh_key	remote.ssh_key	Explicit remote SSH key path.
host, remote.host	remote.host	Remote SSH host.
user, remote.user	remote.user	Remote SSH user.
port, remote.port	remote.port	Remote SSH port.
compose-file, compose_file, remote.compose_file	remote.compose_file	Remote Compose file path/name.

Safety

Changing context registry fields changes how future commands find and operate on projects. It does not move remote files automatically. After changing fields that affect deployment, run sftpwarden deploy to apply project desired state.