docs: get and list move to their own page, integration.md

2026-10-14 21:24:01 +02:00
1 parent 470f0c11e4
commit b0ea217d87
@@ -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 <link>` 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,
+- [Links](docs/links.md): sharing, opening, and opening links from the
-  and opening links from the browser and chat
+  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
@@ -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
@@ -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 <link>` 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:<user>/<tenant>`), `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/<tenant>","accountLabel":"alice"}
 ```
 `accountLabel`, the account's short name, is there when several az
 accounts are signed in. Values are never listed.
@@ -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 <link>` does one without asking
 and ends in the list, like Go to,
-and `--account <account>` picks the account (as [`list`](#listing-for-fzf-and-pickers)
+and `--account <account>` picks the account (as [`list`](integration.md#listing-for-fzf-and-pickers)
 prints it) when several can see it.
 ## In scripts
 `lazysecrets get <link>` 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:<user>/<tenant>`), `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/<tenant>","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