Enum Commands

Source

pub enum Commands {
Show 48 variants    Init,
    Config {
        action: ConfigAction,
    },
    Set {
        key: String,
        value: Option<String>,
        tags: Vec<String>,
        overwrite: bool,
    },
    Get {
        key: String,
        copy: bool,
        version: Option<usize>,
    },
    Delete {
        key: String,
    },
    List {
        tags: Vec<String>,
        ns: Option<String>,
    },
    Export {
        format: ExportFormat,
        keys: Vec<String>,
        tags: Vec<String>,
        ns: Option<String>,
    },
    Exec {Show 18 fields
        contract: Option<String>,
        ns: Option<String>,
        keys: Vec<String>,
        mode: Option<ExecModeSetting>,
        timeout: Option<u64>,
        preset: Option<ExecPresetSetting>,
        dry_run: bool,
        plan: bool,
        no_inherit: bool,
        minimal: bool,
        only: Vec<String>,
        require: Vec<String>,
        env_mappings: Vec<String>,
        deny_dangerous_env: bool,
        allow_dangerous_env: bool,
        redact_output: bool,
        no_redact_output: bool,
        cmd: Vec<String>,
    },
    Import {
        from: String,
        file: Option<String>,
        overwrite: bool,
        skip_duplicates: bool,
        ns: Option<String>,
        dry_run: bool,
    },
    Rotate,
    RotateKey {
        profile: Option<String>,
    },
    Profile {
        action: ProfileAction,
    },
    Audit {
        limit: usize,
        hibp: bool,
        explain: bool,
        json: bool,
        cell_id: Option<String>,
    },
    Validate {
        cellos_policy: Option<PathBuf>,
        policy_file: Option<PathBuf>,
        json: bool,
    },
    Snapshot {
        action: SnapshotAction,
    },
    KvPull {
        prefix: Option<String>,
        overwrite: bool,
        on_error: PullOnError,
    },
    KvPush {
        prefix: Option<String>,
        ns: Option<String>,
        dry_run: bool,
        yes: bool,
        delete_missing: bool,
    },
    Gen {
        key: String,
        length: usize,
        charset: String,
        words: Option<usize>,
        tags: Vec<String>,
        print: bool,
        exclude_ambiguous: bool,
    },
    Diff,
    Compare {
        profile_b: String,
    },
    History {
        key: String,
    },
    Mv {
        source: String,
        dest: Option<String>,
        to_profile: Option<String>,
        force: bool,
    },
    AuditExport {
        format: AuditExportFormat,
        output: Option<String>,
    },
    AuditVerify {
        json: bool,
    },
    Policy {
        action: PolicyAction,
    },
    RotateDue {
        json: bool,
        fail: bool,
    },
    Completions {
        shell: Shell,
    },
    CompletionsData {
        data_type: String,
    },
    Doctor {
        json: bool,
    },
    Explain {
        topic: Option<ExplainTopic>,
    },
    Unlock,
    Ui,
    Qr {
        key: String,
    },
    Totp {
        action: TotpAction,
    },
    Pin {
        key: String,
    },
    Unpin {
        key: String,
    },
    Alias {
        target_key: Option<String>,
        alias_name: Option<String>,
        list: bool,
    },
    Template {
        file: String,
        output: Option<String>,
        ignore_missing: bool,
    },
    Redact,
    BuildInfo {
        json: bool,
    },
    SshAdd {
        key: String,
    },
    SshImport {
        path: String,
        name: Option<String>,
        tags: Vec<String>,
    },
    Ssh {
        action: SshAction,
    },
    Ns {
        action: NsAction,
    },
    Push {
        config: Option<PathBuf>,
        source: Vec<String>,
        dry_run: bool,
        yes: bool,
        delete_missing: bool,
        on_error: PushOnError,
    },
    Team {
        action: TeamAction,
    },
    Biometric {
        action: BiometricAction,
    },
    Agent {
        action: AgentAction,
    },
}

Variants§

§

Init

Initialise a new encrypted vault for the current profile.

Creates the vault file for this profile under the platform data directory. Prompts for a master password twice.

On an interactive terminal, after the vault is created you may be offered “quick unlock”: storing the password in the OS credential store (Touch ID / Face ID / Windows Hello / device PIN where the OS supports it). You can accept, defer, or skip; run tsafe biometric enable anytime.

