Appearance
Reference
Commands
| Command | Options | What it does |
|---|---|---|
geslar login (alias signin) | --device | Signs in: in the browser (default) or with a device code (RFC 8628, for machines without a browser). |
geslar logout | Revokes the sign-in on the server when possible and always clears local state. | |
geslar whoami | --json | Shows the current identity: email, plan, how you signed in, working organization. |
geslar status | --json | Shows the sign-in status and whether the Vault is unlocked. |
geslar unlock | --ttl <duration> | Unlocks the Vault (asks for the master password in the terminal). Default 30 minutes, at most 8 hours. |
geslar lock | Locks the Vault. | |
geslar read <ref> | --unlock | Prints the value of one field to stdout. |
geslar item list [vault] | --json, --unlock | Lists items (name, type, Vault), never any secret fields. |
geslar run <command…> | -e, --env <KEY=ref> (repeatable), -f, --secrets-file <path>, --no-masking, --unlock, --reason <text> | Runs a command with secrets in its environment. The command goes after --. |
geslar inject | -f, --secrets-file <path> (required), --unlock | Prints KEY=value lines for source or a dotenv loader. The output is not masked. |
geslar agent add <name> | --stdin | Saves an agent profile: takes a gsm_… token once (a person only, in a terminal). |
geslar agent list | --json | Lists the local profiles and their state on the server. |
geslar agent remove <name> | --revoke | Deletes a local profile; with --revoke also the identity on the server. |
geslar approval request <vault> | --reason <text> (required), --item <name> (repeatable), --ttl <duration>, --uses <n> | Asks a person to approve access to a Vault; prints the link and exits with code 8 (does not wait). |
geslar approval status <requestId> | --json | The state of one approval request. |
geslar approval list | --json | This profile's active approvals and requests. |
geslar mcp serve | --agent <name>, --root <dir>, --pass-env <names>, --return-stdout-tail | Runs the stdio MCP server over an agent profile (OS keychain only). |
geslar mcp init <profile> | --client <client>, --scope <scope> | Writes the MCP server of an agent profile into a client's configuration, or prints it. Clients: claude-code (default), claude-desktop, cursor, json (print only). --scope (user, the default, or local) is for Claude Code only. |
geslar mcp allow-cmd <pattern> | --ttl <duration>, --max-uses <n> | Lets the MCP server start commands that match a pattern. A person only, in a terminal. Default 1 hour, at most 8 hours. |
geslar mcp grants | --json | Lists the active command patterns. |
geslar mcp revoke [selector] | --all | Revokes a command pattern (by id or pattern), or all of them with --all. |
Global options, before or after the command:
| Option | Meaning |
|---|---|
--api-url <url> | API base URL (default https://api.geslar.app). |
--web-url <url> | Web base URL for the browser login-approval step (default https://my.geslar.app). |
--lang <hr|en> | Output language: hr or en. |
--key-storage <auto|keychain|file> | Where the local key is kept; see Install. |
--agent <name> | The agent profile the command runs as. |
-V, --version | Prints the version. |
-h, --help | Shows help for a command. |
--api-url and --web-url accept https URLs, or http only for localhost, 127.0.0.1 and [::1].
Environment variables
| Variable | Meaning |
|---|---|
GESLAR_API_URL | Same as --api-url. |
GESLAR_WEB_URL | Same as --web-url. |
GESLAR_LANG | Same as --lang; exactly hr or en. |
GESLAR_KEY_STORAGE | Same as --key-storage. |
GESLAR_AGENT | Same as --agent. |
GESLAR_SERVICE_TOKEN | The token of a service account, for CI. Never a command-line argument. |
Sign-in and unlock
Signing in proves who you are; unlocking decrypts your Vault. They are separate steps.
geslar unlock asks for the master password in the terminal only, never from an environment variable, an argument or a file. The Vault stays unlocked for the --ttl you give (30m, 1h, 8h; default 30 minutes, at most 8 hours) and locks itself after 15 minutes without use.
--unlock on read, run, inject and item list asks for the password for that one command, keeps the key in the memory of that process only, and stores nothing.
Without an unlock and without --unlock, these commands exit with 6.
geslar:// references
geslar://<vault>/<item>[/<field>]References are resolved inside the CLI process, after decryption on your machine.
<vault>
Matched case-insensitively against these, together:
| To address… | Use |
|---|---|
| your personal Vault | personal (the older osobno still works) |
| the Vault of your family organization | family |
| the Vault of your business or enterprise organization | company or work |
| a Vault of a named organization | the organization's name |
| a Vault | the Vault's own name |
family, company and work are keywords. company and work are synonyms and mean your business or enterprise organization. If a name matches more than one Vault, the error lists every candidate; the CLI never picks one. The org: prefix is not supported. Under an agent profile and with a service account, a Vault is given by its name only.
<item>
The item's name, case-insensitive. If two items in the Vault share a name, the error lists their ids and an example; use id:<item id> instead of the name:
geslar://personal/id:0192f3ab-cdef-4444-8888-000000000001/password<field>
If omitted, password. Otherwise, by item type:
- login:
username,password,url,notes, andtotp(the current code, not the stored secret) - note:
notes - card:
cardNumber,cardholderName,expiry,cvv,notes - other item types: their fields by name, and
notes - any item: a custom field's label (case-insensitive)
An unknown field is an error that lists the available fields. An empty field is an error.
A literal / in a vault, item or field name is written %2F.
Examples
geslar://personal/GitHub/password
geslar://personal/GitHub/username
geslar://personal/AWS%20Prod/totp
geslar://personal/id:0192f3ab-cdef-4444-8888-000000000001/passwordAgent profiles
Profiles for AI tools are created and approved as described in Agents and approvals; the MCP server over a profile is described in MCP. In short: geslar agent add|list|remove, selected with --agent <name> or GESLAR_AGENT; an agent cannot print a value (read and inject are refused), and a person approves access to a Vault with 2FA (exit code 8 until then).
run
geslar run [-e KEY=geslar://…]… [-f secrets-file] [--no-masking] [--unlock] [--reason text] -- <command> [args…]- Everything is parsed first (no network). Malformed references fail here.
- Every reference is resolved. The first failure stops everything: the command is not started.
- The command starts with the values in its environment, on top of your own environment. Nothing is written to disk.
Masking. By default the command's stdout and stderr go through a filter that replaces the literal secret value with ***, including a value split across output chunks. It does not recognize encoded forms (base64, URL-encoded, hex). A value of any length is masked here; the filtered tail of geslar mcp serve --return-stdout-tail is different and never masks a value shorter than 6 characters. With masking on, the command's stdout and stderr are pipes, not a terminal, so tools that check for a terminal may switch off colors or progress bars. --no-masking gives the command the terminal directly.
--reason is for agent profiles: why the run is needed, 1 to 200 characters, shown to the person who approves.
Exit code. run exits with the command's own exit code, or 128+N if it was killed by signal N. If the command cannot be found: 127; if it cannot be executed: 126. On Windows .cmd and .bat files must be started through cmd /c.
Signals. SIGTERM is forwarded to the command. On Windows, Ctrl+C reaches the command through the shared console, and SIGBREAK ends it.
PowerShell. PowerShell swallows a bare -- before it reaches geslar. If the command has options of its own, write the separator in quotes: geslar run -e KEY=geslar://… '--' node -p "1".
Secrets files (-f)
- One
KEY=VALUEper line, optionally prefixed withexport. - Blank lines and lines starting with
#are skipped. KEYis letters, digits and_, not starting with a digit.VALUEis everything after the first=, trimmed; one pair of matching quotes is removed. There is no escape processing, no${VAR}expansion and no inline comments.- A value starting with
geslar://is a reference and is resolved. Any other line passes through unchanged. - A line without
=or with an invalid key is an error naming the line number only. - If a key appears again later in the file, or in a later
-e, the later one wins. - Size limit 1 MiB; the path must be a regular file.
-e accepts references only (KEY=geslar://…), so plain values never land in your shell history.
inject
geslar inject -f secrets-file [--unlock]Prints each line as KEY=value, shell-quoted when needed: a value with any character outside A-Za-z0-9_@%+=:,./- is wrapped in POSIX single quotes (a ' becomes '\''), so this works exactly:
sh
eval "$(geslar inject -f .env.geslar)"Lines that are not references are printed as they are. Nothing is printed unless every reference resolved. The output is not masked. A dotenv parser that does not understand '\'' will misread a value that contains a single quote.
Output language
Messages are Croatian or English. The first of these that is set decides: --lang hr|en, GESLAR_LANG, LC_ALL, LC_MESSAGES, LANG, the system locale. --lang and GESLAR_LANG must be exactly hr or en.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | Usage or other error |
2 | Not signed in, or the identity is invalid, revoked or expired |
3 | The plan does not include this |
4 | A geslar:// reference cannot be resolved |
5 | Access denied or outside the scope (indistinguishable from "does not exist"), or refused for an agent (read, inject, a command that is not allowed) |
6 | The Vault is locked |
7 | The local key store or key-file password is unusable |
8 | A person must approve first: wait, do not retry blindly |
126 / 127 | run: the command cannot be executed / was not found |
128+N | run: the command was killed by signal N |
Error messages state the cause and never contain a secret value.
What the server sees
The server never sees secret values. Each item you read is recorded in your account's audit log.