Skip to content

Quickstart ​

Requires a Geslar account on a Premium, Family, Business or Enterprise plan, and Node.js 22 or later. See Install.

1. Sign in ​

sh
geslar login            # opens your browser (alias: geslar signin)
geslar login --device   # device code, for machines without a browser
geslar status           # current sign-in
geslar logout

login --device prints a code and a link: open the link on another device and enter the code yourself. Device-code sign-in can be turned off in your Geslar settings; the CLI then says so.

geslar whoami shows your email, plan, how you signed in and your working organization. whoami and status accept --json.

2. Unlock the Vault ​

Reading secrets needs your master password, asked for in the terminal only.

sh
geslar unlock                      # stay unlocked for 30 minutes (--ttl 1h; at most 8h)
geslar lock

The Vault stays unlocked for the time you give (30m, 1h, 8h; default 30 minutes, at most 8 hours) and locks itself after 15 minutes without use. To unlock for one command only, add --unlock: the CLI asks for the password, keeps the key in the memory of that command, and stores nothing.

Without an unlock and without --unlock, read, run, inject and item list exit with code 6.

3. Read a value ​

sh
geslar read geslar://personal/GitHub/password
geslar read --unlock geslar://personal/GitHub/password   # ask for the password for this command only
geslar item list

A reference is geslar://<vault>/<item>[/<field>]; the field defaults to password. See geslar:// references. item list shows names, types and Vaults, never values.

4. Run a command with secrets ​

sh
geslar run -e DB_PASSWORD=geslar://personal/Database/password -- ./deploy.sh
geslar run -f secrets.env -- node app.js

Every reference is resolved before the command starts; if one fails, the command is not started. Values reach the command only through its environment. The command's output is masked by default (--no-masking turns this off); masking covers the literal value only, not encoded forms such as base64. See run.

geslar inject -f secrets.env prints KEY=value lines for source or a dotenv loader. A value that contains characters outside A-Za-z0-9_@%+=:,./- is written in POSIX single quotes, and a ' inside it becomes '\''. Lines that are not references pass through unchanged. The output is not masked.

PowerShell ​

-- is required: everything after it is the command, and without it geslar would read your command's own options as its own (geslar run -e KEY=geslar://… node --version prints the version of geslar, not of node). PowerShell swallows a bare -- before it reaches geslar; put it in quotes ('--'):

powershell
geslar run -e DB_PASSWORD=geslar://personal/Database/password '--' node app.js

What the server sees ​

The server never sees secret values. Each item you read is recorded in your account's audit log.

What's next ​