keypin 0.4.0 → 0.6.0

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
@@ -36,6 +36,16 @@ bun add -g keypin
36
36
  In 1Password, open **Settings → Developer**. Under **Integrate with the 1Password SDKs**, select **Integrate with
37
37
  other apps**. 1Password then asks you to approve each keypin command.
38
38
 
39
+ ## Use with an agent
40
+
41
+ The keypin skill tells a coding agent how to use keypin: keep values out of chat and files, and hand each approval
42
+ back to you. It works with Claude Code, Codex, Cursor and other agents that read skills.
43
+
44
+ ```sh
45
+ npx skills add caiopizzol/keypin # this project
46
+ npx skills add caiopizzol/keypin -g # all your projects
47
+ ```
48
+
39
49
  ## Quick start
40
50
 
41
51
  Register a project. `keypin init` writes a commented `keypin.toml` for you to fill in:
@@ -48,37 +58,43 @@ keypin init
48
58
  A key looks like this:
49
59
 
50
60
  ```toml
51
- [vaults.personal]
52
- kind = "1password"
61
+ [1password]
53
62
  account = "my.1password.com"
54
- vault = "Private"
55
-
56
- [keys.api-token]
57
- env = "API_TOKEN"
58
- owner = "my-project"
59
63
 
60
- [keys.api-token.dev] # read by keypin run
61
- vault = "personal"
62
- item = "my-project dev api token"
64
+ [keys.API_TOKEN] # the variable your program reads
65
+ rotate_every = "90d"
66
+ dev = "op://Private/my-project dev api token/credential" # read by keypin run
63
67
 
64
- [keys.api-token.prod] # read by keypin publish
65
- vault = "personal"
66
- item = "my-project prod api token"
68
+ [keys.API_TOKEN.prod] # read by keypin publish
69
+ from = "op://Private/my-project prod api token/credential"
67
70
 
68
- [[keys.api-token.prod.publish]] # where publish writes it
71
+ [[keys.API_TOKEN.prod.publish]] # where publish writes it
69
72
  to = "github-actions"
70
73
  repo = "me/my-project"
71
74
  ```
72
75
 
73
- In 1Password, each item holds the value in its `password` field, plus a `rotated` date and a `rotate_every` period
74
- such as `90d`. Now use it:
76
+ Each `op://` reference is a 1Password secret reference: in the item, open the field's menu and select **Copy Secret
77
+ Reference**. Add a `rotated` date to the item. Now use it:
75
78
 
76
79
  ```sh
77
80
  keypin status # every key, when it's due, and any problem
78
81
  keypin run -- npm run dev # run a command with the dev keys
79
- keypin publish api-token # write the prod value to the GitHub secret
82
+ keypin publish API_TOKEN # write the prod value to the GitHub secret
80
83
  ```
81
84
 
85
+ ### Coming from a .env
86
+
87
+ `keypin import` moves a `.env` file's values into new 1Password items and maps them:
88
+
89
+ ```sh
90
+ keypin import .env --vault Private --account my.1password.com
91
+ ```
92
+
93
+ It shows each item it will create and waits for you to type `yes`. It never overwrites an item, and it never changes
94
+ the `.env` file. It names any variable it left only in the file; move those, then delete the file yourself, and
95
+ `keypin run -- <command>` provides the values.
96
+ See [Import](https://github.com/caiopizzol/keypin/blob/main/docs/import.md).
97
+
82
98
  ## Commands
83
99
 
84
100
  ```sh
@@ -86,13 +102,18 @@ keypin init [folder] # register a project and write a keypin.toml
86
102
  keypin unregister [folder] # stop listing a project (its keypin.toml stays)
87
103
  keypin status [--json] # every key, when it's due, and any problem
88
104
  keypin discover [folder] # every key name a project uses, where it's set, and a draft map
89
- keypin run -- <command> # run a command with the project's dev keys
90
- keypin publish <key-id> # check each destination's account, then write the key
91
- keypin rotate <key-id> # replace a Cloudflare API token, then revoke the old one
105
+ # (--write saves the draft as keypin.toml and registers the project)
106
+ keypin import <env-file> --vault <vault>
107
+ # move an env file's values into 1Password and map them
108
+ keypin run -- <command> # run a command with the project's dev keys (--env for another)
109
+ keypin publish <VARIABLE> # check each destination's account, then write the key
110
+ keypin publish --all # publish every key, with one plan and one approval
111
+ keypin rotate <VARIABLE> # replace a Cloudflare API token, then revoke the old one
92
112
  ```
93
113
 
94
- `publish` and `rotate` show a plan and wait for you to type `yes`. `--yes` skips that only for routine updates. It
95
- never approves a first write, a changed account or vault item, or a revoke. `keypin --help` lists the exit codes.
114
+ `import`, `publish` and `rotate` show a plan and wait for you to type `yes`. `--yes` approves `import`, which only
115
+ creates new items. For `publish` and `rotate`, it skips that only for routine updates: it never approves a first
116
+ write, a changed account or vault item, or a revoke. `keypin --help` lists the exit codes.
96
117
 
97
118
  ## Docs
98
119
 
@@ -100,6 +121,8 @@ never approves a first write, a changed account or vault item, or a revoke. `key
100
121
  `keypin.toml` and in the vault items.
101
122
  - [Discover](https://github.com/caiopizzol/keypin/blob/main/docs/discover.md): what `discover` reads, the problems
102
123
  it reports, and its draft map.
124
+ - [Import](https://github.com/caiopizzol/keypin/blob/main/docs/import.md): moving a `.env` file's values into
125
+ 1Password.
103
126
  - [Publishing](https://github.com/caiopizzol/keypin/blob/main/docs/publishing.md): destinations, account checks and
104
127
  approvals.
105
128
  - [Rotation](https://github.com/caiopizzol/keypin/blob/main/docs/rotation.md): how `rotate` works, and the admin