# CLI Reference

This reference documents the public `sftpwarden` command surface from the real
Typer application. It is written for operators who are new to SFTPWarden and need
to know what each command does, what each argument accepts, and which commands
change local files, remote hosts, containers, provider data, or Kubernetes
resources.

## How To Read Commands

`sftpwarden` is command-first:

```bash
sftpwarden <command> [options]
sftpwarden <group> <subcommand> [arguments] [options]
```

Most commands work against the active context. Select a different context for
one command with `--context <name>` or `-c <name>`. Use `--config <path>` only
when you want to bypass the context registry and point directly at a
`sftpwarden.yaml` file.

`sftpwarden.yaml` is desired state. Editing it manually, or changing it with
`sftpwarden config`, does not update running infrastructure by itself. Apply
deployment-level config changes with `sftpwarden deploy`, `sftpwarden kube
apply`, or `sftpwarden helm upgrade`. User/provider data changes are applied to
the running runtime with `sftpwarden refresh`, except Kubernetes YAML/CSV
providers, where the provider file is copied into the PVC during deploy/apply or
upgrade.

## Common Value Types

| Type | Accepted value |
| --- | --- |
| `TEXT` | Plain string. Quote values that contain spaces. |
| `INTEGER` | Whole number, for example `2200` or `12001`. |
| `BOOLEAN` | Usually a flag such as `--json`; for config values use YAML scalars such as `true` or `false`. |
| `PATH` | File or directory path. `~` is expanded by SFTPWarden where path expansion is supported. |
| `DSN` | Database URL such as `postgresql://user:pass@host:5432/sftpwarden`. Environment references like `${SFTPWARDEN_POSTGRES_DSN}` are accepted in config. |
| `REMOTE` | Remote URL in `user@host:/path` form. |

## Common Flags

| Flag | Value | What it does |
| --- | --- | --- |
| `--context`, `-c` | `TEXT` | Runs the command against one registered context without changing the active context. |
| `--config` | `PATH` | Reads a specific `sftpwarden.yaml` file directly. |
| `--json` | flag | Prints machine-readable JSON instead of Rich tables or human text. |
| `--dry-run` | flag | Prints the planned operation without writing files, touching containers, or mutating remote resources. |
| `--yes`, `-y` | flag | Accepts confirmation prompts for scripts and CI. Use it only when the action is intentional. |
| `--help` | flag | Shows command help generated by Typer. |

## Shell Completion

Install completion for the current shell:

```bash
sftpwarden --install-completion
```

Print the completion script without installing it:

```bash
sftpwarden --show-completion
```

## Command Sections

The command pages below are also available in the left navigation under the
Reference section. Each page documents its commands and subcommands with
arguments, options, examples, and operational effects.

- [Init Commands](cli/init.md): project creation and provider schema selection.
- [Core Commands](cli/core.md): deploy, validate, compose, plan, refresh, health,
  backup, and restore.
- [User Commands](cli/users.md): user listing, creation, updates, disable/enable,
  and removal.
- [User Key Commands](cli/user-keys.md): named key listing, add/remove,
  lifecycle, rotation, expiry, and import.
- [Provider Commands](cli/providers.md): provider export/import/copy and schema
  migration commands.
- [Context Commands](cli/contexts.md): context registry, active context, remote
  metadata, cleanup, and dynamic context fields.
- [Config Commands](cli/config.md): `sftpwarden.yaml` inspection and supported
  config updates.
- [Watcher And Sync Commands](cli/watcher.md): remote local-sync planning,
  foreground watch, and watcher service installation.
- [Kubernetes Commands](cli/kubernetes.md): render, apply, status, logs, doctor,
  and delete.
- [Helm Commands](cli/helm.md): values, template, lint, upgrade, and uninstall.
- [Runtime Commands](cli/runtime.md): container-side runtime entrypoints used by
  the deployed image.

## Command Index

