@circlesac/vlt-cli 26.6.2 → 26.6.4
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 +33 -35
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
`vlt` is the official CLI for [Circles Vault](https://github.com/circlesac/vault) — a secrets manager on Cloudflare Workers with two parallel address surfaces:
|
|
6
6
|
|
|
7
7
|
- **`op://<vault>/<item>/<field>`** — 1Password Connect-compatible. Most workflows that use `op read`, `op inject`, or `op run` work unchanged by setting `OP_CONNECT_HOST`.
|
|
8
|
-
- **`vlt://<provider>/<owner>[/<repo>]
|
|
8
|
+
- **`vlt://<provider>/<owner>[/<repo>]/<NAME>`** — flat GitHub-Secrets-style key→value secrets, addressed by GitHub coordinates. The repo segment selects the scope: present → project secret, absent → owner-global. Designed to replace GitHub Actions secrets (the coordinate is identical to the OIDC `repository` claim).
|
|
9
9
|
|
|
10
10
|
`vlt read`, `vlt inject`, and `vlt run` accept both schemes anywhere a reference appears.
|
|
11
11
|
|
|
@@ -30,7 +30,7 @@ npm install -g @circlesac/vlt-cli
|
|
|
30
30
|
2. **`OP_CONNECT_HOST` + GitHub Actions OIDC** — if `ACTIONS_ID_TOKEN_REQUEST_URL`/`_TOKEN` are present (workflow has `id-token: write`), `vlt` fetches a short-lived OIDC token automatically. No stored secrets.
|
|
31
31
|
3. **`crcl` config** (`~/.config/crcl/config`) — interactive user. Run `crcl login`, optionally `--profile dev` to target the dev environment.
|
|
32
32
|
|
|
33
|
-
`vlt whoami` shows the resolved host + org.
|
|
33
|
+
`vlt whoami` shows the resolved host + account (`personal` by default, or `org:<slug>` with `--org`/`CRCL_ORG`).
|
|
34
34
|
|
|
35
35
|
## Common commands
|
|
36
36
|
|
|
@@ -67,8 +67,8 @@ vlt run --env-file=.vlt.env -- ./deploy.sh
|
|
|
67
67
|
|
|
68
68
|
```bash
|
|
69
69
|
# .vlt.env — safe to commit; values are fetched at runtime
|
|
70
|
-
DB_PASSWORD=vlt://github.com/acme/api
|
|
71
|
-
OPENAI_KEY=vlt://github.com/acme
|
|
70
|
+
DB_PASSWORD=vlt://github.com/acme/api/DB_PASSWORD
|
|
71
|
+
OPENAI_KEY=vlt://github.com/acme/OPENAI_KEY
|
|
72
72
|
LEGACY_PASS=op://my-vault/db-credentials/password
|
|
73
73
|
```
|
|
74
74
|
|
|
@@ -102,54 +102,52 @@ vlt document list --vault prod-secrets
|
|
|
102
102
|
vlt document get "TLS Cert" --vault prod-secrets -o ./cert.pem
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
###
|
|
105
|
+
### GitHub-coordinate secrets (vlt://)
|
|
106
106
|
|
|
107
|
-
|
|
107
|
+
A secret is just an op:// **item** (there's no separate "secret" store or verb). What's special about a vault named like a GitHub coordinate — `github.com/<owner>[/<repo>]` — is that it's addressed by the **`vlt://` reference scheme**, which exists for two reasons `op://` can't cover:
|
|
108
108
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
vlt secret set "vlt://github.com/acme/api#DB_PASSWORD" "s3cret"
|
|
112
|
-
echo -n "s3cret" | vlt secret set "vlt://github.com/acme#OPENAI_KEY"
|
|
109
|
+
1. **Coordinate names contain `/`.** An `op://<vault>/<item>/<field>` reference splits on `/`, so it can't name a vault like `github.com/acme/api` (the slashes collide). `vlt://github.com/<owner>[/<repo>]/<NAME>` knows the structure — `<NAME>` is the last segment, the leading github coordinate is the vault — so it parses unambiguously, no escaping.
|
|
110
|
+
2. **Inheritance.** Reads cascade `project > global` (repo→owner), like GitHub Actions repo/org secrets.
|
|
113
111
|
|
|
114
|
-
|
|
115
|
-
|
|
112
|
+
- `vlt://github.com/<owner>/<repo>/<NAME>` — project; falls back to the owner if absent
|
|
113
|
+
- `vlt://github.com/<owner>/<NAME>` — owner-global
|
|
114
|
+
- NAME charset is GitHub-isomorphic (`[A-Z0-9_]`, no digit start, no `GITHUB_` prefix)
|
|
116
115
|
|
|
117
|
-
|
|
118
|
-
vlt secret resolve DB_PASSWORD --owner acme --repo api # humans pass the coordinate
|
|
119
|
-
vlt secret resolve DB_PASSWORD # CI: coordinate implied by OIDC identity
|
|
116
|
+
The item itself is still managed with the op `item`/`vault` verbs — those take the coordinate as a `--vault` **name** (a flag value, not an `op://` reference, so the slashes are fine).
|
|
120
117
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
vlt
|
|
124
|
-
```
|
|
118
|
+
```bash
|
|
119
|
+
# Register the coordinate vault (+ CI grant for a repo coordinate; org-scoped → --org)
|
|
120
|
+
vlt vault create github.com/acme/api --org acme
|
|
125
121
|
|
|
126
|
-
|
|
122
|
+
# Write a secret = create/edit an item in that vault (--vault takes the name)
|
|
123
|
+
vlt item create --vault github.com/acme/api --title DB_PASSWORD 'value[password]=s3cret'
|
|
124
|
+
vlt item edit DB_PASSWORD --vault github.com/acme/api 'value[password]=rotated'
|
|
127
125
|
|
|
128
|
-
|
|
129
|
-
vlt
|
|
130
|
-
|
|
126
|
+
# Read by reference — vlt:// handles the coordinate + inherits (project→owner)
|
|
127
|
+
vlt read "vlt://github.com/acme/api/DB_PASSWORD" # cascades to github.com/acme if absent
|
|
128
|
+
|
|
129
|
+
# List / delete = op item verbs (coordinate as --vault name)
|
|
130
|
+
vlt item list --vault github.com/acme/api
|
|
131
|
+
vlt item delete DB_PASSWORD --vault github.com/acme/api
|
|
131
132
|
```
|
|
132
133
|
|
|
134
|
+
**Scope: personal by default.** Commands target your personal account unless you escalate to an org with `--org <slug>` (or `CRCL_ORG`). Personal is always available, non-shared, isolated per user; an org is shared, so targeting it is explicit. CI via GitHub OIDC always resolves to the org.
|
|
135
|
+
|
|
133
136
|
### Registering repos for CI access (operator-only)
|
|
134
137
|
|
|
135
|
-
|
|
138
|
+
`vlt vault create <coordinate>` creates the op:// vault that stores the secrets; for a **repo** coordinate it also records the OIDC grant that lets that repo's CI read it (**creating it is the consent**). Grants are org-scoped, so pass `--org <owner>`. Once per repo:
|
|
136
139
|
|
|
137
140
|
```bash
|
|
138
|
-
|
|
139
|
-
vlt vault create github.com/circlesac/my-app
|
|
140
|
-
|
|
141
|
-
# Options: CI write access to its own project, env/ref narrowing
|
|
142
|
-
vlt vault create github.com/circlesac/my-app --ci-write --env production
|
|
141
|
+
vlt vault create github.com/circlesac/my-app --org circlesac
|
|
142
|
+
vlt vault create github.com/circlesac/my-app --org circlesac --ci-write --env production
|
|
143
143
|
|
|
144
|
-
|
|
145
|
-
vlt vault
|
|
146
|
-
vlt vault get github.com/circlesac/my-app
|
|
147
|
-
vlt vault delete github.com/circlesac/my-app
|
|
144
|
+
vlt vault get github.com/circlesac/my-app --org circlesac # registration + secret count
|
|
145
|
+
vlt vault delete github.com/circlesac/my-app --org circlesac # revokes CI access; items remain
|
|
148
146
|
```
|
|
149
147
|
|
|
150
|
-
Owner-global (`github.com/circlesac`) needs no
|
|
148
|
+
Owner-global (`github.com/circlesac`) needs no grant — every registered repo of that owner reads it via `project > global`, and org members write to it with `vlt item create --vault github.com/circlesac --org circlesac …`.
|
|
151
149
|
|
|
152
|
-
The legacy `vlt oidc grant create|list|get|edit|delete` commands remain for
|
|
150
|
+
The legacy `vlt oidc grant create|list|get|edit|delete` commands remain for op://-vault-scoped or org-wildcard (`owner/*`) grants.
|
|
153
151
|
|
|
154
152
|
`vault create / edit / delete`, `oidc grant *`, and `whoami` require operator (user JWT) auth. OIDC tokens from GitHub Actions are scoped to data-plane operations (read secrets/items, write if allowed) and cannot manage vaults or grants regardless of role.
|
|
155
153
|
|
package/package.json
CHANGED