If tsafe config set-backup-vault main (or default) is set, the new vault’s master password is also stored under profile-passwords/<profile> in that vault when possible.

§

Config

View or change global settings (config.json): password backup target, default profile, etc.

Use config set-backup-vault main so every new vault’s master password is also stored under profile-passwords/<profile> in the main vault (requires that vault to exist and be unlockable when you create more profiles).

Fields

§action: ConfigAction

§

Set

Store or update a secret in the vault.

If VALUE is omitted on a TTY, you are prompted with masked input (typically * per character). Piped / non-interactive stdin reads a single line. Keys may be namespaced with . or - (e.g. github.com.token, db-prod.PASSWORD).

If the key already exists the command will prompt for confirmation (on a TTY) or exit with an error (non-TTY). Pass –overwrite to skip the check.

Fields

§key: String

Secret key (e.g. DB_PASSWORD, github.com.token).

§value: Option<String>

Secret value. Omit for a masked TTY prompt or a line from stdin when piped.

§tags: Vec<String>

Attach tags as KEY=VALUE pairs (repeatable).

§overwrite: bool

Overwrite the key if it already exists — skips the confirmation prompt.

§

Get

Retrieve a secret and print its plaintext value.

Use –copy to copy to clipboard instead of printing; the clipboard is cleared after 30 s. Use –version to retrieve a previous version (0=current, 1=previous, etc.).

Fields

§key: String

Secret key.

§copy: bool

Copy value to clipboard and clear after 30 seconds (does not print).

§version: Option<usize>

Retrieve a previous version (0=current, 1=previous, etc.).

§

Delete

Permanently remove a secret from the vault.

The deletion is recorded in the audit log and a snapshot is taken before removal.

Fields

§key: String

Secret key.

§

List

List all secret key names stored in the vault.

Use –tag to filter by attached metadata. Use –ns to filter to a specific namespace (e.g. “cds-adf”).

Fields

§tags: Vec<String>

Filter to secrets with this tag (KEY=VALUE). Repeatable.

§ns: Option<String>

Filter to keys in this namespace (stored as “/”).

§

Export

Print secrets to stdout in the chosen format.

Formats: env (default), dotenv, powershell, json, github-actions, yaml, docker-env. Use –ns to export only keys from a namespace; the prefix is stripped so the output contains plain KEY=VALUE (e.g. APP_PW not cds-adf/APP_PW).

Fields

§format: ExportFormat

Output format.

§keys: Vec<String>

Limit to specific keys (all keys if omitted).

§tags: Vec<String>

Filter to secrets with this tag (KEY=VALUE). Repeatable.

§ns: Option<String>

Filter to keys in this namespace; prefix is stripped in output.

§

Exec

Execute a command with secrets injected into its environment.

Secrets are injected as env vars; the child inherits all other env vars. Ctrl-C is forwarded to the child and tsafe exits with the child’s exit code. Use –ns to inject only secrets from a namespace (prefix stripped from var names).

Use –contract to load a named authority contract from the nearest .tsafe.yml manifest. A contract declares profile, namespace, allowed secrets, required secrets, allowed targets, and trust posture as a reusable, auditable policy. Explicit flags still override contract values.

Fields

§contract: Option<String>

Load a named authority contract from the nearest .tsafe.yml (or .tsafe.json) manifest. The contract sets the profile, namespace, allowed/required secrets, allowed targets, and trust posture. Explicit flags (–ns, –keys, –mode, etc.) still override contract values.

§ns: Option<String>

Inject only secrets from this namespace; prefix is stripped from env var names.

§keys: Vec<String>

Inject only these vault keys (after --ns prefix stripping). Comma-separated or repeat flag. Missing selected keys abort the run so narrower injection does not silently degrade.

§mode: Option<ExecModeSetting>

Trust preset for this run. standard keeps broad compatibility, hardened applies a stricter preset, and custom uses your persisted exec trust settings. Explicit flags still override the preset.

§timeout: Option<u64>

Kill the child process after this many seconds and exit non-zero. Default: no timeout.

§preset: Option<ExecPresetSetting>

