CLI Reference — sy

The sy command-line tool lets you interact with SyVault Secrets Manager from terminals, scripts, CI pipelines, and container entrypoints. It is a statically linked binary built from the crates/cli workspace member.

Installation

From crates.io:

cargo install syvault-cli

Pre-built binaries (Linux, macOS, Windows):

Download the latest release from the GitHub Releases page and place the sy binary on your PATH.

curl -fsSL https://get.syvault.com | sh

Verify the installation:

sy --version
# sy 0.1.0

Bootstrap — sy init

Before a machine can fetch secrets it must complete a one-time bootstrap using the access token generated in the web vault.

sy init --token vft_abc123def456 --server https://vault.example.com

This exchanges the one-time token for persistent key material stored in ~/.config/syvault/profile.json. The token is invalidated immediately after use.

Secrets

List secrets

sy secret list

Returns a table of every secret the current client is authorized to read, including UID, folder, title, and last-modified timestamp.

Get a full secret

sy secret get 7Kj9mNpQ2xRs

Prints every field of the secret as JSON:

{
  "uid": "7Kj9mNpQ2xRs",
  "title": "Production DB",
  "fields": {
    "host": "db.example.com",
    "port": "5432",
    "username": "app_prod",
    "password": "s3cret!"
  }
}

Get a single field

sy secret get 7Kj9mNpQ2xRs --field password
# s3cret!

When --field is provided the output is the raw value with no JSON wrapping, making it safe to use in shell substitutions:

export PGPASSWORD=$(sy secret get 7Kj9mNpQ2xRs --field password)
psql -h db.example.com -U app_prod mydb

Notation

Notation is a URI-style reference that resolves a secret field by its human-readable path instead of its UID.

sy secret notation "sy://Production/Database/field/password"
# s3cret!

The format is:

sy://<Folder>/<Title>/field/<fieldname>

Rotate a secret

Roadmap feature

sy secret rotate is not yet implemented in the CLI. Per-secret rotation is currently available only via the bulk endpoint (POST /api/vault/bulk-rotate) from the web vault admin UI. A CLI subcommand and individual HTTP endpoint are planned.

Exec — Inject Secrets into Commands

sy exec launches a subprocess with secrets injected as environment variables. Secrets are resolved at launch time and never written to disk.

sy exec \
  --env DB_HOST=sy://Production/Database/field/host \
  --env DB_PASS=sy://Production/Database/field/password \
  -- node server.js

Multiple --env flags are supported. The notation is resolved, decrypted, and set in the child process environment before the command starts.

Profiles

Profiles let you manage multiple server/client identities on the same machine.

# List configured profiles
sy profile list

# Switch to a different profile
sy profile use staging

# Remove a profile
sy profile remove old-dev

The active profile determines which server and client credentials are used for all other commands.

SSH Agent — sy agent

The built-in SSH agent serves private keys stored in Secrets Manager, so you never need to keep SSH keys on disk.

# Start the agent (listens on a Unix socket)
sy agent start

# Check agent status
sy agent status

# Configure Git to use the SyVault SSH agent
sy agent setup-git

# Stop the agent
sy agent stop

After running sy agent setup-git, Git operations that require SSH (clone, fetch, push) will automatically request the key from SyVault.

Environment Variables

Variable	Description
SY_SERVER	Server URL (overrides profile)
SY_CLIENT_ID	Client ID (overrides profile)
SY_CLIENT_SECRET	Client secret (overrides profile)
SY_PROFILE	Active profile name
SY_CONFIG_DIR	Config directory (default ~/.config/syvault)

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication failure
3	Secret not found
4	Permission denied (folder not granted)