From db868e174497c67d594121114747124d5a2eaec2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl-Einar=20Bergstr=C3=B8m?= Date: Thu, 15 Oct 2026 08:52:38 +0200 Subject: [PATCH] docs: fix what no longer matches lazysecrets, and say each thing once MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes: - A newer release shows in the status pane (`↑ v0.2.0`), not the footer. - The account in `lazysecrets list` is plain `Azure` with one az account; `Azure:/` only with several. - Sharing lists subscription, workspace and scope links, and opening takes Azure portal links. - `--timeout` and `--clipboard-clear` are documented, next to their config keys. - `--kind`'s description reads, and says `vault` covers scopes and repo files. - `lazysecrets -h` lists `list`'s `--stars`, `--notes`, `--recent` and `--expiry`. - README typos; "Supported platforms" is "Sources". Trimmed: - An option is documented on its topic's page; config.md's example keeps the general ones and links the rest. - The fzf picker lives in docs/integration.md; the README keeps a link and the screenshot. - The clipboard clear, reveal timeout, per-account stars, Azure's "no extra requests" and `open --action` are each said once. - The status pane's contents are a list; build sizes and PR-title spellings are gone from development.md. --- README.md | 30 +++++++-------------- cmd/lazysecrets/main.go | 1 + docs/azure.md | 7 +++-- docs/config.md | 59 +++++++++++++++-------------------------- docs/development.md | 8 +++--- docs/integration.md | 12 ++++----- docs/keys.md | 35 +++++++++++------------- docs/repos.md | 12 ++------- docs/sharing.md | 7 +++-- 9 files changed, 66 insertions(+), 105 deletions(-) diff --git a/README.md b/README.md index d2c9e2c..7e6ec8c 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,23 @@ A terminal UI for finding, reading and sharing secrets. Inspired by the fantasti ## Main features - **Read-only**: lazysecrets never creates, changes or deletes a secret. - That's by design and may stay that way. - **Zero setup**: uses the logins you already have (`az`, the Databricks CLI, `sops`, `git`). No config file needed. - **Search everything**: `ctrl+s` searches every source at once, with fzf-style matching. - **Share links**: Share `lazysecrets://` links with colleagues. -- **Neovim integration**: via [lazysecrets.nvim](https://github.com/karleinarb/lazysecrets.nvim) - **Careful with values**: values stay hidden until you reveal them, and copied values are cleared from the clipboard after 30 seconds. -- **Scriptable**: `lazysecrets get ` prints a value for scripts and - pipes. +- **Scriptable**: `get`, `list` and `open` for scripts, fzf and editor + pickers; [lazysecrets.nvim](https://github.com/karleinarb/lazysecrets.nvim) + for Neovim. - **Favourites**: star the secrets you use most for easy access. - **Expiry warnings**: secrets, keys and certificates that expire soon are marked, listed together in the status pane. - **Your way**: rebind any key, pick a theme, and add custom commands to run on a secret. - **Try it first**: `lazysecrets --demo` runs on built-in sample data. -- **Supported platforms**: Azure Key Vault, Databricks secret scopes, and SOPS and `.env` files in your git repos. +- **Sources**: Azure Key Vault, Databricks secret scopes, and SOPS and `.env` files in your git repos. > **Early development:** expect rough edges. See [CHANGELOG.md](CHANGELOG.md) for what's new. @@ -45,9 +44,8 @@ Both approaches will install the latest release from [GitHub](https://github.com `sh -s -- v0.2.0` installs a given version, `LAZYSECRETS_INSTALL_DIR` somewhere else. -lazysecrets looks for a newer release once a day: the footer then shows -`↑ v0.2.0`, and `U` shows its changelog and updates in place (or run -`lazysecrets update`). +`U` (or `lazysecrets update`) updates in place when there's a newer +release. Or build it yourself: `go install git.kebcloud.no/keb/lazysecrets/cmd/lazysecrets@latest`. @@ -70,30 +68,20 @@ use most: | `l` / `h` | the details of what's selected / back | | `/` | filter the list you're in | | `space` | reveal / hide the value | -| `y` | copy the value (cleared from the clipboard after 30s) | +| `y` | copy the value | | `ctrl+s` | Go to: search everything and jump there | | `f` / `F` | star / your favourites | | `s` | copy a link to share | | `?` | every key, searchable | | `q` | quit | - ## Integration -Lazysecret let you integrate it into your workflows by `lazysecrets` `list`/`get`/`open` -Here is an example of implementing a picker in `fzf`: -```sh -lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' --accept-nth=-1 \ - --header 'enter: link · ctrl-o: open · ctrl-y: copy value · ctrl-x: copy and close' \ - --bind 'ctrl-o:become(lazysecrets open --action go --account {-2} {-1})' \ - --bind 'ctrl-y:execute-silent(lazysecrets get --account {-2} {-1} | pbcopy)+change-header(Copied the value of {3})' \ - --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)' -``` +`lazysecrets list`, `get` and `open` plug lazysecrets into fzf, editor +pickers and scripts: see [Integration](docs/integration.md#an-fzf-picker). ![fzf-example](docs/assets/fzf-example.png) -More defails in the [Integration](docs/integration.md) docs - ## Docs - [Keys](docs/keys.md): every key, Go to, the layout, and rebinding keys diff --git a/cmd/lazysecrets/main.go b/cmd/lazysecrets/main.go index 736fb1f..8b789f9 100644 --- a/cmd/lazysecrets/main.go +++ b/cmd/lazysecrets/main.go @@ -150,6 +150,7 @@ func run() error { for scripts: VAR=$(lazysecrets get ) lazysecrets [flags] list [--kind secret,…] [--cached] [--max-age 2m] [--format text|json] [--color always|never] [--icons=false] [--errors=false] + [--stars=false] [--notes=false] [--recent] [--expiry=false] print every source, vault and secret it can find, one per line, for fzf and pickers: what's cached at once, then what loads diff --git a/docs/azure.md b/docs/azure.md index 6405b92..5c11727 100644 --- a/docs/azure.md +++ b/docs/azure.md @@ -16,7 +16,7 @@ A service principal is used instead when `AZURE_CLIENT_ID`, On an account's group row, the fourth pane shows who it signs in as: name, user, tenant, object ID, whether the session used MFA, directory roles (built-in ones by name) and its subscriptions, read from az's account list -and the token lazysecrets already has: no requests of their own. `y` on +and the token lazysecrets already has. `y` on the row copies the object ID, the one access policies and role assignments ask for; `l` goes into the pane, where `j`/`k` pick any field, `/` filters them (`/tenant`) and `y` copies the selected one. @@ -67,9 +67,8 @@ fetched. `v` lists an item's versions. Items expiring within The status pane (`0`) lists them across every vault loaded, opened or cached, soonest first, and its line counts them (`⚠ 3 expiring`); `enter` -on one goes to it. That makes no requests of its own: expiry dates come -with the lists. It says how many vaults it covers; `ctrl+a` in search -loads the rest. +on one goes to it. Expiry dates come with the lists. It says how many +vaults it covers; `ctrl+a` in search loads the rest. On a vault, the right pane shows its settings: resource group, location, SKU, whether access is by Azure roles or access policies, soft delete and diff --git a/docs/config.md b/docs/config.md index dcb47c2..0e2f3ab 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,10 +1,11 @@ # Config Optional, at `~/.config/lazysecrets/config.yaml` (or -`$XDG_CONFIG_HOME/lazysecrets/config.yaml`, or `--config`). Flags override -it. Unknown keys are an error, so typos don't go unnoticed. `e` on the -status pane (`0`) opens it in your editor, as in lazygit (making it if -it isn't there yet); changes apply when lazysecrets starts again. +`$XDG_CONFIG_HOME/lazysecrets/config.yaml`, or `--config`). Flags (noted +below) override it. Unknown keys are an error, so typos don't go +unnoticed. `e` on the status pane (`0`) opens it in your editor, as in +lazygit (making it if it isn't there yet); changes apply when lazysecrets +starts again. ```yaml ui: @@ -17,7 +18,7 @@ ui: values: revealTimeout: 60s # hide a revealed value after this long; 0s keeps it shown hideOnBlur: true # hide a revealed value when the terminal loses focus (tmux: focus-events on) - clipboardClear: 30s # clear copied values from the clipboard after this long; 0s disables + clipboardClear: 30s # clear copied values from the clipboard after this long; 0s disables; also --clipboard-clear storage: cache: true # keep what was loaded (never values) for the next start history: true # count uses of items for Recent (R) @@ -28,32 +29,15 @@ updates: - https://github.com/karleinarb/lazysecrets - https://git.kebcloud.no/keb/lazysecrets providers: - timeout: 30s # per backend request; a provider's own timeout overrides it - azure: # applies to every az account - enabled: true # default + timeout: 30s # per backend request; a provider's own timeout overrides it; also --timeout + azure: # likewise databricks and repos; azure covers every az account + enabled: true # default timeout: 30s - hideSubscriptions: [platform-mgmt] # by name or ID - vaults: # listed under "Pinned vaults", for vaults - - https://kv-foo.vault.azure.net/ # you can read but not discover - databricks: - enabled: true - timeout: 30s - hideProfiles: [test] - repos: - enabled: true - timeout: 30s - roots: [~/git] - paths: [~/work/infra] - include: ["secrets/**"] - exclude: ["**/testdata/**"] -sharing: # sharing env files as encrypted links - key: https://kv-team.vault.azure.net/secrets/env-share # or its lazysecrets:// link; for repos naming none - keyRules: # what a key's value must be - minLength: 32 # characters, 16 at least - minClasses: 2 # kinds: lowercase, uppercase, digits, symbols ``` -More, each on its own page: [repos](repos.md) (`providers.repos`), +More, each on its own page: [Azure](azure.md#vaults-you-cant-discover) +(`providers.azure`), [Databricks](databricks.md) (`providers.databricks`), +[repos](repos.md#which-files) (`providers.repos`), [sharing env files](sharing.md#sharing-env-files) (`sharing`), the [link handler](sharing.md#from-the-browser-and-chat) (`linkHandler`), [keybindings](keys.md#rebinding-keys) (`keybinding`) and @@ -102,9 +86,8 @@ as boxes, turn them off with `ui.icons: false`. Several config files can be layered, later ones winning (theme roles and keybindings merge one by one), with a comma-separated `--config` or -`LAZYSECRETS_CONFIG_FILE`, like lazygit's `LG_CONFIG_FILE`. An editor -plugin can so add a generated theme file to your own config, the way -snacks.nvim themes lazygit from Neovim's highlight groups: +`LAZYSECRETS_CONFIG_FILE`, like lazygit's `LG_CONFIG_FILE`; e.g. your +config plus an editor-generated theme: ```sh LAZYSECRETS_CONFIG_FILE=~/.config/lazysecrets/config.yaml,~/.cache/nvim/lazysecrets-theme.yml lazysecrets @@ -117,11 +100,10 @@ Stars, notes, usage and the layout are kept in by you: one record per source, vault or secret, keyed by its `lazysecrets://` link, never with values. A star belongs to the account you starred the item under (a vault two of your accounts can see can be starred -for one); a note describes the item, so it shows under every account. It's -JSON so an editor plugin can read it with a built-in parser; several -lazysecrets windows can save to it without losing each other's changes. -One written by a newer lazysecrets is read but not saved to, with a -warning, until you update. +for one); a note describes the item, so it shows under every account. +Several lazysecrets windows can save to it without losing each other's +changes. One written by a newer lazysecrets is read but not saved to, +with a warning, until you update. Revealing, copying, opening in the browser, sharing and jumping to an item count as using it: its record keeps when it was last used and how often, @@ -157,8 +139,9 @@ until then it reuses the answer from the state file. Releases are published on GitHub and on git.kebcloud.no, and it asks them in that order, the next when one doesn't answer within 5 seconds; `updates.sources` lists others, such as a mirror of your own. Offline, or with -every server down, it says nothing. A newer release shows in the footer, `v0.1.1 ↑ v0.2.0`; `U` (or -`lazysecrets update --check`) shows what changed since your version, across the last 10 releases. +every server down, it says nothing. A newer release shows in the status +pane, `↑ v0.2.0`; `U` (or `lazysecrets update --check`) shows what +changed since your version, across the last 10 releases. Updating (`u` there, or `lazysecrets update`) downloads the release for your OS and CPU from the first server that has it, checks it against diff --git a/docs/development.md b/docs/development.md index 6ebdcd5..5e11fa5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -12,7 +12,7 @@ repo, pick `kv-shared-prod / env-share` (the second account's) as the key, then paste the link back. The demo repos aren't on disk, so opening asks where to save, as for a repo you haven't cloned. -A stripped binary is about 21 MB instead of 30 MB: +A stripped binary is a third smaller: ```sh go build -trimpath -ldflags "-s -w" -o lazysecrets ./cmd/lazysecrets @@ -35,10 +35,8 @@ subject, checked by `pr-title.yml`: | `fix` | a bug fix | Fixed | | `refactor`, `docs`, `test`, `ci`, `chore`, `build`, `style`, `revert` | everything users don't need to hear about | no | -`feat!:` marks a breaking change, `feat(scope):` names a part. Brackets -and a missing space work too: `[feat] x`, `[feat]: x` and `feat:x` all -become `feat: x` in the changelog. `[skip changelog]` in the description -leaves a pull request out. +`feat!:` marks a breaking change, `feat(scope):` names a part. +`[skip changelog]` in the description leaves a pull request out. CI (`ci.yml`) runs gofmt, vet, staticcheck, the tests and a build for each platform on pull requests into `main`. `main` is protected: a pull request diff --git a/docs/integration.md b/docs/integration.md index 79e6ee3..65f2f62 100644 --- a/docs/integration.md +++ b/docs/integration.md @@ -34,7 +34,7 @@ tab-separated: | name | `platform-prod / kv-app-prod / db-password` | | status | why a vault or source couldn't be read, or that it has `expired` or `expires in 12d` (within `ui.expiryWarningDays`), or empty | | note | your note on it (`n` in lazysecrets), after a note icon (✎ without icons), or empty | -| account | what it's listed through: an az account (`Azure:/`), `Databricks` or `Repos` | +| account | what it's listed through: `Azure` (`Azure:/` with several az accounts), `Databricks` or `Repos` | | link | its `lazysecrets://` link | What's cached prints at once, then what loads follows as it arrives: read @@ -47,7 +47,7 @@ so `^prod` finds names starting with prod. | Flag | | |---|---| | `--format json` | an object per line instead, for editor plugins (below) | -| `--kind secret,vault` | only these kinds: `source`, `vault`, `secret`, `key`, `certificate`; lists only other kinds need aren't loaded | +| `--kind secret,vault` | only these kinds: `source`, `vault` (also scopes and repo files), `secret`, `key`, `certificate`; lists they don't need aren't loaded | | `--cached` | only what's cached, at once: nothing is loaded from Azure or Databricks | | `--max-age 2m` | load cached lists older than this again | | `--errors=false` | leave out the vaults and sources it couldn't read | @@ -77,12 +77,11 @@ may be added: | `expires` | when a secret, key or certificate expires, if it does (Azure) | | `enabled` | `false` for a disabled one; only where the provider says (Azure) | -`lazysecrets open --action go --account ` opens one in -lazysecrets without asking what to do or which account, ending in the -secrets list, like Go to. +[`lazysecrets open --action go --account `](sharing.md#opening-a-link) +opens one in lazysecrets without asking what to do or which account. +### An fzf picker -### Example usage with fzf ```sh lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' --accept-nth=-1 \ --header 'enter: link · ctrl-o: open · ctrl-y: copy value · ctrl-x: copy and close' \ @@ -90,5 +89,6 @@ lazysecrets list | fzf --ansi --delimiter='\t' --with-nth='2..-3' --nth='2..' -- --bind 'ctrl-y:execute-silent(lazysecrets get --account {-2} {-1} | pbcopy)+change-header(Copied the value of {3})' \ --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)' ``` + ![fzf-example](assets/fzf-example.png) diff --git a/docs/keys.md b/docs/keys.md index 90e862c..829dc24 100644 --- a/docs/keys.md +++ b/docs/keys.md @@ -49,7 +49,7 @@ match case exactly. | Key | Action | |---|---| | `space` | reveal / hide the selected value (public material for keys and certificates) | -| `y` | copy the value without revealing it; cleared from the clipboard after 30s. On an Azure account's row: its object ID; in its pane, the selected field | +| `y` | copy the value without revealing it. On an Azure account's row: its object ID; in its pane, the selected field | | `Y` | copy the reference (`@Microsoft.KeyVault(...)`, key/certificate URL, `{{secrets/scope/key}}`) | | `v` | versions of the selected item (Azure); `space`/`y`/`Y` then act on that version; `esc`, `⌫` or `v` to go back | | `o` | open the selected item in the browser (over SSH: copy the link) | @@ -63,10 +63,8 @@ match case exactly. A revealed value is shown as it reads best: JSON indented, and PEM certificates as their subject, issuer, dates, names and thumbprint, with any other PEM block (a private key) named but not shown. `y` still copies -it exactly as stored. - -A revealed value hides again after `values.revealTimeout` (60s) and -when the terminal loses focus (`values.hideOnBlur`); see [config](config.md). +it exactly as stored. It hides again after a while, and when the terminal +loses focus ([config](config.md)). ## Stars and notes @@ -75,8 +73,7 @@ when the terminal loses focus (`values.hideOnBlur`); see [config](config.md). | `f` | star the selected source, vault or secret: it gets a ★ and sorts first in its list | | `n` | write a short note on it, shown dimmed on its row and in the detail pane | -A star belongs to the account you starred the item under; a note shows -under every account. Both are kept in the [state file](config.md#state). +Both are kept in the [state file](config.md#state). ## Go to @@ -124,15 +121,16 @@ it's hidden. On top, the status pane (`0`) shows the version, a newer release and how your accounts are doing; `e` there opens your [config](config.md) in your editor, as in lazygit. Focused, the right pane lists more under the -logo (when there's room): the version and updates (`U`), each account -(`L` on one that needs it signs in), what's expiring (`enter` goes to -it), this session's errors, newest first (what a pane showed, or the -footer flashed before you moved on; not kept after quitting), the config, -state and cache files (`e` opens one in your editor), and links to the -docs, source, issues, releases and changelog (`o` opens one; on the -version or update, its release), then the changelog of every release up -to yours, built in so it needs no network: `/` filters it (`/fixed`, -`/search`). `y` copies any row. +logo; `y` copies any row: + +- the version and updates (`U`) +- each account (`L` on one that needs it signs in) +- what's expiring (`enter` goes to it) +- this session's errors, newest first (not kept after quitting) +- the config, state and cache files (`e` opens one in your editor) +- links to the docs, source, issues, releases and changelog (`o` opens one) +- the changelog of every release up to yours, built in: `/` filters it + (`/fixed`, `/search`) | Key | Action | |---|---| @@ -141,9 +139,8 @@ to yours, built in so it needs no network: `/` filters it (`/fixed`, | `+` / `_` | zoom the focused pane: normal → half → full screen, and back | | `=` | reset the layout (divider, heights, zoom) | -The divider and pane heights are remembered (zoom isn't). macOS uses -ctrl+arrows for Mission Control and switching desktops by default, hence -the `<` `>` `{` `}` alternatives. +The divider and pane heights are remembered (zoom isn't). `<>{}` are for +macOS, where ctrl+arrows switch desktops. ## Rebinding keys diff --git a/docs/repos.md b/docs/repos.md index 3a994a7..08d55a0 100644 --- a/docs/repos.md +++ b/docs/repos.md @@ -100,13 +100,5 @@ sops 3.8 or later. ## Links -`S` → `f` shares env files as an [encrypted link](sharing.md#sharing-env-files). - -Links name the repo by its git remote, so they open in a colleague's clone -wherever it is: - -``` -lazysecrets://repo/git.example.com%2Fteam%2Finfra/secrets%2Fapp.yaml/db.password -``` - -See [sharing](sharing.md). +Repo links name the repo by its git remote, so they open in a colleague's +clone wherever it is ([sharing](sharing.md)). diff --git a/docs/sharing.md b/docs/sharing.md index 80336fa..6168b3b 100644 --- a/docs/sharing.md +++ b/docs/sharing.md @@ -7,10 +7,13 @@ permissions: the link names the item, never its value. Env files can also be [shared encrypted](#sharing-env-files), in the link itself. ``` +lazysecrets://azure/subscriptions/ subscription lazysecrets://azure/kv-app-prod.vault.azure.net vault lazysecrets://azure/kv-app-prod.vault.azure.net/keys vault, Keys tab lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password secret lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password/91d3e0 one version +lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net workspace +lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net/app scope lazysecrets://databricks/adb-1111111111111111.11.azuredatabricks.net/app/storage-key lazysecrets://repo/git.example.com%2Fteam%2Finfra/secrets%2Fapp.yaml/db.password ``` @@ -102,8 +105,8 @@ it now and then: new links use the newest version. ## Opening a link - Paste it into lazysecrets, or press `ctrl+o`, which reads the clipboard - and fills in any reference it finds there. Key Vault URLs, - `@Microsoft.KeyVault(...)` and `{{secrets/scope/key}}` work too. + and fills in any reference it finds there. Key Vault URLs, Azure portal + links, `@Microsoft.KeyVault(...)` and `{{secrets/scope/key}}` work too. - `lazysecrets ` (or `lazysecrets open `) in a terminal. - Click it anywhere, once the [link handler](#from-the-browser-and-chat) is set up. -- 2.54.0