Preset for inherited parent environment. minimal keeps only PATH and a safe core set (equivalent to –minimal). full inherits the full parent environment minus the strip list (equivalent to the default). Explicit –no-inherit, –minimal, and –only override this.

§dry_run: bool

List env var names that would be injected (sorted, one per line) and exit 0; no command is run.

§plan: bool

Show a human-readable plan: profile, namespace, injected names, –require checks, parent env strips, and a copy-paste run line. Exit 0; no command is run.

§no_inherit: bool

Start from a clean environment: no parent env vars are inherited. Only vault secrets (and any –only keys) are visible to the child. Mutually exclusive with –only and –minimal.

§minimal: bool

Inherit only a safe minimal set of parent env vars (PATH, HOME, USER, TMPDIR, LANG, TERM, SSH_AUTH_SOCK, etc.) plus vault secrets. No tokens or credentials leak through. Mutually exclusive with –no-inherit and –only.

§only: Vec<String>

Inherit only these parent env vars (comma-separated or repeat flag); all others are stripped. Vault secrets are then added on top. Mutually exclusive with –no-inherit and –minimal.

§require: Vec<String>

Require these vault keys (after –ns mapping) to be present. Comma-separated or repeat flag.

§env_mappings: Vec<String>

Map a vault key to a different env var name in the child process. Format: ENV_VAR=VAULT_KEY (e.g. –env MY_DB=PROD_SECRET injects the vault value of PROD_SECRET under the name MY_DB). When –keys is also given, only vault keys that are in the –keys allowlist may be referenced; other vault keys are rejected with an error. Repeat the flag for multiple mappings.

§deny_dangerous_env: bool

Abort if any injected name is a known high-risk env var (e.g. NODE_OPTIONS, LD_PRELOAD). Redundant: this is now the default. Kept for backwards compatibility.

§allow_dangerous_env: bool

Allow injection of known high-risk env var names (e.g. LD_PRELOAD, NODE_OPTIONS). By default, dangerous names abort exec. Use this flag to inject them with a warning instead.

§redact_output: bool

Replace exact vault secret values in the child’s stdout/stderr with [REDACTED]. Useful for agent/tool wrappers where you trust the command less than the vault.

§no_redact_output: bool

Force raw child stdout/stderr even if config enables exec output redaction by default.

§cmd: Vec<String>

Command and its arguments (omit when using –dry-run or –plan).

§

Import

Import secrets from a .env file or another supported export source.

.env paths work in every build. Some builds may also accept additional source names for password-manager or browser CSV exports.

When --from is a named export source, --file is required. Skips keys that already exist unless –overwrite is passed.

Use –ns to prefix all imported keys with a namespace, e.g. “cds-adf”. Keys are stored as “/” allowing multiple projects in one vault without collision (e.g. cds-adf/APP_PW vs mail-automation/APP_PW).

If --from is a relative path that does not exist, the error includes extra hints and searches downward from the current directory (bounded depth; skips target/, node_modules/, .git/, etc.) for files with the same name (e.g. .env) so you can copy-paste a suggested tsafe import --from '…' line.

Fields

§from: String

.env file path or another supported source name for this build.

§file: Option<String>

Export file path (required when --from is a named export source).

§overwrite: bool

Overwrite existing keys (skip by default).

§skip_duplicates: bool

Skip duplicate keys silently instead of erroring (applies to both within-file duplicates and keys already in the vault).

§ns: Option<String>

Namespace prefix to prepend to imported keys (e.g. “cds-adf”). Keys are stored as “/”, preventing collisions across projects.

§dry_run: bool

Show what would be imported without writing any secrets to the vault. Prints each key and whether it would be skipped (existing) or imported.

§

Rotate

Re-encrypt all secrets with a new master password (vault re-key).

Prompts for the current password, then the new password twice (unless non-interactive). For automation / CI, set TSAFE_PASSWORD (current) and TSAFE_NEW_MASTER_PASSWORD (new); confirmation is skipped when both are set (no OS keychain prompt in that case — run biometric enable after). After interactive rotation, you are offered an OS keychain update so quick unlock matches the new password. A snapshot is taken automatically before rotation. tsafe doctor suggests periodic rotation.

§

RotateKey

Re-encrypt the vault with a new master password and update the biometric credential.

