All guides

Geslar CLI, agents and automation

Vault access from your terminal, for AI agents (with a person's approval) and CI jobs.

Updated

Who Geslar CLI is for

Geslar CLI (the geslar command) reads secrets from your vault, runs commands with secrets in the process environment, and gives AI tools and CI jobs narrowly scoped access to the vaults you choose. Decryption happens on your computer; the server never sees secret values. Each item read is recorded in the audit log — of your account or of the organization the vault belongs to. Available with a Premium, Family, Business, or Enterprise plan; agents and service accounts need a plan that includes them (see "Plans and limits").

Install

npm install -g @geslar/cli — needs Node.js 22 or newer. The CLI is distributed through npm only. Check with geslar --version. Details and where the local key is kept → docs.geslar.app/cli/install.

Signing in as a person

geslar login opens your browser, where you sign in as usual and approve the CLI. Without a browser (an SSH session, say) there is geslar login --device: it prints a code and a link, and you type the code on another device yourself. Device-code login can be turned off in your settings. Signing in proves who you are; it does not unlock your vault. Full walkthrough → docs.geslar.app/cli/quickstart.

Unlocking

geslar unlock asks for your master password in the terminal (never from an environment variable, argument or file) and keeps the vault unlocked for 30 minutes, at most 8 hours (--ttl 1h); it also locks after 15 minutes without use. geslar lock locks it at once. With --unlock you enter the password for one command only and nothing is stored. Without an unlock, read, run and inject fail (exit code 6). Details → docs.geslar.app/cli/quickstart.

geslar:// addresses

Vault items are addressed as geslar://<vault>/<item>/<field> — the vault selected by name or a special word like personal/family/company (under an agent profile and with a service account by name only). The field defaults to password. An ambiguous name is always an error that lists the candidates, never a silent pick. Full grammar and examples → docs.geslar.app/cli/reference.

Running commands

geslar run resolves geslar:// references and starts your command with the values in its process environment; if any reference fails, the command is not started. The command's output is masked by default, but masking hides only the literal value, not encoded forms (such as base64). geslar inject prints KEY=value lines for source or a dotenv loader, and that output is not masked. In PowerShell, put the -- in quotes ('--'). Example and rules → docs.geslar.app/cli/quickstart.

Agents and approvals

An agent is a machine identity with mode "Agent (AI tool)". You create it in Škrinjar on the web (Settings → Agents & automation → Agents & CI): you choose the vaults it may reach and a lifetime, and the app shows its token (gsm_…) once. The agent never sees your password or any other vault; it can list the names and types of items in the vaults you give it, never their values. We recommend a separate vault for the agent alone.

You save the agent's profile on your computer with geslar agent add <name> (the token goes in a hidden prompt, within 15 minutes of creating it). Under a profile the agent cannot print a value: read and inject are refused, and run works only for a command you have allowed, always with masking and with a reason that the person who approves can see.

The boundary is the server-side approval. When an agent needs to read items of a vault and has no valid approval, a person has to approve it: run stops with exit code 8, prints a link and a short code, and starts nothing. You approve with your password and a fresh 2FA code, every time, and you may approve less than was asked, never more. An approval is valid for a limited time and a limited number of reads. The CLI does not wait for the decision and cannot approve or deny anything. Details → docs.geslar.app/cli/agents.

MCP: AI clients

geslar mcp serve is a stdio MCP server over an agent profile. Any MCP client that can start a local stdio server can use it; geslar mcp init configures Claude Code, Claude Desktop and Cursor for you, and prints the entry to paste for any other client. The entry never contains the token.

The server offers five tools: geslar_list_vaults, geslar_list_items (names and types only), geslar_whoami, geslar_provision_env (writes KEY=geslar://… references, never values) and geslar_run (starts a program with secrets in its environment and answers the model only with the exit code, the duration and the number of output lines). You decide which commands the agent may start, in a terminal, with geslar mcp allow-cmd. A command pattern is not a security boundary: a command that can run arbitrary code can send the secrets in its environment elsewhere.

There is no hosted version of the Geslar MCP server, by design: your secrets are decrypted only on your own computer, so the server has to run there. Chat apps that run only in the browser or in the cloud cannot start it; use a client that runs on your computer. Claude Desktop on Windows is not yet verified on a real client. Details → docs.geslar.app/cli/mcp.

CI and GitHub Action

A CI job uses a service account (mode "Service (CI)" in the same settings) and its token, which you hand to the job as the environment variable GESLAR_SERVICE_TOKEN from your CI's secret store. The session lives in memory only, with no sign-in, no unlock and no terminal. The scope and the expiry of the account are the approval, so there is no approval per read. We advise one service account per repository, read-only, with the shortest expiry that suits you.

For GitHub there is geslar-eu/secrets-action, which loads secrets into a job, masked. Pin the action by full commit SHA, and name the CLI version exactly (1.0.0 or newer). Details → docs.geslar.app/cli/ci.

Plans and limits

Signing in as a person needs a Premium, Family, Business or Enterprise plan; the Free plan does not include it. Agents and service accounts need the same plan, and their number is limited. They count together, and only those that are neither revoked nor expired:

  • Free plan: 0
  • Premium: 5
  • Family: 5 (payer only)
  • Business: 20
  • Enterprise: 50

On Premium and Family the limit is per person; on Business and Enterprise it is per organization. On Family, only the person who pays has agents and service accounts; a family member has them only with a paid plan of their own. The plan is checked every time an identity is used: when it lapses, the identity stops working.

What the server sees

The server never sees secret values. Each item read is recorded in the audit log — of your account or of the organization the vault belongs to.

Key limitations

While your vault is unlocked, anything that runs as you can use it, an AI agent with access to your terminal included. Any process on your account can run geslar read, run or inject as you, with no approval and without an agent profile: an agent profile and its approvals protect your vault only from an agent that does not also have your unlocked session. Run geslar lock before you let an agent work in your terminal, or run the agent under a separate OS user.

Masking hides only the literal value, not encoded forms. In the output tail that --return-stdout-tail gives the model, values shorter than 6 characters are never masked; geslar run masks a value of any length. A command you start with geslar run receives the secrets in its environment, and other processes of the same OS user can read it. There is no offline mode. Full list → docs.geslar.app/cli/limitations.

Did not find an answer? Write to us