lew/pda
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: some further readme updates and tweaks

Browse source
This commit is contained in:
Lewis Wynne 2026-04-01 15:13:32 +01:00
parent d71f00357e
commit 2f87f0fd98
1 changed files with 16 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

66
README.md
View file

@ -1251,7 +1251,7 @@ pda rm cat --key "{mouse,[cd]og}**"
</sup> </sup>
</p> </p>
`pda!` supports all binary data. Values can be read from a file with `--file` or piped in via stdin. Retrieval works the same way — pipe or redirect the output to get the raw bytes. `pda!` supports all binary data. Values can be read from a file with `--file` or piped in via stdin. Retrieval works the same way: pipe or redirect the output to get the raw bytes.
```bash ```bash
# store binary data from a file # store binary data from a file
@ -1357,18 +1357,14 @@ The amount of Git automation can be configured via `git.auto_commit`, `git.auto_
</sup> </sup>
</p> </p>
[`pda identity`](#identity) (alias: [`id`](#identity)) manages the age encryption identity used for [encryption](#encryption). [`pda identity`](#identity) (alias: [`id`](#identity)) manages the [age](https://github.com/FiloSottile/age) identity used for [encryption](#encryption). An identity is generated automatically the first time [`--encrypt`](#encryption) is used, but one can also be created manually with `--new`. [`--new`](#identity) will error if an identity already exists; delete the file manually to replace it.
#### Viewing Identity ```bash
# create a new identity manually
pda identity --new
```
<p> With no flags, [`pda identity`](#identity) displays your public key, identity file path, and any additional recipients. Passing `path` prints only the identity file path, useful for scripting.
<sup>
<a href="#overview">↑</a> ·
<a href="#pda-identity"><code>pda identity</code></a>
</sup>
</p>
With no flags, [`pda identity`](#identity) shows your public key, identity file path, and any additional recipients. Passing `path` prints only the identity file path, useful for scripting.
```bash ```bash
❯ pda identity ❯ pda identity
@ -1379,23 +1375,6 @@ With no flags, [`pda identity`](#identity) shows your public key, identity file
~/.config/pda/identity.txt ~/.config/pda/identity.txt
``` ```
#### Creating an Identity
<p>
<sup>
<a href="#overview">↑</a> ·
<a href="#pda-identity"><code>pda identity</code></a>
</sup>
</p>
An identity is generated automatically the first time you use [`--encrypt`](#encryption). To create one manually:
```bash
pda identity --new
```
[`--new`](#identity) errors if an identity already exists. Delete the file manually to replace it.
#### Recipients #### Recipients
<p> <p>
@ -1405,7 +1384,7 @@ pda identity --new
</sup> </sup>
</p> </p>
By default, secrets are encrypted only for your own identity. To encrypt for additional recipients (e.g. a teammate or another device), use [`--add-recipient`](#identity) with their age public key. All existing secrets are automatically re-encrypted for every recipient: By default, secrets are encrypted only for your own identity. To encrypt for additional recipients (e.g. another device or a friend), use [`--add-recipient`](#identity) with their age public key. All existing secrets are automatically re-encrypted for every recipient.
```bash ```bash
❯ pda identity --add-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p ❯ pda identity --add-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
@ -1414,7 +1393,7 @@ By default, secrets are encrypted only for your own identity. To encrypt for add
ok re-encrypted 1 secret(s) ok re-encrypted 1 secret(s)
``` ```
Removing a recipient with `--remove-recipient` re-encrypts all secrets without their key. Additional recipients are shown in the default identity display. Removing a recipient with `--remove-recipient` re-encrypts all secrets without their key. Additional recipients are shown in the default [`pda identity`](#identity) output.
```bash ```bash
pda identity --remove-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p pda identity --remove-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
@ -1435,18 +1414,7 @@ pda identity --remove-recipient age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2k
</sup> </sup>
</p> </p>
Config is stored at `~/.config/pda/config.toml` (Linux/macOS) or `%LOCALAPPDATA%/pda/config.toml` (Windows). All values have sensible defaults, so a config file is entirely optional. Config is stored at `~/.config/pda/config.toml` (Linux/macOS) or `%LOCALAPPDATA%/pda/config.toml` (Windows). All values have sensible defaults, so a config file is entirely optional. [`pda config`](#config) manages configuration without needing to edit files by hand, and [`pda doctor`](#doctor) will warn about unrecognised keys (typos, removed options) and show any non-default values, so it doubles as a config audit.
#### Config Commands
<p>
<sup>
<a href="#overview">↑</a> ·
<a href="#pda-config"><code>pda config</code></a>
</sup>
</p>
[`pda config`](#config) manages configuration without editing files by hand:
```bash ```bash
# list all config values and their current settings # list all config values and their current settings
@ -1475,9 +1443,7 @@ pda config init --new
pda config init --update pda config init --update
``` ```
[`pda doctor`](#doctor) will warn about unrecognised keys (typos, removed options) and show any non-default values, so it doubles as a config audit. #### Default Config
#### Example config.toml
<p> <p>
<sup> <sup>
@ -1547,7 +1513,7 @@ default_commit_message = "{{ summary }} {{ time }}"
`pda!` respects a small set of environment variables for overriding paths and tools. These are primarily useful for isolating stores across environments or for scripting. `pda!` respects a small set of environment variables for overriding paths and tools. These are primarily useful for isolating stores across environments or for scripting.
`PDA_CONFIG` overrides the config directory — `pda!` will look for `config.toml` here instead of the default XDG location. `PDA_DATA` overrides the data storage directory where stores and the Git repository live. Default data locations follow XDG conventions: `~/.local/share/pda/` on Linux, `~/Library/Application Support/pda/` on macOS, and `%LOCALAPPDATA%/pda/` on Windows. `PDA_CONFIG` overrides the config directory, causing `pda!` to look for `config.toml` here instead of the default XDG location. `PDA_DATA` overrides the data storage directory where stores and the Git repository live. Default data locations follow XDG conventions: `~/.local/share/pda/` on Linux, `~/Library/Application Support/pda/` on macOS, and `%LOCALAPPDATA%/pda/` on Windows.
```bash ```bash
# use an alternative config directory # use an alternative config directory
@ -1557,7 +1523,7 @@ PDA_CONFIG=/tmp/config/ pda set key value
PDA_DATA=/tmp/stores pda set key value PDA_DATA=/tmp/stores pda set key value
``` ```
`EDITOR` is used by [`pda edit`](#editing) and [`pda config edit`](#config) to open values in a text editor. Must be set for these commands to work. `SHELL` is used by [`pda run`](#running) (or [`pda get --run`](#getting)) for command execution, falling back to `/bin/sh` if unset. `EDITOR` is used by [`pda edit`](#editing) and [`pda config edit`](#config) to open values in a text editor, and must be set for these commands to work. `SHELL` is used by [`pda run`](#running) (or [`pda get --run`](#getting)) for command execution, falling back to `/bin/sh` if unset.
```bash ```bash
EDITOR=nvim pda edit mykey EDITOR=nvim pda edit mykey
@ -1573,7 +1539,7 @@ EDITOR=nvim pda edit mykey
</sup> </sup>
</p> </p>
[`pda doctor`](#doctor) runs a set of health checks against your environment, covering installed tools, config validity, store integrity, and Git status. [`pda doctor`](#doctor) runs a set of health checks against your [environment](#environment), covering installed tools, [config](#config) validity, [store](#stores) integrity, and [Git](#git) status. As mentioned in [config](#config), it also doubles as a config audit by warning about unrecognised keys and surfacing any non-default values.
```bash ```bash
❯ pda doctor ❯ pda doctor
@ -1595,7 +1561,7 @@ EDITOR=nvim pda edit mykey
ok No issues found ok No issues found
``` ```
Severity levels are colour-coded: `ok` (green), `WARN` (yellow), and `FAIL` (red). Only `FAIL` produces a non-zero exit code. `WARN` is generally not a problem, but may mean some functionality isn't being made use of, like version control not having been initialised yet. Severity levels are colour-coded: `ok` (green), `WARN` (yellow), and `FAIL` (red). Only `FAIL` produces a non-zero exit code. `WARN` is generally not a problem, but may indicate that some functionality isn't being made use of (like [version control](#git) not having been initialised yet).
### Version ### Version
@ -1606,7 +1572,7 @@ Severity levels are colour-coded: `ok` (green), `WARN` (yellow), and `FAIL` (red
</sup> </sup>
</p> </p>
[`pda version`](#version) displays the current version. Passing `short` prints just the release string without ASCII art, useful for scripting. `pda!` uses calendar versioning: `YYYY.WW`. ASCII art can be permanently disabled with `display_ascii_art = false` in [config](#config). [`pda version`](#version) displays the current version. `pda!` uses calendar versioning in the format `YYYY.WW`. Passing `short` prints just the release string without ASCII art, useful for scripting. The ASCII art can also be permanently disabled with `display_ascii_art = false` in the [config](#config).
```bash ```bash
# display the full version output # display the full version output