Prompts for the current password (or reads from TSAFE_PASSWORD), then the new password twice (or reads from TSAFE_NEW_MASTER_PASSWORD). The vault is written atomically via a temp-file rename. If biometric quick-unlock is active, the stored credential is re-stored under the new password so subsequent unlocks continue to work.

If the vault re-encryption succeeds but the biometric re-store fails, a warning is emitted directing the user to tsafe biometric re-enroll.

Fields

§profile: Option<String>

Profile to re-key (defaults to the active profile).

§

Profile

Manage profiles (named vaults).

Each profile is an independent vault file under the platform data vaults/ directory.

Fields

§action: ProfileAction

§

Audit

Display recent audit log entries for the current profile in human-readable form.

Fields

§limit: usize

Number of entries to display.

§hibp: bool

Check all secret values against Have I Been Pwned (k-anonymity, no full hash sent).

§explain: bool

Show a session-style explanation (grouped operations, exec authority summaries).

§json: bool

With --explain, print JSON instead of human text.

§cell_id: Option<String>

Filter entries to those with this CellOS cell ID in their audit context.

§

Validate

Cross-check authority contracts against a CellOS policy pack.

Loads authority contracts from the nearest .tsafe.yml and compares each contract’s allowed_secrets against allowedSecretRefs in the CellOS policy pack JSON. Reports mismatches and exits non-zero if any are found.

Use --policy-file as an alias for --cellos-policy (both accepted).

Fields

§cellos_policy: Option<PathBuf>

Path to the CellOS policy pack JSON file.

§policy_file: Option<PathBuf>

Alias for –cellos-policy. Path to the policy pack JSON file.

§json: bool

Emit machine-readable JSON output (exit codes are preserved).

§

Snapshot

Manage local vault snapshots.

Snapshots are encrypted copies of the vault file, taken automatically before every write operation. Use them to recover from accidental changes.

Fields

§action: SnapshotAction

§

KvPull

Pull secrets from Azure Key Vault into the local vault.

Requires TSAFE_AKV_URL and either a service principal (AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET) or a managed identity (IMDS, automatic inside Azure VMs / ACI).

Fields

§prefix: Option<String>

Only import secrets whose names start with this prefix (case-insensitive). Omit to pull all secrets.

§overwrite: bool

Overwrite existing local secrets (skip conflicts by default).

§on_error: PullOnError

Failure handling mode for provider/network errors.

§

KvPush

Push local vault secrets to Azure Key Vault (upsert semantics).

Requires TSAFE_AKV_URL and either a service principal (AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET) or a managed identity (IMDS, automatic inside Azure VMs / ACI).

Local keys are reverse-normalised to Azure Key Vault format: MY_SECRET → my-secret. Two local keys that normalise to the same provider name are detected as a collision and abort pre-flight.

Remote-only keys are left untouched unless –delete-missing is passed. A pre-flight diff is always shown before writing. No secret values are printed — only key names and 12-char SHA-256 hash prefixes.

Fields

§prefix: Option<String>

Only push secrets whose local key names start with this prefix (case-insensitive).

§ns: Option<String>

Only push secrets in this namespace (stored as <ns>/KEY).

§dry_run: bool

Show the diff without writing anything (always exits 0).

§yes: bool

Skip the confirmation prompt (required in non-TTY / CI contexts).

§delete_missing: bool

Also delete remote secrets that are absent locally within the filtered scope. Off by default — opt-in to avoid accidental mass deletion. AKV uses soft-delete (30-day recoverable window).

§

Gen

Generate a cryptographically random secret and store it in the vault.

Uses a CSPRNG. Default length 32, character set ‘alnum’.

Fields

§key: String

Key name to store the generated secret under.

§length: usize

Length of the generated secret in characters (ignored if –words is set).

§charset: String

Character set: alnum (default), alpha, numeric, hex, symbol.

§words: Option<usize>

Generate a passphrase of N random words instead of a random string.

§tags: Vec<String>

Attach tags as KEY=VALUE pairs (repeatable).

§print: bool

Print the generated value to stdout (otherwise the value is only in the vault).

§exclude_ambiguous: bool

Remove visually ambiguous characters (0, O, l, 1, I) from the charset. Useful when the secret will be read aloud or transcribed manually.

