Credentials vault CLI reference
The safeguard vault, safeguard secrets and safeguard hostscan commands, the /vault panel in the interactive terminal, and the runner's vault settings.
Credentials vault CLI reference
Sign in first with safeguard login. No command here prints a secret. Update the CLI with safeguard self-update.
safeguard vault
| Command | What it does |
|---|---|
safeguard vault list [--scope shared|personal] [--json] | List entries with their kind (stored or PAM) and provider. |
safeguard vault show <handle|id> [--json] | Show one entry, never its secret. |
safeguard vault add --name <name> --kind stored [--secret-stdin] | Add a stored entry. The secret is read from a hidden prompt, or from stdin with --secret-stdin, never from a flag. |
safeguard vault add --name <name> --kind pam --provider <type> --pam-ref <reference> | Add a PAM entry, for example --provider arcon --pam-ref pam://arcon/Windows/10.0.5.17/svc_scan. |
safeguard vault test <handle|id> [--json] | Read an entry on this machine the way a scan would, print OK or the reason, and record a TEST in the audit trail. |
safeguard vault providers [--json] | Check this machine's secret-providers.yaml: each provider and whether it is complete, the allowed_refs of each, whether env:// and file:// are allowed, and where the local audit file is written. Reads no secret. |
vault add also takes --ref <handle>, --username, --notes, --category and --scope. Entries are shared with your organization by default, which is what scans use.
Manage a credential
These commands manage entries in the vault. The ones that use a policy need the vault controls to be on for your organization and the permission the action needs (see Roles and grants). None prints a value. Each takes --scope shared|personal (default shared).
| Command | What it does |
|---|---|
safeguard vault edit <handle|id> | Change an entry's name, user name, notes or PAM reference. --secret-stdin replaces its secret from stdin, which becomes a new version when a policy is on. |
safeguard vault delete <handle|id> [--yes] | Delete an entry. It asks you to type its reference to confirm, unless --yes is given. |
safeguard vault history <handle|id> [--limit 50] [--json] | Show the entry's audit history: reveals, fetches, check-outs, approvals, rotations. |
safeguard vault versions <handle|id> [--json] | List the versions of an entry that has a policy, with state, time and origin. |
safeguard vault rotate <handle|id> [--runner <name>] [--json] | Queue a rotation now. The runner in the policy, or --runner, does it. |
safeguard vault rotate <handle|id> --manual [--username <name>] | Add a new version yourself. The value is read from stdin or a hidden prompt. |
safeguard vault policy show <handle|id> | Print the policy as JSON. |
safeguard vault policy set <handle|id> [flags] | Change the policy. Flags are merged over the current policy. |
printf '%s' "$NEW_PW" | safeguard vault edit web-login --secret-stdin
safeguard vault rotate db-ssh --runner runner-avault policy set takes:
| Flag | Meaning |
|---|---|
--enable, --disable | Turn the policy on or off. |
--require-approval, --no-approval | Whether a use needs an approver's yes. |
--write-only | The value is never shown. |
--exclusive | One active lease at a time. |
--lease-ttl, --max-lease-ttl, --approval-window, --fresh-auth | Durations such as 15m, 4h, 1h. |
--bind-target, --bind-scan-type, --bind-runner | Bindings. Repeat the flag for more than one value. Each list replaces the old one. |
--file <policy.json> | A policy as JSON (including grants and rotation). Flags are applied on top. |
--json | Print the stored policy as JSON. |
safeguard vault policy set web-login --enable --require-approval --lease-ttl 15m \
--bind-target 'https://app.example.com/*' --bind-scan-type dastvault requests
safeguard vault requests [list] [--state PENDING] [--mine] [--json]
safeguard vault requests approve <number|credential> [--comment <text>] [--yes]
safeguard vault requests deny <number|credential> --comment <text> [--yes]list shows requests in the given state (PENDING, APPROVED, DENIED, EXPIRED or CANCELLED) that you can decide, or with --mine the ones you opened, each with a number. approve and deny take that number, or the credential's name, and ask you to confirm unless --yes is given. A denial needs a --comment that says why. Both need the APPROVE permission and a recent sign-in when the policy asks for one. You cannot approve your own request.
vault audit
safeguard vault audit [--from <date>] [--to <date>] [--credential <handle|id>] [--action <action>] \
[--actor <email|subject>] [--scan <scan-ref>] [--limit 100] [--cursor <c>] [--json]
safeguard vault audit --export csv --out vault-audit.csv
safeguard vault audit --export jsonl --out vault-audit.jsonlReads the tenant-wide audit log with the same filters as the app. Vault admins and auditors see every row, others the rows of credentials they can view. --export downloads the whole filtered log to the --out file (mode 600) and is recorded in the log. See Audit.
vault import
safeguard vault import --from chrome|edge|brave|arc|opera|firefox|safari|1password|bitwarden|lastpass|csv <file>Reads a CSV export on this machine, shows the entries with duplicates marked, and imports the entries you choose into your personal vault. Passwords are never printed. Flags: --on-duplicate skip|update, --yes, --dry-run and --json. Opera files are recorded as csv, and Arc has no password export of its own. See Import from a browser or password manager.
vault providers and provider-types
safeguard vault provider-types [--json]
safeguard vault providers register --from-config <name> [--runner <runner>]
safeguard vault providers register --name <name> --type <type> --url <address> --runner <runner> [--auth-method <m>] [--notes <t>]provider-types lists every credential source this CLI can read: the Safeguard vault, your PAM products, and the local env and file. --json prints the full descriptors: reference syntax and example, the fields of a reference, the settings of a provider file entry, and the capabilities. It is the same description the app builds its forms from.
providers register tells the vault about a provider so the Providers tab lists it. --from-config takes the name, type, address and sign-in method from this machine's secret-providers.yaml. Only descriptive settings are sent, never a secret. The name must equal the name in the runner's file.
safeguard secrets test
safeguard secrets test <reference> [--json]Reads one reference (sgvault://, pam://, vault://, env:// or file://) on this machine and prints OK, the provider and a length class (short, medium, long), or the code and reason. Exits 0 on success and 1 otherwise. Use it in a runner's health check.
safeguard hostscan
safeguard hostscan --host <host>[,<host>...] | --cidr <range> \
(--ssh-user <user> | --winrm-user <user>) --credential <reference> [options]| Option | Meaning |
|---|---|
--host, --cidr | Hosts, or an IPv4 range up to a /24. At most 256 hosts. |
--protocol, --port | ssh (22) or winrm (5986). --winrm-user implies winrm. |
--credential, --key-passphrase | References to the password or private key, and the key's passphrase. A literal secret is refused. |
--known-hosts, --host-key-fingerprint, --trust-on-first-scan | How SSH host keys are trusted. |
--winrm-ca, --winrm-allow-http | The CA of the hosts' WinRM certificates; plain HTTP on 5985 (not recommended). |
--match | Match each Linux host's packages against advisories on this machine. |
--output-dir, --concurrency, --json | Where the SBOMs and report go, hosts at once, JSON report. |
The /vault panel
In the interactive terminal, /vault opens a panel in the same style as /mcp and /skills: entries with a kind badge and provider, Enter for details, t to test on this machine. /vault list, /vault providers and /vault test <reference> run the same actions directly, and /vault import runs the import with a picker.
Runner settings
A running runner reads its provider file at every scan start and checks in with the vault about every 30 seconds, so the app can show provider status and run Test access.
| Variable | Meaning |
|---|---|
SAFEGUARD_RUNNER_NAME | The runner's name in the vault and the audit trail (default: host name). |
SAFEGUARD_VAULT_CHECKIN=off | No check-in (no provider status, no Test access). Scans still read credentials. |
SAFEGUARD_SECRET_PROVIDERS | Another path for the provider file. |
SAFEGUARD_VAULT_AUDIT_FILE | Another path for the local audit file, or off. |
A runner also claims rotations through its check-in and executes them (SSH password, SSH key, HTTP token) when it is the runner named in a credential's rotation. The setting native.approval_wait in the provider file sets how long a scan waits for an approval.
See Runner configuration for every provider setting.
Troubleshooting
Error codes for credential reads, what each means and how to fix it, and the common problems with PAM entries, runners, DAST, API and host scans.
Add a credential provider
How credential sources are built as strategies in the Safeguard CLI and platform, the optional capabilities a strategy can add, and the steps to add a new PAM or secret store.