diff --git a/README.md b/README.md index 4d4a4e9..1f04d24 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ A terminal UI for finding, reading and sharing secrets. Inspired by the fantasti copied values are cleared from the clipboard after 30 seconds. - **Scriptable**: `lazysecrets get ` prints a value for scripts and pipes, and `lazysecrets list` everything it can find, for fzf and editor - pickers. + pickers ([integration](docs/integration.md)). - **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. @@ -87,8 +87,10 @@ use most: - [Azure Key Vault](docs/azure.md): accounts, permissions, pinned vaults - [Databricks](docs/databricks.md): profiles and Key Vault-backed scopes - [SOPS and .env files](docs/repos.md): which repos and files, decrypting -- [Links](docs/links.md): sharing, opening, `lazysecrets get` and `list` in scripts, - and opening links from the browser and chat +- [Links](docs/links.md): sharing, opening, and opening links from the + browser and chat +- [Integration](docs/integration.md): `lazysecrets get` in scripts, and + `lazysecrets list` for fzf and editor pickers - [Custom commands](docs/custom-commands.md): run your own commands on a secret - [Config](docs/config.md): every option, themes, layered configs, the diff --git a/docs/config.md b/docs/config.md index d5d9740..70fd2f2 100644 --- a/docs/config.md +++ b/docs/config.md @@ -140,7 +140,7 @@ you: the Sources lists, vaults and scopes, and secrets' names and metadata once, and anything older than two minutes reloads in the background when you go to it, or when Go to searches it. While it does, the pane's bottom border says how old what it shows is (`cached 3h ago`). Revealing -and copying always fetch the value live. [`lazysecrets list`](links.md#listing-for-fzf-and-pickers) +and copying always fetch the value live. [`lazysecrets list`](integration.md#listing-for-fzf-and-pickers) reads it and adds to it too. Lists not loaded for 30 days are dropped, and so is everything from an diff --git a/docs/integration.md b/docs/integration.md new file mode 100644 index 0000000..2a5c207 --- /dev/null +++ b/docs/integration.md @@ -0,0 +1,97 @@ +# Integration + +lazysecrets works outside its own window too: `lazysecrets get` reads a +value for scripts, and `lazysecrets list` lists everything for fzf, editor +pickers and your own tools. Both take the [links](links.md) lazysecrets +copies and shares. For Neovim, there's +[lazysecrets.nvim](https://github.com/karleinarb/lazysecrets.nvim). + +## Reading a value + +`lazysecrets get ` prints the value, for scripts and pipes: + +```sh +export DB_PASSWORD=$(lazysecrets get lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password) +lazysecrets get lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password | kubectl create secret generic db --from-file=password=/dev/stdin +``` + +It reads the value directly, with your az accounts (the one that last read +it first), the Databricks profile for the workspace, or sops in your clone +of the repo; a version in the link reads that version. `--account` tries +that account first, as [`list`](#listing-for-fzf-and-pickers) prints it. +The value ends with a newline only on a terminal. + +## Listing, for fzf and pickers + +`lazysecrets list` prints every source, vault and secret, one per line, +tab-separated: + +| Field | | +|---|---| +| kind | `source`, `vault`, `secret`, `key` or `certificate` | +| name | `platform-prod / kv-app-prod / db-password` | +| account | what it's listed through: an az account (`Azure:/`), `Databricks` or `Repos` | +| link | its `lazysecrets://` link | + +It's what Go to searches, so fzf, or an editor's picker, can search it +instead, showing the names and acting on the links: + +```sh +lazysecrets list | fzf --ansi --with-nth='2..-3' --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 {2..-3})' \ + --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)' +``` + +`--with-nth='2..-3'` shows and searches only the names; `{-1}` and +`--accept-nth=-1` are the link, `{-2}` the account. All but the name are +one word, so this works without `--delimiter`. To filter by kind +yourself: `awk -F'\t' '$1 == "secret"'`. + +`enter` prints the link (`lazysecrets get $(…)`), `ctrl-o` opens it in +lazysecrets, `ctrl-y` copies the value, saying so in the header, and +`ctrl-x` copies it and closes fzf (`pbcopy` on macOS; `wl-copy` or `xclip` +on Linux). A value copied this way isn't cleared from the +clipboard after `values.clipboardClear`, as one copied in lazysecrets is. + +`--account` makes `open` and `get` use the account it was listed through, +when several of yours can see it: without, `open` asks which, and `get` +tries the one that last read it first. The link stays as it is, to copy +and share; the account isn't part of it. `--action` tells `open` what to +do rather than asking, as it does for a link clicked elsewhere: `go` to +it, `copy` its value too, or `show` it. It ends in the secrets list, like +Go to, rather than on the details as a clicked link does. + +What's [cached](config.md#cache) prints at once. Then, like Go to, it loads +what's missing or older than `--max-age` (2m), and what's new in it follows +as it arrives: fzf shows it while you type. `--cached` loads nothing from +Azure or Databricks, for an answer at once. Repos are always read, from +disk. What it loads is cached for the TUI too. It stops when the reader +goes, after a pick in fzf. + +`--kind` lists only some kinds, comma-separated: `source`, `vault` (also +Databricks scopes and repo files), `secret`, `key`, `certificate`. Lists +only other kinds need aren't loaded: `--kind source,vault` asks for no +secrets. Keys and certificates load only when asked for this way; else, +like Go to, they're listed as far as you opened them in lazysecrets. + +A vault or source it can't read is a line too, as it fails: its name, +then `✗` and why in red (`errorColor`), with its link, so opening it +shows more. They're in the list, not on stderr, which would draw over fzf. +`--errors=false` leaves them out. + +The name is coloured from your [theme](config.md#theme), with the +provider's icon when [icons](config.md#theme) are on (`ui.icons`); fzf +shows the colours with `--ansi`. `--color never` leaves them out, for +scripts, and `--icons=false` the icons. The link is never coloured. + +`--format json` prints an object per line instead, for editor plugins, +without colours or icons, and with `error` on a list it couldn't read: + +```json +{"link":"lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password","kind":"secret","provider":"azure","path":["platform-prod","kv-app-prod","db-password"],"account":"Azure:alice@example.com/","accountLabel":"alice"} +``` + +`accountLabel`, the account's short name, is there when several az +accounts are signed in. Values are never listed. diff --git a/docs/links.md b/docs/links.md index c619d56..53139f5 100644 --- a/docs/links.md +++ b/docs/links.md @@ -123,98 +123,9 @@ not what to do: opening a link to a secret asks whether to just go to it, also copy or show its value, or (`y`) copy its value without going there. `lazysecrets open --action go|copy|show ` does one without asking and ends in the list, like Go to, -and `--account ` picks the account (as [`list`](#listing-for-fzf-and-pickers) +and `--account ` picks the account (as [`list`](integration.md#listing-for-fzf-and-pickers) prints it) when several can see it. -## In scripts - -`lazysecrets get ` prints the value, for scripts and pipes: - -```sh -export DB_PASSWORD=$(lazysecrets get lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password) -lazysecrets get lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password | kubectl create secret generic db --from-file=password=/dev/stdin -``` - -It reads the value directly, with your az accounts (the one that last read -it first), the Databricks profile for the workspace, or sops in your clone -of the repo; a version in the link reads that version. The value ends with -a newline only on a terminal. - -### Listing, for fzf and pickers - -`lazysecrets list` prints every source, vault and secret, one per line, -tab-separated: - -| Field | | -|---|---| -| kind | `source`, `vault`, `secret`, `key` or `certificate` | -| name | `platform-prod / kv-app-prod / db-password` | -| account | what it's listed through: an az account (`Azure:/`), `Databricks` or `Repos` | -| link | its `lazysecrets://` link | - -It's what Go to searches, so fzf, or an editor's picker, can search it -instead, showing the names and acting on the links: - -```sh -lazysecrets list | fzf --ansi --with-nth='2..-3' --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 {2..-3})' \ - --bind 'ctrl-x:become(lazysecrets get --account {-2} {-1} | pbcopy)' -``` - -`--with-nth='2..-3'` shows and searches only the names; `{-1}` and -`--accept-nth=-1` are the link, `{-2}` the account. All but the name are -one word, so this works without `--delimiter`. To filter by kind -yourself: `awk -F'\t' '$1 == "secret"'`. - -`enter` prints the link (`lazysecrets get $(…)`), `ctrl-o` opens it in -lazysecrets, `ctrl-y` copies the value, saying so in the header, and -`ctrl-x` copies it and closes fzf (`pbcopy` on macOS; `wl-copy` or `xclip` -on Linux). A value copied this way isn't cleared from the -clipboard after `values.clipboardClear`, as one copied in lazysecrets is. - -`--account` makes `open` and `get` use the account it was listed through, -when several of yours can see it: without, `open` asks which, and `get` -tries the one that last read it first. The link stays as it is, to copy -and share; the account isn't part of it. `--action` tells `open` what to -do rather than asking, as it does for a link clicked elsewhere: `go` to -it, `copy` its value too, or `show` it. It ends in the secrets list, like -Go to, rather than on the details as a clicked link does. - -What's [cached](config.md#cache) prints at once. Then, like Go to, it loads -what's missing or older than `--max-age` (2m), and what's new in it follows -as it arrives: fzf shows it while you type. `--cached` loads nothing from -Azure or Databricks, for an answer at once. Repos are always read, from -disk. What it loads is cached for the TUI too. It stops when the reader -goes, after a pick in fzf. - -`--kind` lists only some kinds, comma-separated: `source`, `vault` (also -Databricks scopes and repo files), `secret`, `key`, `certificate`. Lists -only other kinds need aren't loaded: `--kind source,vault` asks for no -secrets. Keys and certificates load only when asked for this way; else, -like Go to, they're listed as far as you opened them in lazysecrets. - -A vault or source it can't read is a line too, as it fails: its name, -then `✗` and why in red (`errorColor`), with its link, so opening it -shows more. They're in the list, not on stderr, which would draw over fzf. -`--errors=false` leaves them out. - -The name is coloured from your [theme](config.md#theme), with the -provider's icon when [icons](config.md#theme) are on (`ui.icons`); fzf -shows the colours with `--ansi`. `--color never` leaves them out, for -scripts, and `--icons=false` the icons. The link is never coloured. - -`--format json` prints an object per line instead, for editor plugins, -without colours or icons, and with `error` on a list it couldn't read: - -```json -{"link":"lazysecrets://azure/kv-app-prod.vault.azure.net/secrets/db-password","kind":"secret","provider":"azure","path":["platform-prod","kv-app-prod","db-password"],"account":"Azure:alice@example.com/","accountLabel":"alice"} -``` - -`accountLabel`, the account's short name, is there when several az -accounts are signed in. Values are never listed. - ## From the browser and chat ```sh