§

Diff

Show key-level changes between the current vault and its most-recent snapshot.

Highlights added, removed, and modified keys — values are never shown.

§

Compare

Compare key names across two profiles without decrypting any values.

Highlights keys present in one profile but missing from the other.

Fields

§profile_b: String

Second profile to compare against the active –profile.

§

History

Show version history for a secret.

Lists all stored versions with timestamps. Version 0 is the current value; higher numbers are older. Use tsafe get KEY --version N to retrieve a specific version.

Fields

§key: String

Secret key.

§

Mv

Move or rename a secret within the vault, or to a different profile.

Within a profile this is an atomic rename: key name, namespace prefix, tags and full version history are all preserved.

Fields

§source: String

Source secret key.

§dest: Option<String>

Destination key name. Omit when using –to-profile to keep the same key name.

§to_profile: Option<String>

Move the secret to this profile (cross-profile move).

§force: bool

Overwrite the destination key if it already exists.

§

AuditExport

Export audit log entries to stdout or a file as JSON or Splunk HEC events.

Fields

§format: AuditExportFormat

Output format.

§output: Option<String>

Write to a file instead of stdout.

§

AuditVerify

Report HMAC chain coverage for the audit log of the current profile.

Reads all entries from the audit log file and counts how many carry a prev_entry_hmac field (written by a C8-capable tsafe build) versus how many are unchained (written before C8 or at a session boundary).

IMPORTANT — ephemeral-key limitation: the HMAC chain key is generated fresh on every tsafe session and is never persisted. This command cannot perform cryptographic verification of entries from a closed session; it can only report chain coverage (presence of the field). To detect within-session tampering, use AuditLog::verify_chain() from a live session handle.

Exit codes: 0 = log is structurally valid (or empty), 2 = at least one entry could not be parsed as JSON.

Fields

§json: bool

Emit machine-readable JSON output.

§

Policy

Set or remove a rotation policy on a secret.

Policies are stored as tags and checked by tsafe doctor and tsafe rotate-due.

Fields

§action: PolicyAction

§

RotateDue

List secrets that are overdue for rotation (per rotate_policy tags).

Checks the rotate_policy tag against the secret’s updated_at timestamp. Use --json for automation; --fail exits with status 1 when anything is overdue (CI/cron).

Set policies with: tsafe policy set KEY --rotate-every 90d

Fields

§json: bool

Print JSON to stdout (overdue_count + items with key, days_overdue, policy).

§fail: bool

Exit with status 1 when one or more secrets are overdue.

§

Completions

Print a shell completion script and exit.

Fields

§shell: Shell

Shell to generate completions for.

§

CompletionsData

Output completion candidates for use by shell completion scripts (internal).

Called by the patched completion scripts generated by tsafe completions. Not intended for direct use.

Fields

§data_type: String

Type of completion data to emit: profiles or contracts.

§

Doctor

Diagnose vault health: file presence, snapshots, env vars, secret expiry, and operator-facing health hints.

Fields

§json: bool

Emit machine-readable JSON and use health exit codes (0=healthy, 1=warning, 2=critical).

§

Explain

Explain a concept in the terminal (exec, namespaces, compiled agent/browser pull lanes, …).

Omit the topic to list available explanations.

Fields

§topic: Option<ExplainTopic>

Topic to print (omit to list all topics).

§

Unlock

Remove a stale vault lock file (use after a crash leaves the vault locked).

Deletes <profile>.vault.lock if it exists. Safe to run — the lock is advisory only. Use when tsafe reports “vault is locked by another process” but no other process is actually running.

§

Ui

Launch the full-screen interactive terminal UI.

Supports add/edit/delete/reveal/rotate/snapshot restore and audit log viewing. Press ? inside the TUI for a contextual keyboard reference.

§

Qr

Render a secret value as a QR code in the terminal.

Opens the vault, retrieves KEY, prints the QR code to stdout, then waits for Enter before clearing — so the value is never left on-screen.

Fields

§key: String

Secret key whose value to render as a QR code.

§

Totp

Store a TOTP secret and retrieve live codes.

add: store a TOTP seed for the given key get: compute and print the current 6-digit code

Fields

§action: TotpAction

§

Pin