- [sftpwarden](cli/core.md#sftpwarden)
- [sftpwarden version](cli/core.md#sftpwarden-version)
- [sftpwarden init](cli/init.md#sftpwarden-init)
- [sftpwarden deploy](cli/core.md#sftpwarden-deploy)
- [sftpwarden validate](cli/core.md#sftpwarden-validate)
- [sftpwarden compose](cli/core.md#sftpwarden-compose)
- [sftpwarden plan](cli/core.md#sftpwarden-plan)
- [sftpwarden refresh](cli/core.md#sftpwarden-refresh)
- [sftpwarden info](cli/core.md#sftpwarden-info)
- [sftpwarden doctor](cli/core.md#sftpwarden-doctor)
- [sftpwarden health](cli/core.md#sftpwarden-health)
- [sftpwarden backup](cli/core.md#sftpwarden-backup)
- [sftpwarden restore](cli/core.md#sftpwarden-restore)
- [sftpwarden users](cli/users.md#sftpwarden-users)
- [sftpwarden user show](cli/users.md#sftpwarden-user-show)
- [sftpwarden user create](cli/users.md#sftpwarden-user-create)
- [sftpwarden user update](cli/users.md#sftpwarden-user-update)
- [sftpwarden user disable](cli/users.md#sftpwarden-user-disable)
- [sftpwarden user enable](cli/users.md#sftpwarden-user-enable)
- [sftpwarden user remove](cli/users.md#sftpwarden-user-remove)
- [sftpwarden user key list](cli/user-keys.md#sftpwarden-user-key-list)
- [sftpwarden user key show](cli/user-keys.md#sftpwarden-user-key-show)
- [sftpwarden user key add](cli/user-keys.md#sftpwarden-user-key-add)
- [sftpwarden user key remove](cli/user-keys.md#sftpwarden-user-key-remove)
- [sftpwarden user key disable](cli/user-keys.md#sftpwarden-user-key-disable)
- [sftpwarden user key enable](cli/user-keys.md#sftpwarden-user-key-enable)
- [sftpwarden user key rename](cli/user-keys.md#sftpwarden-user-key-rename)
- [sftpwarden user key rotate](cli/user-keys.md#sftpwarden-user-key-rotate)
- [sftpwarden user key expire](cli/user-keys.md#sftpwarden-user-key-expire)
- [sftpwarden user key import](cli/user-keys.md#sftpwarden-user-key-import)
- [sftpwarden provider export](cli/providers.md#sftpwarden-provider-export)
- [sftpwarden provider import](cli/providers.md#sftpwarden-provider-import)
- [sftpwarden provider copy](cli/providers.md#sftpwarden-provider-copy)
- [sftpwarden provider schema show](cli/providers.md#sftpwarden-provider-schema-show)
- [sftpwarden provider schema migrate](cli/providers.md#sftpwarden-provider-schema-migrate)
- [sftpwarden provider keys migrate](cli/providers.md#sftpwarden-provider-keys-migrate)
- [sftpwarden context ls](cli/contexts.md#sftpwarden-context-ls)
- [sftpwarden context current](cli/contexts.md#sftpwarden-context-current)
- [sftpwarden context use](cli/contexts.md#sftpwarden-context-use)
- [sftpwarden context default](cli/contexts.md#sftpwarden-context-default)
- [sftpwarden context show](cli/contexts.md#sftpwarden-context-show)
- [sftpwarden context add](cli/contexts.md#sftpwarden-context-add)
- [sftpwarden context rename](cli/contexts.md#sftpwarden-context-rename)
- [sftpwarden context remove](cli/contexts.md#sftpwarden-context-remove)
- [sftpwarden context clear](cli/contexts.md#sftpwarden-context-clear)
- [sftpwarden context FIELD](cli/contexts.md#sftpwarden-context-field)
- [sftpwarden config PATH](cli/config.md#sftpwarden-config-path)
- [sftpwarden config show](cli/config.md#sftpwarden-config-show)
- [sftpwarden config default-provider](cli/config.md#sftpwarden-config-default-provider)
- [sftpwarden sync](cli/watcher.md#sftpwarden-sync)
- [sftpwarden watch](cli/watcher.md#sftpwarden-watch)
- [sftpwarden watcher status](cli/watcher.md#sftpwarden-watcher-status)
- [sftpwarden watcher install](cli/watcher.md#sftpwarden-watcher-install)
- [sftpwarden watcher uninstall](cli/watcher.md#sftpwarden-watcher-uninstall)
- [sftpwarden kube render](cli/kubernetes.md#sftpwarden-kube-render)
- [sftpwarden kube apply](cli/kubernetes.md#sftpwarden-kube-apply)
- [sftpwarden kube status](cli/kubernetes.md#sftpwarden-kube-status)
- [sftpwarden kube logs](cli/kubernetes.md#sftpwarden-kube-logs)
- [sftpwarden kube doctor](cli/kubernetes.md#sftpwarden-kube-doctor)
- [sftpwarden kube delete](cli/kubernetes.md#sftpwarden-kube-delete)
- [sftpwarden helm values](cli/helm.md#sftpwarden-helm-values)
- [sftpwarden helm template](cli/helm.md#sftpwarden-helm-template)
- [sftpwarden helm lint](cli/helm.md#sftpwarden-helm-lint)
- [sftpwarden helm upgrade](cli/helm.md#sftpwarden-helm-upgrade)
- [sftpwarden helm uninstall](cli/helm.md#sftpwarden-helm-uninstall)
- [sftpwarden runtime plan](cli/runtime.md#sftpwarden-runtime-plan)
- [sftpwarden runtime refresh](cli/runtime.md#sftpwarden-runtime-refresh)
- [sftpwarden runtime sync](cli/runtime.md#sftpwarden-runtime-sync)
- [sftpwarden runtime health](cli/runtime.md#sftpwarden-runtime-health)