119 lines
5.4 KiB
Markdown
119 lines
5.4 KiB
Markdown
# Links
|
|
|
|
Every subscription, workspace, vault, scope, repo, file and secret has a
|
|
`lazysecrets://` link. Share one in chat or a ticket, and whoever opens it
|
|
lands on that item, reading it with their own account and permissions:
|
|
links carry names, never values.
|
|
|
|
```
|
|
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/app/storage-key
|
|
lazysecrets://repo/git.example.com%2Fteam%2Finfra/secrets%2Fapp.yaml/db.password
|
|
```
|
|
|
|
## Sharing
|
|
|
|
`s` copies a link to the selected item (from the versions view, pinned to
|
|
that version). `S` opens the share menu:
|
|
|
|
- secrets: the link (`o`), the plain Key Vault URL (`u`), the config
|
|
reference (`y`) or the web page (`b`)
|
|
- vaults and scopes: a link (`o`), a link that opens on the current tab
|
|
(`t`), the plain vault URL (`u`) or the web page (`b`)
|
|
- subscriptions and workspaces: a link (`o`) or the web page (`b`)
|
|
|
|
## Opening
|
|
|
|
- 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.
|
|
- `lazysecrets <link>` (or `lazysecrets open <link>`) in a terminal.
|
|
- Click it anywhere, once the [link handler](#from-the-browser-and-chat) is
|
|
set up.
|
|
|
|
If you copy a `lazysecrets://` link elsewhere and switch back, lazysecrets
|
|
offers to open it, once per link. It looks at the clipboard at startup,
|
|
when the terminal regains focus (in tmux: `set -g focus-events on`) and,
|
|
for terminals that don't report focus, on a key press at most every 3
|
|
seconds. It keeps nothing but `lazysecrets://` links, doesn't offer a link
|
|
to what's already selected (like one you just copied with `s`), and can't
|
|
read the clipboard over SSH.
|
|
|
|
lazysecrets finds the vault in your accounts (one Resource Graph query per
|
|
account) and jumps to it, asking which account to use when several can see
|
|
it. Links say what, 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.
|
|
|
|
## 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.
|
|
|
|
## From the browser and chat
|
|
|
|
```sh
|
|
lazysecrets handler install # run it in the terminal links should open in
|
|
lazysecrets handler uninstall
|
|
```
|
|
|
|
Use an installed binary (`go run`'s is temporary). lazysecrets offers to do
|
|
this at startup when links don't open it (or open a lazysecrets that no
|
|
longer exists): set it up, not now, or don't ask again, which is
|
|
remembered in the state file. `linkHandler.prompt: false` in the config
|
|
turns the question off too.
|
|
|
|
`handler install` registers `lazysecrets://` with the system: clicking a
|
|
link then opens a new window of the terminal you ran it in, with
|
|
lazysecrets on that link. It recognises kitty, Ghostty, WezTerm, iTerm2,
|
|
Terminal.app, Alacritty, GNOME Terminal, Konsole and foot, also inside
|
|
tmux; `--terminal NAME` picks another. It records your `PATH` and config
|
|
locations, since apps start without your shell's environment (and so
|
|
without `az`): run it again after moving lazysecrets or changing those.
|
|
|
|
- macOS: a small background app, `~/Applications/Lazysecrets Links.app`
|
|
- Linux: a desktop entry claiming `x-scheme-handler/lazysecrets`, set as
|
|
the default with `xdg-mime` (desktops following freedesktop.org)
|
|
- Windows: not yet
|
|
|
|
The config can override the terminal, or run any other:
|
|
|
|
```yaml
|
|
linkHandler:
|
|
terminal: ghostty # instead of the one install detected
|
|
command: [foot, --title, secrets, "{cmd}"] # any terminal; {cmd} is the lazysecrets command
|
|
reuse: true # hand links to a running lazysecrets first
|
|
prompt: true # offer to set up the handler at startup
|
|
```
|
|
|
|
### Where a clicked link opens
|
|
|
|
- **In a terminal** (a link in a terminal app): a lazysecrets that
|
|
terminal shows (or whose tmux session one of its tmux clients can switch
|
|
to) gets it, never one elsewhere; otherwise a new window opens.
|
|
- **Anywhere else** (Slack, a browser): the lazysecrets you used last (key
|
|
press or focus), preferring one already on screen; a tmux client is
|
|
switched to its session if needed, its terminal comes to the front, and
|
|
a hidden dropdown terminal (kitty's quick access terminal) is shown.
|
|
With none running, a new window opens.
|
|
|
|
The link is then offered as if pasted. `linkHandler.reuse: false` always
|
|
opens a new window.
|
|
|
|
Running instances listen on a socket in `$XDG_RUNTIME_DIR/lazysecrets`, or
|
|
`run/` in the state directory, readable only by you. A link from a web page
|
|
can only make lazysecrets go somewhere: it asks before copying or showing
|
|
anything.
|