Pin a secret to the top of lists.

Fields

§key: String

§

Unpin

Remove pin from a secret.

Fields

§key: String

§

Alias

Create an alias: ALIAS_NAME resolves to an existing KEY.

tsafe get ALIAS_NAME returns the value of KEY. Use tsafe alias –list to view all aliases.

Fields

§target_key: Option<String>

Key this alias should resolve to (omit with –list to view all aliases).

§alias_name: Option<String>

Name of the alias to create.

§list: bool

List all aliases in the vault.

§

Template

Replace {{KEY}} placeholders in a file with vault secret values.

Reads the input file, replaces each {{KEY}} with the corresponding vault secret, and writes to stdout (or --output PATH).

Fields

§file: String

Input template file containing {{KEY}} placeholders.

§output: Option<String>

Write output to a file instead of stdout.

§ignore_missing: bool

Ignore missing keys instead of failing.

§

Redact

Read stdin and replace any vault secret values with [REDACTED].

Useful for piping logs through to scrub sensitive values.

§

BuildInfo

Show the active build profile label and compile-time capabilities.

This reports the compiled truth for the running tsafe binary only. Companion runtimes such as tsafe-agent have separate install and release truth.

Fields

§json: bool

Emit machine-readable JSON output.

§

SshAdd

Add an SSH key from the vault to the running ssh-agent.

The key is passed via stdin to ssh-add - so it never touches disk.

Fields

§key: String

Vault key name containing the SSH private key.

§

SshImport

Import an SSH private key file into the vault.

Fields

§path: String

Path to the SSH private key file.

§name: Option<String>

Vault key name to store under (defaults to filename).

§tags: Vec<String>

Attach tags as KEY=VALUE pairs (repeatable).

§

Ssh

SSH key inventory and operations.

Subcommands: list, public-key, generate, config, agent

Fields

§action: SshAction

§

Ns

List namespaces or copy/move all keys under one prefix to another.

A namespace is any key-prefix of the form “/KEY”. They are not stored explicitly — this command introspects the key names in the vault.

Fields

§action: NsAction

§

Push

Push local vault secrets to all destinations defined in .tsafe.yml.

Searches upward from the current directory for .tsafe.yml or .tsafe.json and executes each push destination in manifest order (sequential; see ADR-030).

Use –dry-run to preview which destinations would be invoked without making any live API calls or writes.

Use –source to narrow execution to one or more named destinations. Destinations are named with the name field in the manifest. Multiple –source flags are OR’d.

A pre-flight diff is shown before any writes. Secret values are never printed — only key names and 12-char SHA-256 hash prefixes are shown (ADR-030).

Fields

§config: Option<PathBuf>

Path to config file (auto-detected if omitted).

§source: Vec<String>

Narrow execution to destinations with this name label (repeatable). Destinations without a name field are excluded when any –source filter is active.

§dry_run: bool

Show the diff without writing anything (always exits 0).

§yes: bool

Skip confirmation prompts (required in non-TTY / CI contexts).

§delete_missing: bool

Also delete remote secrets that are absent locally within each destination’s scope. Off by default — opt-in to avoid accidental mass deletion (ADR-030).

§on_error: PushOnError

Failure handling mode for destination errors.

§

Team

Manage team vaults (multi-recipient age encryption).

Team vaults use X25519 (age) keypairs so multiple people can decrypt the same vault without sharing a password.

Fields

§action: TeamAction

§

Biometric

Enable or disable biometric / keyring unlock for the current profile.

When enabled, the vault password is stored in the OS credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service). The credential store is itself protected by biometric or PIN.

After tsafe init, the CLI may offer the same setup interactively (“quick unlock”). You can always run biometric enable later if you skipped it.

Fields

§action: BiometricAction

§

Agent

Manage the per-process vault unlock agent.

tsafe agent unlock prints terminal approval text, may show an OS notification, then prompts for the vault password once and starts a background agent that holds it in memory. The token it prints must be set in the calling process’s environment as TSAFE_AGENT_SOCK — all subsequent tsafe invocations that inherit that env var will be granted vault access without re-entering the password.

Requests must present the session token and come from a live OS-reported peer PID; the unlock process PID is recorded for audit/context, not as the only process allowed to use the session.