CLI Reference

CLI Reference

Xferity is operated primarily through the xferity CLI. This page documents all commands, subcommands, and global flags.

Global flags

These flags are available on every command:

Flag	Default	Description
--config path	./config/config.yaml	Path to the configuration file
--env-file path	—	Load a .env-format file into the process environment before starting
--verbose, -v	false	Enable verbose output to stderr
--dry-run	false	Execute flow logic without transferring, encrypting, or deleting any files
--expect-existing-state	false	Fail startup if the licensing state file is absent (use on hardened production nodes after initial deployment)

Using --env-file

The --env-file flag loads a file containing KEY=VALUE pairs into the process environment before configuration is read. This is useful for injecting secrets into an env: reference environment without modifying the process environment externally.

xferity run payroll-upload --env-file /run/secrets/xferity.env

File format:

SFTP_PASSWORD=secret123
DB_PASSWORD=dbsecret456
# Comments are allowed
export SOME_VAR=value   # export prefix is stripped

Using --dry-run

Dry-run executes the full flow logic — file discovery, idempotency checks, PGP key resolution — but does not perform any actual file transfers, encryptions, deletions, or uploads. Use it to verify flow configuration before enabling it in production.

xferity run payroll-upload --dry-run
xferity run-all --dry-run

---

xferity run

Run a specific named flow once.

xferity run <flow-name> [flags]

Example:

xferity run payroll-sftp-upload
xferity run payroll-sftp-upload --dry-run
xferity run payroll-sftp-upload --config /etc/xferity/config.yaml

The flow is loaded from the flows_path directory configured in config. The flow runs once and exits. Use xferity run-service for scheduled/daemon execution.

---

xferity run-all

Run all enabled flows in sequence.

xferity run-all [flags]

Executes every flow that has enabled: true (or equivalent). Reports per-flow success or failure. Does not stop on the first failure — all flows are attempted.

Example:

xferity run-all
xferity run-all --dry-run

---

xferity run-service

Run Xferity as a background worker service.

xferity run-service [flags]

In service mode, Xferity:

• Polls the job queue at the configured worker.poll_interval (default: 1s)
• Executes scheduled flows according to their schedule_cron configuration
• Processes queued jobs including retries
• Runs until the process is terminated

This is the standard production invocation. Use it with Docker or a process supervisor (systemd, supervisor).

Example:

xferity run-service --config /etc/xferity/config.yaml
xferity run-service --expect-existing-state  # hardened production

Docker Compose example:

command: run-service --config /config/config.yaml --expect-existing-state

---

xferity resume

Resume a previously interrupted or failed flow from its last committed state.

xferity resume [flow-name] [flags]

When called without a flow name, resumes all flows that have incomplete state. When called with a flow name, resumes only that flow.

Resume is idempotent: files already successfully transferred are tracked by their SHA-256 content hash and are not re-transferred.

Example:

xferity resume                      # resume all incomplete flows
xferity resume payroll-sftp-upload  # resume specific flow
xferity resume payroll-sftp-upload --dry-run

When to use resume:

• After a network failure mid-transfer
• After an unexpected process termination
• After a scheduled flow did not complete its run window
• After manually interrupting a long-running flow for maintenance

---

xferity validate

Validate the configuration file and all flow YAML files.

xferity validate [flags]

Performs all startup validation checks without starting any services:

• Config YAML syntax and required field validation
• Flow YAML syntax validation
• Hardened mode enforcement (if security.hardened_mode: true)
• Secret reference format validation
• Partner configuration validation

Exits with code 0 on success, non-zero on any error.

Example:

xferity validate
xferity validate --config /etc/xferity/config.yaml

Use before deployment to catch configuration errors early:

xferity validate && docker compose up -d

---

xferity diag

Run diagnostics and print a system status report.

xferity diag [flags]

Outputs:

• Configuration summary (without secrets)
• State backend connectivity
• Flow inventory (names, enabled status, schedule)
• Partner inventory
• Licensing status

Example:

xferity diag
xferity diag --config /etc/xferity/config.yaml

---

xferity logs

View or tail transfer logs.

xferity logs [flow-name] [flags]

Without a flow name, shows logs from all flows. With a flow name, filters to that flow.

Example:

xferity logs
xferity logs payroll-sftp-upload

---

xferity flow

Subcommand group for flow status and history.

xferity flow status

xferity flow status [flow-name]

Show the current status of a flow (running, completed, failed, idle). Without a flow name, shows status for all flows.

xferity flow history

xferity flow history [flow-name]

Show execution history for a flow. Without a flow name, shows history for all flows.

---

xferity trace

Trace specific transfer events from the audit log.

xferity trace [flags]

Queries the audit log index for specific events. Useful for investigating a specific file’s transfer history.

Example:

xferity trace --flow payroll-sftp-upload
xferity trace --file invoice-2026-03.xml

---

xferity ui

Start the Xferity web UI server.

xferity ui [flags]

Starts the HTTP server for the web management interface. The UI is also started automatically when ui.enabled: true is set in the config and xferity run-service is used.

Example:

xferity ui --config /etc/xferity/config.yaml

The UI listens on the address and port configured in ui.host and ui.port.

---

xferity vault

Subcommand group for the local encrypted secrets vault.

xferity vault seed

Initialize or update the local vault with secrets.

xferity vault seed [flags]

Seeds the local encrypted vault (local-vault: secret provider). The vault stores secrets encrypted with AES-256. The master key is provided via MFT_MASTER_KEY environment variable (or secrets.local_vault.master_key_ref in config).

Example:

MFT_MASTER_KEY=your-base64-key xferity vault seed

---

xferity license

License management commands.

xferity license [subcommand]

Subcommands include status, reload, and validation. Used to manage the Xferity license file and check current license state.

---

xferity operator

Operator administration commands.

xferity operator [subcommand]

Administrative commands for operations teams. Includes health check and maintenance utilities.

---

xferity version

Print the version of the Xferity binary.

xferity version

---

Exit codes

Code	Meaning
0	Success
1	Error (configuration, runtime failure, or flow failure)

---

Environment variables

All configuration values can be overridden with environment variables using the FTO_ prefix. For example, FTO_FLOWS_PATH=/data/flows overrides flows_path in config.

The env prefix is FTO (legacy name before rebranding). Secret references using env:VAR_NAME read from the process environment without any prefix.

---

See Also

• Configuration Reference
• Flow Reference
• Hardened Mode
• Retry and Recovery