@geslar/cli 0.3.1 → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,29 +1,195 @@
1
1
  # @geslar/cli
2
2
 
3
- Command-line access to your [Geslar](https://geslar.app) vault via `geslar://` references — for scripts, agents, and DevOps. Requires a Premium, Family, Business, or Enterprise plan.
3
+ > **Trial release.** This is a pre-release of 1.0 for testing. It is published under the npm tag `next`, so a plain `npm install -g @geslar/cli` does **not** install it; install it by its exact version (see [Install](#install)). Behaviour and options may still change before 1.0, and some things are not yet verified on every system (they are named below). Do not rely on it for production secrets yet.
4
+
5
+ Command-line client for [Geslar](https://geslar.app): sign in, read a secret, run a command with secrets in its environment, and give AI tools and CI jobs narrowly scoped access to a Vault.
6
+
7
+ Requires a Geslar account on a Premium, Family, Business or Enterprise plan. Agents and CI service accounts (machine identities) need a plan that includes them; on a Family plan they belong to the plan's owner. The server never sees secret values. Each item you read is recorded in your account's audit log.
8
+
9
+ ## Install
10
+
11
+ Requires Node.js 22 or newer.
12
+
13
+ ```sh
14
+ npm install -g @geslar/cli@1.0.0-rc.1
15
+ geslar --version
16
+ ```
17
+
18
+ `npm install -g @geslar/cli@next` installs the newest trial release. A plain `npm install -g @geslar/cli` never installs a trial release.
19
+
20
+ ## Sign in
21
+
22
+ ```sh
23
+ geslar login # opens your browser (alias: geslar signin)
24
+ geslar login --device # device code, for machines without a browser
25
+ geslar status # current sign-in
26
+ geslar logout
27
+ ```
28
+
29
+ ## Unlock and read
30
+
31
+ Reading secrets needs your master password, asked for in the terminal only.
32
+
33
+ ```sh
34
+ geslar unlock # stay unlocked for 30 minutes (--ttl 1h; at most 8h)
35
+ geslar read geslar://personal/GitHub/password
36
+ geslar read --unlock geslar://personal/GitHub/password # ask for the password for this command only
37
+ geslar item list
38
+ geslar lock
39
+ ```
40
+
41
+ A reference is `geslar://<vault>/<item>[/<field>]`; the field defaults to `password`. `personal` is your personal organization; `family`, `company` and `work` are keywords for organizations of that kind (`company` and `work` mean a Business or Enterprise organization), so a Vault can also be named directly. Use `%2F` for a literal `/` in a name. An ambiguous name is an error that lists the candidates.
42
+
43
+ ## Run a command with secrets
44
+
45
+ ```sh
46
+ geslar run -e DB_PASSWORD=geslar://personal/Database/password -- ./deploy.sh
47
+ geslar run -f secrets.env -- node app.js
48
+ ```
49
+
50
+ 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.
51
+
52
+ `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 (`KEY='va lue'`, a `'` becomes `'\''`). Lines that are not references pass through unchanged. The output is **not** masked.
53
+
54
+ ## PowerShell
55
+
56
+ `--` 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 may swallow a bare `--` before it reaches `geslar`; put it in quotes (`'--'`):
57
+
58
+ ```powershell
59
+ geslar run -e DB_PASSWORD=geslar://personal/Database/password '--' node app.js
60
+ ```
61
+
62
+ ## Where the local key lives
63
+
64
+ The local key that seals your session is kept in the OS keychain where there is one: Windows Credential Manager, the macOS Keychain, or on Linux a Secret Service (GNOME Keyring, KWallet, KeePassXC). `--key-storage` (or `GESLAR_KEY_STORAGE`) chooses:
65
+
66
+ - `auto` (the default): the keychain when it works. If the keychain cannot be used at all, the CLI says so and keeps the key in a file protected by a local password instead. Once a key file exists, the file keeps being used.
67
+ - `keychain`: only the OS keychain; an error if it does not work.
68
+ - `file`: the key file, even where a keychain works.
69
+
70
+ ```sh
71
+ geslar login --key-storage file # or: GESLAR_KEY_STORAGE=file
72
+ ```
73
+
74
+ **Linux without a Secret Service:** the keychain library does not fail there; it falls back to the kernel keyring (keyutils). The CLI notices this the first time it stores the key and warns you: the key lives in the kernel keyring of this login session and does **not** survive a logout or a restart, so you would sign in again; use `--key-storage file` to keep it. An agent profile cannot be created in that situation at all (see [Agents](#agents-ai-tools)).
75
+
76
+ The local password (file mode) is separate from your master password and is asked for in the terminal. Switching between keychain and file requires `geslar logout` first.
77
+
78
+ ## Agents (AI tools)
79
+
80
+ An agent is a machine identity of kind "Agent (AI tool)" that you create in the web app under *Settings → Agents & automation → Agents & CI*: you choose the Vaults it may reach and a lifetime, and the web 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.
81
+
82
+ ```sh
83
+ geslar agent add ci-bot # a person only, in a terminal: paste the token at the hidden prompt
84
+ geslar agent list # profiles on this machine and their state on the server
85
+ geslar agent remove ci-bot # delete the local profile
86
+ geslar agent remove ci-bot --revoke # also revoke the identity on the server (from your signed-in session)
87
+ ```
88
+
89
+ - Enrol within **15 minutes** of creating the token; an agent that is not enrolled in time is revoked.
90
+ - The token is read only from the hidden prompt (or `--stdin` from a pipe), never from an argument or the environment. The profile is stored sealed on this machine; the token cannot be shown again. If the local key is lost (for example after a restart on a system without a persistent key store), `agent list` says so and you create a new agent.
91
+ - On Linux an agent profile needs a **persistent** key store — a Secret Service such as GNOME Keyring, KWallet or KeePassXC. Without one, `agent add` stops before the token is used (exit code 7). On Windows and macOS the OS keychain is used.
92
+ - Create a **separate Vault** for the agent and give the identity access to that Vault only.
93
+
94
+ An agent profile is selected with `--agent <name>` or `GESLAR_AGENT`:
95
+
96
+ ```sh
97
+ geslar --agent ci-bot item list # names and types only, never a secret field
98
+ geslar --agent ci-bot run --reason "run the test suite" -e DB_PASSWORD=geslar://Test-agent/Database/password -- npm test
99
+ ```
100
+
101
+ Under an agent profile, and with a service account, a Vault is given by its **name**: the keywords `personal`, `osobno`, `family`, `company` and `work` are not resolved (a Vault that is itself named like that is found by its name; otherwise it is an error).
102
+
103
+ An agent profile deliberately **cannot print a value**: `read` and `inject` are refused. `run` works only for a command that you have allowed (see [MCP](#mcp-ai-clients)), always with masking, and with a reason of 1–200 characters that the person who approves can see.
104
+
105
+ ### Approvals
106
+
107
+ The first time an agent needs to read items of a Vault, a person has to approve it. `run` stops with exit code **8**, prints a link and a short code, and starts nothing:
108
+
109
+ ```sh
110
+ geslar --agent ci-bot approval request Test-agent --reason "run the test suite" --ttl 1h --uses 5
111
+ geslar --agent ci-bot approval status <requestId>
112
+ geslar --agent ci-bot approval list
113
+ ```
114
+
115
+ - Open the link (or *Settings → Agents & automation → Approvals*), check that the short code is the same as in the terminal, read the reason, and approve with your password and a fresh 2FA code — every time. You can approve **less** than was asked (shorter time, fewer reads), never more.
116
+ - A request is valid for 10 minutes. The CLI does not wait for the decision and has no way to approve or deny anything; it never opens the browser by itself.
117
+ - A service account (see [CI mode](#ci-mode)) is not asked per read: its scope and expiry are the approval.
118
+
119
+ | Exit code | Meaning |
120
+ |---|---|
121
+ | 0 | success |
122
+ | 1 | usage or other error |
123
+ | 2 | not signed in, or the identity is invalid, revoked or expired |
124
+ | 3 | the plan does not include this |
125
+ | 4 | a `geslar://` reference cannot be resolved |
126
+ | 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) |
127
+ | 6 | the Vault is locked |
128
+ | 7 | the local key store or key-file password is unusable |
129
+ | 8 | a person must approve first — wait, do not retry blindly |
130
+ | 126, 127 | `run`: the command cannot be executed / was not found |
131
+
132
+ ## MCP (AI clients)
133
+
134
+ `geslar mcp serve` is a stdio [MCP](https://modelcontextprotocol.io) server over an agent profile, for clients such as Claude Code, Claude Desktop and Cursor. `geslar mcp init` writes the entry into the client's configuration for you:
4
135
 
5
136
  ```sh
6
- npm install -g @geslar/cli
7
- geslar signin
8
- geslar run -e DB_PASSWORD=geslar://Work/Database/password -- ./start-server.sh
137
+ geslar mcp init ci-bot # Claude Code (default; --scope user or local)
138
+ geslar mcp init ci-bot --client cursor # claude-code, claude-desktop, cursor, or json (print only)
9
139
  ```
10
140
 
11
- The server never sees which vault, item, or field a reference asks for — resolution happens locally, after decrypting on your machine.
141
+ - The entry is only `{ command, args, env: { GESLAR_AGENT: "ci-bot" } }` — never the token. It starts `geslar mcp serve` if `geslar` is on your PATH, otherwise `npx -y @geslar/cli@<exact version> mcp serve`. For a trial release that is the exact trial version, never `latest`.
142
+ - A configuration file that cannot be parsed (for example one with comments), or is a symbolic link, is **not touched**: the entry is printed for you to paste. Otherwise a backup is written first, other servers are kept, and running it again changes nothing.
143
+ - For Claude Code, `mcp init` runs `claude mcp add-json` where it can and otherwise prints the exact command. **Claude Desktop on Windows** is not yet verified on a real client in this trial release: the entry for it uses `cmd /c npx …` when `geslar` is not on the PATH — check that the server shows as running and report problems.
144
+ - `mcp serve` needs the OS keychain (no key file) and refuses to start while `GESLAR_SERVICE_TOKEN` is set.
12
145
 
13
- ## MCP server
146
+ The server offers five tools: `geslar_list_vaults`, `geslar_list_items` (names and types only), `geslar_whoami`, `geslar_provision_env` (writes `KEY=geslar://…` **reference** lines into an env file under the server's root, never values) and `geslar_run`. `geslar_run` starts a program with secrets in **its** environment and answers only with the exit code, how it ended, the duration and the number of output lines; the model gets no output unless you start the server with `--return-stdout-tail` (a filtered tail, best effort, **not** a security boundary). References are accepted in `env` and `env_file` only, never in the command, its arguments or the directory.
14
147
 
15
- `geslar mcp serve` runs a stdio [MCP](https://modelcontextprotocol.io) server for Claude Code, Claude Desktop, Cursor, and other MCP clients — 6 tools (list vaults/items, whoami, provision-env, run, recent audit) scoped to an [agent profile](https://docs.geslar.app/cli/reference#agent-profiles), gated behind an out-of-band pre-grant (`geslar mcp allow`/`allow-cmd`) for anything that writes or executes. No tool returns a secret value — `run` reports only exit status and line counts, and by default returns no process output at all.
148
+ You decide which commands the agent may start, in a terminal, with a typed confirmation:
16
149
 
17
150
  ```sh
18
- geslar unlock --ttl 30m
19
- geslar agent create my-agent --vault Work
20
- geslar mcp init my-agent --client claude-code
151
+ geslar mcp allow-cmd "npm test" # lasts 1 hour by default (--ttl up to 8h; --max-uses n)
152
+ geslar mcp grants # active patterns
153
+ geslar mcp revoke --all # or: geslar mcp revoke <id or pattern>
21
154
  ```
22
155
 
23
- `geslar mcp init` detects your MCP client and wires up the config for you (never contains a token). It points the config at your globally-installed `geslar` if one is on your PATH (tracking whatever version that is), otherwise at a version-pinned `npx -y @geslar/cli@<version>` — never an unpinned `@latest`. Full reference — all 6 tools, the pre-grant model, and known limitations — at [docs.geslar.app/cli/reference](https://docs.geslar.app/cli/reference).
156
+ A pattern lasts one hour unless you set `--ttl` (at most 8h), and `--max-uses` limits how many times it can be used. Keep patterns narrow (`npm test`, not `npm *`). **A pattern is not a security boundary:** a command that can run arbitrary code (a shell, `node`, `python`, `npx` and the like) can read the secrets in its own environment and send them anywhere. What protects your Vault is the Vault you gave the agent, its time and read limits, and the approval by a person with 2FA — not the pattern.
157
+
158
+ ## CI mode
24
159
 
25
- Full docs: install (including standalone Windows/Linux binaries), quickstart, the `geslar://` reference syntax, agent profiles, and known limitations — see [docs.geslar.app/cli/reference](https://docs.geslar.app/cli/reference) or the `docs/cli/` directory in the [geslar-suite](https://github.com/StudioIT/geslar-suite) repository.
160
+ A CI job uses a **service account** (created in the web app under *Settings → Agents & automation → Agents & CI*, kind "Service (CI)") and its token. Put the whole `gsm_…` token in the secret store of your CI and hand it to the job as the environment variable `GESLAR_SERVICE_TOKEN`:
161
+
162
+ ```yaml
163
+ # GitHub Actions: the token goes in `secrets`, never in `vars`, and never as an input of a step
164
+ - run: npm install -g @geslar/cli@<exact version> --ignore-scripts
165
+ - run: geslar run -e DB_PASSWORD=geslar://CI/Database/password -- ./deploy.sh
166
+ env:
167
+ GESLAR_SERVICE_TOKEN: ${{ secrets.GESLAR_SERVICE_TOKEN }}
168
+ ```
169
+
170
+ Under an agent profile, and with a service account, a Vault is given by its **name** (`CI` above is the name of a Vault): the keywords `personal`, `osobno`, `family`, `company` and `work` are not resolved (a Vault that is itself named like that is found by its name; otherwise it is an error).
171
+
172
+ What happens:
173
+
174
+ - `read`, `run`, `inject`, `item list` and `whoami` / `status` use the token when it is set and no `--agent` / `GESLAR_AGENT` is given. No `login`, no `unlock`, no terminal, no prompt: the session lives **in memory only**, and nothing is written to disk or to a keychain (it works in a container with neither). `--unlock` makes no sense with a token and is refused.
175
+ - **Only a service account's token works from the environment.** If the server says the token belongs to an agent, the CLI stops before it asks for any key; agents use `geslar agent add` on a machine of their own.
176
+ - The child process of `geslar run` never receives the token or any other `GESLAR_*` credential, and the token is masked in the child's output. The token is in no message or error either.
177
+ - The scope and the expiry of the account are the approval: there is no per-read approval for a service account.
178
+
179
+ Advice: one service account per repository, read-only, with the shortest expiry that suits you and a rotation date; one `geslar run` per job rather than one per step (every start exchanges the token once; the server limits exchanges per hour and per address); a CI *environment* with protection for production secrets; never run it for pull requests from forks (GitHub does not give them your secrets, and `pull_request_target` with code from the pull request must not be used). Honest limit: while `geslar` runs, the token is in its own process environment (on Linux, `/proc/<pid>/environ` is readable by the same user); it is not passed on to anything it starts.
180
+
181
+ ## What this does not protect against
182
+
183
+ - A person at a terminal can print any value they may read; masking covers the literal value only.
184
+ - Anything that runs as you can read what you can read. The CLI is not a sandbox against a malicious process on your own account.
185
+ - An agent that is allowed to run a program that can run code can send that program's secrets elsewhere (see [MCP](#mcp-ai-clients)); limit what you give it and approve with care.
26
186
 
27
187
  ## License
28
188
 
29
- Proprietary, copyright Geslar d.o.o. — see [LICENSE.md](./LICENSE.md).
189
+ Proprietary, see `LICENSE.md`.
190
+
191
+ ## Security and issues
192
+
193
+ - Security: https://github.com/geslar-eu/geslar-cli/security
194
+ - Issues: https://github.com/geslar-eu/geslar-cli/issues
195
+ - Website: https://geslar.app