Skip to content

Reference ​

Commands ​

CommandOptionsWhat it does
geslar login (alias signin)--deviceSigns in: in the browser (default) or with a device code (RFC 8628, for machines without a browser).
geslar logoutRevokes the sign-in on the server when possible and always clears local state.
geslar whoami--jsonShows the current identity: email, plan, how you signed in, working organization.
geslar status--jsonShows 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 lockLocks the Vault.
geslar read <ref>--unlockPrints the value of one field to stdout.
geslar item list [vault]--json, --unlockLists 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), --unlockPrints KEY=value lines for source or a dotenv loader. The output is not masked.
geslar agent add <name>--stdinSaves an agent profile: takes a gsm_… token once (a person only, in a terminal).
geslar agent list--jsonLists the local profiles and their state on the server.
geslar agent remove <name>--revokeDeletes 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>--jsonThe state of one approval request.
geslar approval list--jsonThis profile's active approvals and requests.
geslar mcp serve--agent <name>, --root <dir>, --pass-env <names>, --return-stdout-tailRuns 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--jsonLists the active command patterns.
geslar mcp revoke [selector]--allRevokes a command pattern (by id or pattern), or all of them with --all.

Global options, before or after the command:

OptionMeaning
--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, --versionPrints the version.
-h, --helpShows 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 ​

VariableMeaning
GESLAR_API_URLSame as --api-url.
GESLAR_WEB_URLSame as --web-url.
GESLAR_LANGSame as --lang; exactly hr or en.
GESLAR_KEY_STORAGESame as --key-storage.
GESLAR_AGENTSame as --agent.
GESLAR_SERVICE_TOKENThe 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 Vaultpersonal (the older osobno still works)
the Vault of your family organizationfamily
the Vault of your business or enterprise organizationcompany or work
a Vault of a named organizationthe organization's name
a Vaultthe 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, and totp (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/password

Agent 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…]
  1. Everything is parsed first (no network). Malformed references fail here.
  2. Every reference is resolved. The first failure stops everything: the command is not started.
  3. 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=VALUE per line, optionally prefixed with export .
  • Blank lines and lines starting with # are skipped.
  • KEY is letters, digits and _, not starting with a digit.
  • VALUE is 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 ​

CodeMeaning
0Success
1Usage or other error
2Not signed in, or the identity is invalid, revoked or expired
3The plan does not include this
4A geslar:// reference cannot be resolved
5Access denied or outside the scope (indistinguishable from "does not exist"), or refused for an agent (read, inject, a command that is not allowed)
6The Vault is locked
7The local key store or key-file password is unusable
8A person must approve first: wait, do not retry blindly
126 / 127run: the command cannot be executed / was not found
128+Nrun: 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.