Getting Started

Install

One line on Windows (PowerShell):

irm https://raw.githubusercontent.com/lacodda/sefy/main/tools/install.ps1 | iex

One line on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/lacodda/sefy/main/tools/install.sh | sh

Via npm:

npm install -g sefy-cli

Via cargo:

cargo install sefy

Or take a prebuilt archive from Releases (Windows x86_64, Linux x86_64, macOS arm64), unpack it and put sefy on your PATH.

Both one-line installers also place any transport the archive carries into sefy’s plugins directory, so sefy sync has something to call. Installing through cargo or npm gets the CLI alone; add the git transport with cargo install sefy-plugin-github (a git repository) or cargo install sefy-plugin-sftp (your own server), and see Syncing through a transport or Syncing to your own server.

Shell completions:

sefy completions bash > /etc/bash_completion.d/sefy
sefy completions zsh  > ~/.zfunc/_sefy

fish, powershell and elvish work the same way.

Point sefy at a file

sefy has no default vault location. A file at a predictable path would undo the point of one that looks like nothing, so you say where it lives:

export SEFY_VAULT=~/backups/notes.bak

Every command also takes --vault <FILE> if you would rather be explicit, or keep several vaults.

The name is yours. notes.bak, archive-2019.dat, anything at all — there is no extension sefy expects and none it writes.

Create the vault

$ sefy init
New master password:
Repeat it:
created /home/you/backups/notes.bak

The password is asked for twice, because a typo here would lock you out of the vault forever. It is never echoed, and it cannot be passed as an argument: that would put it in your shell history and in every process listing.

The master password is the one secret sefy cannot keep for you, and it is typed by hand. A passphrase of random words is the kind that is both strong and typeable — gen makes one, no vault needed:

$ sefy gen --words 6 --stdout
generated 6 words: 78 bits of entropy, strength 4/4
agreeably-cape-valid-unwary-widget-prozac

Put things in

$ sefy add note "bank card" --text "PIN 4815" --tag money
added "bank card" as 1

$ sefy add login mail --login someone@example.com --url https://mail.example.com --tag mail
Password for this item:
added "mail" as 2

$ sefy add file ~/.ssh/id_ed25519 --tag keys
added "id_ed25519" as 3

For a new account, let sefy make the password and keep it in one step — it is stored as a login and then copied, ready for the sign-up form:

$ sefy gen --save forum --login someone@example.com --url https://forum.example.com
added "forum" as 4
generated 20 characters: 130 bits of entropy, strength 4/4
copied it to the clipboard; clearing in 45s
clipboard cleared

A long note is easier in your editor:

sefy add note "journal" --editor

Coming from another password manager or a browser, bring everything at once: sefy import reads what KeePass, Bitwarden, Chrome, Firefox and Safari export, and Moving between password managers walks through each.

Get things out

$ sefy ls
3  id_ed25519  file        [keys]
2  mail        login       [mail]
1  bank card   note        [money]

$ sefy get mail
copied password of "mail" to the clipboard; clearing in 45s
clipboard cleared

For pipes and scripts, print it instead — knowing that the secret then lives in your terminal scrollback:

$ sefy get "bank card" --stdout
PIN 4815

Files come back exactly as they went in:

sefy extract id_ed25519 -o ~/.ssh/id_ed25519

Naming what you want

Commands take an item’s title, an id, or text to search for. An exact title always wins; when several items still match, sefy shows them rather than picking one:

$ sefy get ma
error: 2 items match "ma":
     4  mailing list                    note
     2  mail                            login
narrow the text, or use an id

In scripts

Passwords come from environment variables you name yourself:

export VAULT_PW='…'
sefy --password-env VAULT_PW ls

Without a terminal, sefy refuses to prompt rather than hanging — and sefy rm refuses to assume “yes” unless you pass --yes.

A script that needs a token does not have to fetch it and export it: sefy run puts it in the environment of one command, and nowhere else.

sefy run -e GITHUB_TOKEN=github -- ./release.sh

Where next

Moving between password managers — arriving from KeePass, Bitwarden or a browser, and leaving again.
Moving a vault between machines — copying it, syncing services, and what to do when two copies drifted apart.
Keeping ssh keys in a vault — keys and passphrases together, and putting them back on a new machine.
Commands — every command, one page each.
How the vault works — the file format and the cryptography behind it.
Threat model — what sefy protects against, and what it does not.