@geslar/cli 1.0.0-rc.1 → 1.0.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 +65 -10
- package/dist/THIRD_PARTY_LICENSES.txt +411 -638
- package/dist/geslar_crypto_wasm_bg.wasm +0 -0
- package/dist/index.cjs +32969 -18251
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
# @geslar/cli
|
|
2
2
|
|
|
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
3
|
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
4
|
|
|
7
5
|
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.
|
|
@@ -11,12 +9,10 @@ Requires a Geslar account on a Premium, Family, Business or Enterprise plan. Age
|
|
|
11
9
|
Requires Node.js 22 or newer.
|
|
12
10
|
|
|
13
11
|
```sh
|
|
14
|
-
npm install -g @geslar/cli
|
|
12
|
+
npm install -g @geslar/cli
|
|
15
13
|
geslar --version
|
|
16
14
|
```
|
|
17
15
|
|
|
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
16
|
## Sign in
|
|
21
17
|
|
|
22
18
|
```sh
|
|
@@ -53,7 +49,7 @@ Every reference is resolved before the command starts; if one fails, the command
|
|
|
53
49
|
|
|
54
50
|
## PowerShell
|
|
55
51
|
|
|
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
|
|
52
|
+
`--` 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 (`'--'`):
|
|
57
53
|
|
|
58
54
|
```powershell
|
|
59
55
|
geslar run -e DB_PASSWORD=geslar://personal/Database/password '--' node app.js
|
|
@@ -71,7 +67,7 @@ The local key that seals your session is kept in the OS keychain where there is
|
|
|
71
67
|
geslar login --key-storage file # or: GESLAR_KEY_STORAGE=file
|
|
72
68
|
```
|
|
73
69
|
|
|
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
|
|
70
|
+
**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 restart of the computer, 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
71
|
|
|
76
72
|
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
73
|
|
|
@@ -127,6 +123,7 @@ geslar --agent ci-bot approval list
|
|
|
127
123
|
| 6 | the Vault is locked |
|
|
128
124
|
| 7 | the local key store or key-file password is unusable |
|
|
129
125
|
| 8 | a person must approve first — wait, do not retry blindly |
|
|
126
|
+
| 11 | this version of the CLI is no longer supported: update it with `npm install -g @geslar/cli`, then run the command again |
|
|
130
127
|
| 126, 127 | `run`: the command cannot be executed / was not found |
|
|
131
128
|
|
|
132
129
|
## MCP (AI clients)
|
|
@@ -138,12 +135,12 @@ geslar mcp init ci-bot # Claude Code (default; --scope us
|
|
|
138
135
|
geslar mcp init ci-bot --client cursor # claude-code, claude-desktop, cursor, or json (print only)
|
|
139
136
|
```
|
|
140
137
|
|
|
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
|
|
138
|
+
- 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` (the exact installed version, never `latest`).
|
|
142
139
|
- 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
|
|
140
|
+
- 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: 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
141
|
- `mcp serve` needs the OS keychain (no key file) and refuses to start while `GESLAR_SERVICE_TOKEN` is set.
|
|
145
142
|
|
|
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.
|
|
143
|
+
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; values shorter than 6 characters are never masked in it). References are accepted in `env` and `env_file` only, never in the command, its arguments or the directory.
|
|
147
144
|
|
|
148
145
|
You decide which commands the agent may start, in a terminal, with a typed confirmation:
|
|
149
146
|
|
|
@@ -155,6 +152,42 @@ geslar mcp revoke --all # or: geslar mcp revoke <id or pattern>
|
|
|
155
152
|
|
|
156
153
|
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
154
|
|
|
155
|
+
### Other MCP clients
|
|
156
|
+
|
|
157
|
+
Any MCP client that can start a local stdio server should work: `geslar mcp serve` speaks the MCP protocol over standard input and output only (no network port) and relies on nothing that is specific to one client. The configuration of a client names a command, its arguments and an environment; for Geslar they are:
|
|
158
|
+
|
|
159
|
+
- command `geslar`, arguments `mcp serve`, environment `GESLAR_AGENT=<profile name>` (instead of the environment variable you can add `--agent <profile name>` to the arguments);
|
|
160
|
+
- when `geslar` is not on the PATH: command `npx`, arguments `-y @geslar/cli@<exact version> mcp serve`, the same environment.
|
|
161
|
+
|
|
162
|
+
The profile must exist (`geslar agent add <profile name>`) and the OS keychain must be usable: the server never asks for a password. `mcp init` can print the entry in the shape that many clients read:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
geslar mcp init ci-bot --client json
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"mcpServers": {
|
|
171
|
+
"geslar": {
|
|
172
|
+
"command": "geslar",
|
|
173
|
+
"args": [
|
|
174
|
+
"mcp",
|
|
175
|
+
"serve"
|
|
176
|
+
],
|
|
177
|
+
"env": {
|
|
178
|
+
"GESLAR_AGENT": "ci-bot"
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Where that goes and what the fields are called is in the documentation of your client; `mcp init` does not guess it. On Windows the entry that `mcp init` writes for Claude Desktop starts `npx` through `cmd` (`cmd /c npx -y …`), which is not yet verified on a real client (see above); a client that starts commands without a shell may need the same, and installing `geslar` globally avoids the question.
|
|
186
|
+
|
|
187
|
+
**Tested with:** the official MCP TypeScript SDK client (pinned in the CLI, run in its test suite against the real `mcp serve` over a stdio pipe and a fake Geslar server) and MCP Inspector 2.9.0 in CLI mode (`initialize`, `tools/list` with the five tools, and calls of `geslar_whoami` and `geslar_list_vaults`, against a fake Geslar server). Both check the protocol; neither is a client that people use. **`mcp init` configures:** Claude Code, Claude Desktop and Cursor, and prints the generic entry above for anything else. If your client works, or does not, tell us which one and which version in an [issue](https://github.com/geslar-eu/geslar-cli/issues).
|
|
188
|
+
|
|
189
|
+
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.
|
|
190
|
+
|
|
158
191
|
## CI mode
|
|
159
192
|
|
|
160
193
|
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`:
|
|
@@ -175,13 +208,35 @@ What happens:
|
|
|
175
208
|
- **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
209
|
- 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
210
|
- The scope and the expiry of the account are the approval: there is no per-read approval for a service account.
|
|
211
|
+
- If the server refuses the token — it is unknown, revoked or expired; the server does not say which — `geslar` exits with code 2 and says exactly that: create a new service account in the browser and update the secret. (An agent profile gets a different message, because it is fixed differently: `geslar agent add` again.)
|
|
178
212
|
|
|
179
213
|
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
214
|
|
|
215
|
+
## Plans and limits
|
|
216
|
+
|
|
217
|
+
- **Signing in as a person** (`geslar login`, then `read`, `run`, `inject`) needs a Premium, Family, Business or Enterprise plan; the Free plan does not include it.
|
|
218
|
+
- **Agent profiles and CI service accounts** (machine identities) need the same plans, and their number is limited. Agents and service accounts count together; only an identity that is neither revoked nor expired counts.
|
|
219
|
+
|
|
220
|
+
| Plan | Machine identities |
|
|
221
|
+
|---|---|
|
|
222
|
+
| Free | 0 |
|
|
223
|
+
| Premium | 5 |
|
|
224
|
+
| Family | 5 |
|
|
225
|
+
| Business | 20 |
|
|
226
|
+
| Enterprise | 50 |
|
|
227
|
+
|
|
228
|
+
- On Premium and Family the limit is per person, across their personal and family organizations; on Business and Enterprise it is per organization.
|
|
229
|
+
- **Family: only the payer.** For a personal or family organization, the plan that counts is the plan of the issuing person's own personal organization. On a Family plan, that is the person who pays and holds it, so the Family plan gives agents and service accounts to the payer only. A member of the family counts only with a paid plan of their own.
|
|
230
|
+
- The plan is checked every time an identity is used, not only when it is created: when it lapses, the identity stops working.
|
|
231
|
+
|
|
181
232
|
## What this does not protect against
|
|
182
233
|
|
|
183
234
|
- A person at a terminal can print any value they may read; masking covers the literal value only.
|
|
235
|
+
- In the output tail that `--return-stdout-tail` gives the model, values shorter than 6 characters are never masked (a 3-character value would wreck any output). `geslar run` itself masks a value of any length.
|
|
184
236
|
- 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.
|
|
237
|
+
- **While your Vault is unlocked, anything that runs as you can use it, an AI agent with access to your terminal included.** `geslar unlock` leaves an unlock record on this computer, sealed with the local key. Until it ends, 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. The unlock also ends by itself: 15 minutes after the last use (every use moves that deadline), and in any case after the time you gave to `geslar unlock` (30 minutes by default, at most 8 hours). `geslar lock` removes the record on this computer, does not call the server, and succeeds when nothing is unlocked. With `--key-storage file` the key that seals the record needs the local password, which is asked for in the terminal.
|
|
238
|
+
- **The environment of a command started by `geslar run` can be read by other processes of the same OS user.** `geslar run` puts the secrets in the command's environment, and the CLI does nothing to hide it from them. On Linux the same user (and root) can read `/proc/<pid>/environ`; other systems have their own ways for a process of the same user to inspect it. On a shared machine, run the command in a container or under a dedicated user.
|
|
239
|
+
- **There is no offline mode.** The CLI keeps no copy of your Vault: its local state is the sealed sign-in, the unlock record (the key and its deadlines), the agent profiles and the MCP command patterns. Without a connection to Geslar, `login`, `unlock`, `whoami`, `read`, `run`, `inject` and `item list` fail with exit code 1 and "Can't connect to Geslar (network error)."; `run` starts nothing. `status` reports your sign-in from local state but cannot check the unlock, so it shows the Vault as locked. `lock`, `mcp allow-cmd`, `mcp grants`, `mcp revoke` and `agent remove` (without `--revoke`) work without a connection; `agent remove --revoke` asks the server first and deletes nothing if that fails. `agent list` shows each profile as unreachable. `logout` signs out on this computer and says that the server could not be told, so the sign-in may stay valid until it expires.
|
|
185
240
|
- 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.
|
|
186
241
|
|
|
187
242
|
## License
|