From 940c3d694def830d43a86850ac6f65670a62cf8d Mon Sep 17 00:00:00 2001 From: lew Date: Sat, 14 Feb 2026 04:17:05 +0000 Subject: [PATCH] docs: progressively updating README.md --- README.md | 1233 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 821 insertions(+), 412 deletions(-) diff --git a/README.md b/README.md index 65eef93..f95caa9 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,11 @@ and more, written in pure Go, and inspired by [skate](https://github.com/charmbr

-`pda!` stores key-value pairs natively as [newline-delimited JSON](https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON) files. Every store is plaintext, portable, and yours. There's no daemon, no cloud service, and no proprietary format. Keys are just lines in a JSON file; stores are just files in a directory. If you can `cat` a file, you can read your data without `pda!` installed. +`pda` stores key-value pairs natively as [newline-delimited JSON](https://en.wikipedia.org/wiki/JSON_streaming#Newline-delimited_JSON) files. [`pda list`](#listing) outputs tabular data by default, but also supports [CSV](https://en.wikipedia.org/wiki/Comma-separated_values), [TSV](), [Markdown]() and [HTML]() tables, [JSON](), and raw NDJSON. Everything is in plaintext to make version control easy, and to avoid tying anybody to using this tool forever. -Git versioning is built in. Enable auto-committing, pushing, and fetching in the [config](#config) to automatically version every change, or just run [`pda sync`](#sync) when you want to. Because the storage format is line-oriented plaintext, diffs are meaningful and merges are clean. +Git versioning can be initiated with [`pda init`](#git), and varying levels of automation can be toggled via the [config](#config): `git.autocommit`, `git.autofetch`, and `git.autopush`. Running Git operations on every change can be slow, but a commit is fast. A happy middle-ground is enabling `git.autocommit` and doing the rest manually via [`pda sync`](#git) when changing devices. -Go's [`text/template`](https://pkg.go.dev/text/template) engine is available on every value at retrieval time, turning simple key-value pairs into dynamic snippets with variables, environment lookups, shell execution, cross-references, and more. +[Templates](#templates) are a primary feature, enabling values to make use of substitutions, environment variables, arbitrary shell execution, cross-references to other keys, and more.

@@ -136,59 +136,18 @@ Powershell users will need to manually add the above command to their profile; t Import & Export · Templates · Filtering · - Binary Data + Binary Data · Git · Identity · Config · Environment · Doctor · - Help & Version + Version · + Help

-```bash -pda! MIT licensed. (c) 2025 Lewis Wynne - -Usage: - pda [command] - -Key commands: - copy Make a copy of a key - edit Edit a key's value in $EDITOR - get Get the value of a key - identity Show or create the age encryption identity - list List the contents of all stores - meta View or modify metadata for a key - move Move a key - remove Delete one or more keys - run Get the value of a key and execute it - set Set a key to a given value - -Store commands: - export Export store as NDJSON (alias for list --format ndjson) - import Restore key/value pairs from an NDJSON dump - list-stores List all stores - move-store Rename a store - remove-store Delete a store - -Git commands: - git Run any arbitrary command. Use with caution. - init Initialise pda! version control - sync Manually sync your stores with Git - -Environment commands: - config View and modify configuration - doctor Check environment health - -Additional Commands: - completion Generate the autocompletion script for the specified shell - help Help about any command - version Display pda! version -``` - -

- Most commands have aliases and flags. Run `pda help [command]` to see them. ### Key commands @@ -196,13 +155,13 @@ Most commands have aliases and flags. Run `pda help [command]` to see them.

↑ · - pda set, - pda get, - pda run, - pda list, - pda edit, - pda move, - pda remove + Setting, + Getting, + Running, + Listing, + Editing, + Moving and Copying, + Removing

@@ -214,33 +173,22 @@ Advanced usage of `pda` revolves around [templates](#templates) and [`pda run`]( #### Setting -[`pda set`](#setting) (alias: [`s`](#setting)) creates a key-value pair. Values can come from arguments, stdin, or a file. +

+ + ↑ · + pda set + +

-```bash -Usage: - pda set KEY[@STORE] [VALUE] [flags] - -Aliases: - set, s - -Flags: - -e, --encrypt encrypt the value at rest using age - -f, --file string read value from a file - --force bypass read-only protection - -h, --help help for set - -i, --interactive prompt before overwriting an existing key - --pin pin the key (sorts to top in list) - --readonly mark the key as read-only - --safe do not overwrite if the key already exists - -t, --ttl duration expire the key after the provided duration (e.g. 24h, 30m) -``` - -[`pda set`](#setting) requires a key and a value as inputs. The first argument given will always be used to determine the key. +[`pda set`](#setting) (alias: [`s`](#setting)) creates a key-value pair, and requires a key and a value as inputs. The first argument given will always be used to determine the key (and store). Values can come from arguments, stdin, or a file. ```bash # create a key-value pair pda set name "Alice" +# create a key-value pair in the "Favourites" store +pda set movie@favourites "The Road" + # create a key-value pair with piped input echo "Bob" | pda set name @@ -250,9 +198,6 @@ pda set example < silmarillion.txt # create a pinned key-value pair from a file pda set --pin example --file example.md -# create a key-value pair in the "Favourites" store -pda set movie@favourites "The Road" - # create an encrypted key-value pair, expiring in one day pda set secret "Secret data." --encrypt --ttl 24h ``` @@ -279,24 +224,15 @@ pda set dog "A four-legged mammal that isn't a cat." --force #### Getting -[`pda get`](#getting) (alias: [`g`](#getting)) retrieves a key's value. [Templates](#templates) are evaluated at retrieval time. +

+ + ↑ · + Templates · + pda get + +

-```bash -Usage: - pda get KEY[@STORE] [flags] - -Aliases: - get, g - -Flags: - -b, --base64 view binary data as base64 - --exists exit 0 if the key exists, exit 1 if not (no output) - -h, --help help for get - --no-template directly output template syntax - -c, --run execute the result as a shell command -``` - -[`pda get`] takes one argument: the desired key. The value is output to stdout. +[`pda get`](#getting) (alias: [`g`](#getting)) can be used to retrieve a key's value, and takes one argument: the desired key. The value is output to stdout. [Templates](#templates) are evaluated at retrieval time unless opted-out via the `no-template` flag. ```bash # get the value of a key @@ -347,11 +283,23 @@ Running [`pda get`](#getting) will resolve templates in the stored key at run-ti lew # get a templated key without resolving the template -❯ pda get user +❯ pda get user --no-template {{ env "USER" }} ``` -An alternative to [templates](#templates) is the `run` flag. For detailed information, see [`pda run`](#running), an alias for `pda get --run`. +#### Running + +

+ + ↑ · + pda get --run · + pda run + +

+ +[`pda run`](#running) retrieves a key and executes it as a shell command. It uses the shell set in `$SHELL. If, somehow, this environment variable is unset, it falls back and attempts to use `/bin/sh`. + +Running takes one argument: the key. [`pda run`](#running) and [`pda get --run`](#getting) are functionally equivalent. ```bash # create a key containg a script @@ -360,23 +308,12 @@ An alternative to [templates](#templates) is the `run` flag. For detailed inform # get and run a key using $SHELL ❯ pda get my_script --run Hello, world. + +❯ pda run my_script +Hello, world. ``` -#### Running - -[`pda run`](#running) retrieves a key and executes it as a shell command. It uses the shell set in $SHELL. If, somehow, this environment variable is unset, it falls back and attempts to use `/bin/sh`. Templates are functional when running a key directly. - -```bash -Usage: - pda run KEY[@STORE] [flags] - -Flags: - -b, --base64 view binary data as base64 - -h, --help help for run - --no-template directly output template syntax -``` - -Running takes one argument: the key. +[Templates](#templates) are fully resolved before any shell execution happens. ```bash # create a key containing a script, and a template @@ -393,42 +330,74 @@ Hello, Alice #### Listing -[`pda list`](#listing) (alias: [`ls`](#listing)) shows what you've got stored. The default columns are `meta,size,ttl,store,key,value`. Meta is a 4-char flag string: `(e)ncrypted (w)ritable (t)tl (p)inned`, or a dash for an unset flag. +

+ + ↑ · + pda list · + Filtering + +

+ +[`pda list`](#listing) (alias: [`ls`](#listing)) displays your key-value pairs. The default columns are `meta,size,ttl,store,key,value`. Meta is a 4-char flag string: `(e)ncrypted (w)ritable (t)tl (p)inned`, or a dash for an unset flag. + + -b, --base64 view binary data as base64 + -c, --count print only the count of matching entries + +[`pda list`](#listing) (alias: [`ls`](#listing)) displays stored key-value pairs with [pinned](#pinning) keys first, followed by alphabetical order. Default behaviour is to list [metadata](#metadata), size, [time-to-live](#ttl), store, the key, and value as a table. The order and visibility of every column can be toggled either via `list.default_columns` in the [config](#config) or via one-off flags. + +It accepts one or zero arguments. If no argument is passed, with a default configuration [`pda list`](#listing) will display all keys from all stores, but this behaviour can be toggled to instead display only keys from the default store. If a store name is passed as an argument, only the keys contained within that store will be listed. + +If `list.always_show_all_stores` is toggled off, the behaviour can be enabled on an individual basis by passing `all`. ```bash -❯ pda ls +# list all store contents +❯ pda list Meta Size TTL Store Key Value --w-p 5 - store todo don't forget this ----- 23 - store url https://prod.example.com --w-- 5 - store name Alice +-w-p 5 - todos todo don't forget this +---- 23 - store url https://example.com +-w-- 5 - me name Alice + +# list only the contents of the "todos" store +❯ pda list todos +Meta Size TTL Store Key Value +-w-p 5 - todos todo don't forget this + +# list all store contents, but without Meta, Size, or TTL +❯ pda list --no-ttl --no-header --no-size +Store Key Value +todos todo don't forget this +store url https://example.com + me name Alice + +# count the number of entries for a given query +❯ pda list --count +3 ``` -By default, [`pda list`](#listing) shows entries from every store. Pass a store name to narrow to a single store: +When [listing](#listing), [glob patterns](#filtering) can be used to further filter by `key`, `store`, or `value`. ```bash -pda ls @store +# list all store contents beginning with "https" +pda ls --value "https**" + +# list all store contents beginning with "https" with "db" in the key +pda ls --value "https**" --key "**db**" ``` -Use [`--store`](#filtering) / `-s` to filter stores by [glob pattern](#filtering): +The standard tabular output of [`pda list`](#listing) can be swapped out for tab-separated values, comma-separated values, a markdown table, a HTML table, newline-delimited JSON, or JSON. Newline-delimited JSON is the native storage format of a `pda` store. ```bash -pda ls --store "prod*" +# list all store contents as comma-separated values +❯ pda ls --format csv +Meta,Size,TTL,Store,Key,Value +-w--,5,-,store,name,Alice + +# list all store contents as JSON +❯ pda ls --format json +[{"key":"name","value":"Alice","encoding":"text","store":"store"}] ``` -Filter by key or value with [`--key`](#filtering) / `-k` and [`--value`](#filtering) / `-v`: - -```bash -pda ls --key "db*" --value "**localhost**" -``` - -Columns can be toggled with `--no-X` flags. `--no-X` suppresses a column; `--no-X=false` adds it even if it's not in the default config: - -```bash -# hide the meta and size columns -pda ls --no-meta --no-size -``` - -Long values are truncated to fit the terminal. [`--full`](#listing) / `-f` shows the complete value: +By default, long values are truncated to fit the terminal, but this behaviour can be toggled via the [config](#config) or by passing `full`. The setting is `list.always_show_full_values`. ```bash ❯ pda ls @@ -440,163 +409,95 @@ Key Value note this is a very long value that keeps on going and going ``` -[`--count`](#listing) / `-c` prints only the count of matching entries: - -```bash -❯ pda ls --count -3 - -❯ pda ls --count --key "d*" -1 -``` - -[`--format`](#listing) / `-o` selects the output format. Available formats: `table` (default), `csv`, `tsv`, `json`, `ndjson`, `markdown`, `html`: - -```bash -❯ pda ls --format csv -Meta,Size,TTL,Store,Key,Value --w--,5,-,store,name,Alice - -❯ pda ls --format json -[{"key":"name","value":"Alice","encoding":"text","store":"store"}] -``` - -[`--all`](#listing) / `-a` lists across all stores (default when `list.always_show_all_stores` is true). - -[`--base64`](#listing) / `-b` shows binary data as base64. - -[`--no-header`](#listing) suppresses the header row. - -[Pinned](#pinned) entries sort to the top, preserving alphabetical order within the pinned and unpinned groups. - -

- - See also: - pda help list - -

+As with [`getting`](#getting), non-UTF8 data in lists will be substituted for a summary rather than displaying raw bytes. This can be changed out for a base64 representation by passing `base64`. #### Editing

↑ · - pda edit, - pda set, - pda meta + pda edit

-[`pda edit`](#editing) (alias: [`e`](#editing)) opens a key's value in your `$EDITOR`. If the key doesn't exist, an empty file is opened — saving non-empty content creates it. +[`pda edit`](#editing) (alias: [`e`](#editing)) opens a key's value in your `$EDITOR`. If the key doesn't exist, an empty file is opened, and saving non-empty content creates it. + +When [editing](#editing) a key, [metadata](#metadata)-altering flags can be passed in the same operation. These alterations will only take place if the edit is finalised by saving. ```bash -# edit an existing key +# edit an existing key or create a new one pda edit name -# edit a new key — saving non-empty content creates it -pda edit newkey +# edit a key and pin it +pda edit name --pin + +# edit a key and give it an expiration, and encrypt it +pda edit secret_stuff --ttl 1h --encrypt + +# edit a key and make it readonly +pda edit do_not_change --readonly ``` -Metadata flags can be passed alongside the edit to modify metadata in the same operation: +Most `$EDITOR` will add a trailing newline on saving a file. These are stripped by default, but this behaviour can be toggled via `edit.always_preserve_newline` in the [config](#config) or as a one-off by passing `preserve-newline`. ```bash -pda edit name --ttl 1h --encrypt +# edit a key and preserve the automatic $EDITOR newline +pda edit example --preserve-newline ``` -Trailing newlines added by the editor are stripped by default. [`--preserve-newline`](#editing) keeps them: - -```bash -pda edit name --preserve-newline -``` - -[`--encrypt`](#editing) / `-e` encrypts the value. [`--decrypt`](#editing) / `-d` decrypts it. [`--readonly`](#editing) and [`--writable`](#editing) toggle protection. [`--pin`](#editing) and [`--unpin`](#editing) toggle pinning. [`--ttl`](#editing) sets or clears expiry (e.g. `30m`, `2h`, or `never`). - -Binary values are presented as base64 for editing and decoded back on save. - -[Read-only](#read-only) keys require [`--force`](#editing) to edit. - -

- - See also: - pda help edit - -

+Binary values will be presented as base64 for editing and will be decoded back to raw bytes on save. [Read-only](#read-only) keys require being made writable before they can be edited, or `force` can be explicitly passed. #### Moving & Copying

↑ · - pda move, - pda copy + pda move, + pda copy

-[`pda move`](#moving--copying) (alias: [`mv`](#moving--copying)) moves a key to a new name or store. All metadata is preserved. +To move (or rename) a key, [`pda move`](#moving--copying) (alias: [`mv`](#moving--copying)) can be used. To copy a key, [`pda move --copy`](#moving--copying) (alias: [`cp`](#moving--copying)) can be used. With both of these operations, all [metadata](#metadata) is preserved. ```bash -❯ pda mv name name2 +# rename a key +❯ pda move name name2 + ok renamed name to name2 + +# move a key across stores +❯ pda mv name name@some_other_store + ok renamed name to name@some_other_store + +# copy a key +❯ pda cp name name2 + ok copied name to name2 +``` + +Accidental overwrites have a few ways of being prevented. `safe` exists for moving and copying as it does for all changeful commands, skipping an operation if a destination already exists that would be overwritten. A [read-only](#read-only) key will also prevent being moved or overwritten unless `force` is explicitly passed. + +Additionally, `interactive` being passed or `key.always_prompt_overwrite` being enabled in the [config](#config) will cause a yes-no prompt to be presented if a key is going to be overwritten. Inversely, prompts can always be skipped by passing `yes`. + +```bash +# move a key safely +❯ pda mv name name2 --safe +# info skipped 'name2': already exists + +# move a key interactively +❯ pda mv name name2 --safe + ??? overwrite 'name2'? (y/n) + >>> y + +# move a key and skip all warning prompts +❯ pda mv name name2 --yes ok renamed name to name2 ``` -[`pda copy`](#moving--copying) (alias: [`cp`](#moving--copying)) makes a copy. The source is kept and all metadata is preserved. - -```bash -pda cp name name2 -``` - -[`mv --copy`](#moving--copying) and [`cp`](#moving--copying) are equivalent: - -```bash -pda mv name name2 --copy -``` - -Move or copy across stores: - -```bash -pda mv name@store name@archive -pda cp config@dev config@prod -``` - -[`--safe`](#moving--copying) skips if the destination already exists: - -```bash -pda mv name name2 --safe -# info skipped 'name2': already exists -``` - -[`--yes`](#moving--copying) / `-y` skips all confirmation prompts: - -```bash -pda mv name name2 -y -``` - -[Read-only](#read-only) keys can't be moved or overwritten without [`--force`](#moving--copying): - -```bash -❯ pda mv readonly-key newname -FAIL cannot move 'readonly-key': key is read-only - -pda mv readonly-key newname --force -``` - -[`cp`](#moving--copying) can copy a read-only key freely (since the source isn't modified), and the copy preserves the read-only flag. Overwriting a read-only destination is blocked without [`--force`](#moving--copying). - -

- - See also: - pda help move, - pda help copy - -

- #### Removing

↑ · - pda remove, - --key + pda help remove

@@ -652,13 +553,6 @@ FAIL cannot remove 'protected-key': key is read-only pda rm protected-key --force ``` -

- - See also: - pda help remove - -

- ### Metadata

@@ -700,20 +594,13 @@ FAIL cannot meta 'api-url': key is read-only pda meta api-url --ttl 1h --force ``` -

- - See also: - pda help meta - -

- #### TTL

↑ · - pda set, - pda meta + pda help set, + pda help meta

@@ -756,22 +643,14 @@ pda edit session --ttl 30m [`export`](#import--export) and [`import`](#import--export) preserve the expiry date. Expirations are stored as a timestamp, not a timer — they continue ticking down regardless of whether the key is in an active store or sitting in a backup file. -

- - See also: - pda help set, - pda help meta - -

- #### Encryption

↑ · - pda set, - pda meta, - pda identity + pda help set, + pda help meta, + pda help identity

@@ -832,23 +711,13 @@ FAIL cannot get 'api-key': secret is locked (identity file missing) All encryption operations can be set as default with `key.always_encrypt` in [config](#config), so every [`pda set`](#setting) automatically encrypts. -

- - See also: - pda help set, - pda help meta, - pda help identity - -

- #### Read-Only

↑ · - pda set, - pda meta, - pda edit + pda help set, + pda help meta

@@ -898,23 +767,13 @@ pda meta api-url --ttl 1h --force [`cp`](#moving--copying) can copy a read-only key freely (since the source isn't modified), and the copy preserves the read-only flag. Overwriting a read-only destination is blocked without `--force`. -

- - See also: - pda help set, - pda help meta, - pda help edit - -

- #### Pinned

↑ · - pda set, - pda meta, - pda list + pda help set, + pda help meta

@@ -944,14 +803,6 @@ Meta Key Value -w-- other foo ``` -

- - See also: - pda help set, - pda help meta - -

- ### Stores

@@ -1027,22 +878,13 @@ pda remove-store birthdays pda remove-store birthdays -y ``` -

- - See also: - pda help list-stores, - pda help move-store, - pda help remove-store - -

- #### Import & Export

↑ · - pda export, - pda import + pda help export, + pda help import

@@ -1103,14 +945,6 @@ pda import --drop -f my_backup [`export`](#import--export) encodes [binary data](#binary-data) as base64. [Encryption](#encryption), [read-only](#read-only), [pinned](#pinned) flags, and [TTL](#ttl) are all preserved through export and import. -

- - See also: - pda help export, - pda help import - -

- ### Templates

@@ -1132,8 +966,7 @@ These same functions are also available in `git.default_commit_message` template

↑ · - Templates, - pda get + Templates

@@ -1346,7 +1179,7 @@ https://example.com/api

↑ · - pda get + pda help get

@@ -1362,14 +1195,6 @@ Good morning. {{ if .MORNING }}Good morning.{{ end }} ``` -

- - See also: - pda help get, - pda help set - -

- ### Filtering

@@ -1546,14 +1371,6 @@ pda rm cat --key "{mouse,[cd]og}**" # ... ``` -

- - See also: - pda help list, - pda help remove - -

- ### Binary Data

@@ -1601,14 +1418,6 @@ iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADklEQVQI12... [`pda edit`](#editing) presents binary values as base64 for editing and decodes them back on save. -

- - See also: - pda help set, - pda help get - -

- ### Git

@@ -1627,8 +1436,7 @@ iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADklEQVQI12...

↑ · - Git, - pda sync + pda help init

@@ -1649,19 +1457,12 @@ pda init --clean pda init https://github.com/llywelwyn/my-repository --clean ``` -

- - See also: - pda help init - -

- #### Sync

↑ · - Git + pda help sync

@@ -1679,20 +1480,12 @@ pda sync -m "added production credentials" Running [`pda sync`](#sync) manually will always fetch, commit, and push — or stash and pull if behind — regardless of config. -

- - See also: - pda help sync - -

- #### Auto-Commit & Auto-Push

↑ · - Git, - Config + pda help config

@@ -1725,7 +1518,7 @@ A recommended setup is to enable `git.auto_commit` and run [`pda sync`](#sync) m

↑ · - pda identity + pda help identity

@@ -1749,7 +1542,7 @@ With no flags, [`pda identity`](#identity) shows your public key, identity file

↑ · - pda identity + pda help identity

@@ -1766,8 +1559,7 @@ pda identity --new

↑ · - pda identity, - Encryption + pda help identity

@@ -1795,13 +1587,6 @@ Additional recipients are shown in the default identity display: ok recipient age1ql3z... ``` -

- - See also: - pda help identity - -

- ### Config

@@ -1819,7 +1604,7 @@ Config is stored at `~/.config/pda/config.toml` (Linux/macOS) or `%LOCALAPPDATA%

↑ · - pda config + pda help config

@@ -1854,19 +1639,13 @@ 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. -

- - See also: - pda help config - -

- #### Example config.toml

↑ · - Config + Config, + pda help config

@@ -1991,27 +1770,16 @@ pda run script 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. -

- - See also: - pda help doctor - -

- -### Help & Version +### Version

- ↑ + ↑ · + pda help version

```bash -# help for any command -pda help set -pda help list -pda help config - # display the full version output pda version @@ -2022,6 +1790,647 @@ pda! 2025.52 Christmas release `pda!` uses calendar versioning: `YYYY.WW`. ASCII art can be permanently disabled with `display_ascii_art = false` in [config](#config). +### Help + +

+ + ↑ + +

+ +
+ set · + get · + run · + list · + edit · + move · + copy · + remove · + meta · + identity · + export · + import · + list-stores · + move-store · + remove-store · + init · + sync · + git · + config · + doctor · + version +
+ +#### `pda set` + +

+ + ↑ · + See also: + Setting + +

+ +```text +Set a key to a given value or stdin. Optionally specify a store. + +Pass --encrypt to encrypt the value at rest using age. An identity file +is generated automatically on first use. + +PDA supports parsing Go templates. Actions are delimited with {{ }}. + +For example: + 'Hello, {{ .NAME }}' can be substituted with NAME="John Doe". + 'Hello, {{ env "USER" }}' will fetch the USER env variable. + 'Hello, {{ default "World" .NAME }}' will default to World if NAME is blank. + 'Hello, {{ require .NAME }}' will error if NAME is blank. + '{{ enum .NAME "Alice" "Bob" }}' allows only NAME=Alice or NAME=Bob. + +Usage: + pda set KEY[@STORE] [VALUE] [flags] + +Aliases: + set, s + +Flags: + -e, --encrypt encrypt the value at rest using age + -f, --file string read value from a file + --force bypass read-only protection + -h, --help help for set + -i, --interactive prompt before overwriting an existing key + --pin pin the key (sorts to top in list) + --readonly mark the key as read-only + --safe do not overwrite if the key already exists + -t, --ttl duration expire the key after the provided duration (e.g. 24h, 30m) +``` + +#### `pda get` + +

+ + ↑ · + See also: + Getting, + Templates + +

+ +```text +Get the value of a key. Optionally specify a store. + +{{ .TEMPLATES }} can be filled by passing TEMPLATE=VALUE as an +additional argument after the initial KEY being fetched. + +For example: + pda set greeting 'Hello, {{ .NAME }}!' + pda get greeting NAME=World + +Usage: + pda get KEY[@STORE] [flags] + +Aliases: + get, g + +Flags: + -b, --base64 view binary data as base64 + --exists exit 0 if the key exists, exit 1 if not (no output) + -h, --help help for get + --no-template directly output template syntax + -c, --run execute the result as a shell command +``` + +#### `pda run` + +

+ + ↑ · + See also: + Running, + Templates + +

+ +```text +Get the value of a key and execute it as a shell command. Optionally specify a store. + +{{ .TEMPLATES }} can be filled by passing TEMPLATE=VALUE as an +additional argument after the initial KEY being fetched. + +For example: + pda set greeting 'Hello, {{ .NAME }}!' + pda run greeting NAME=World + +Usage: + pda run KEY[@STORE] [flags] + +Flags: + -b, --base64 view binary data as base64 + -h, --help help for run + --no-template directly output template syntax +``` + +#### `pda list` + +

+ + ↑ · + See also: + Listing, + Filtering + +

+ +```text +List the contents of all stores. + +By default, list shows entries from every store. Pass a store name as a +positional argument to narrow to a single store, or use --store/-s with a +glob pattern to filter by store name. + +Use --key/-k and --value/-v to filter by key or value glob, and --store/-s +to filter by store name. All filters are repeatable and OR'd within the +same flag. + +Usage: + pda list [STORE] [flags] + +Aliases: + list, ls + +Flags: + -a, --all list across all stores + -b, --base64 view binary data as base64 + -c, --count print only the count of matching entries + -o, --format format output format (table|tsv|csv|markdown|html|ndjson|json) + -f, --full show full values without truncation + -h, --help help for list + -k, --key strings filter keys with glob pattern (repeatable) + --no-header suppress the header row + --no-keys suppress the key column + --no-meta suppress the meta column + --no-size suppress the size column + --no-store suppress the store column + --no-ttl suppress the TTL column + --no-values suppress the value column + -s, --store strings filter stores with glob pattern (repeatable) + -v, --value strings filter values with glob pattern (repeatable) +``` + +#### `pda edit` + +

+ + ↑ · + See also: + Editing + +

+ +```text +Open a key's value in $EDITOR. If the key doesn't exist, opens an +empty file — saving non-empty content creates the key. + +Binary values are presented as base64 for editing and decoded back on save. + +Metadata flags (--ttl, --encrypt, --decrypt) can be passed alongside the edit +to modify metadata in the same operation. + +Usage: + pda edit KEY[@STORE] [flags] + +Aliases: + edit, e + +Flags: + -d, --decrypt decrypt the value (store as plaintext) + -e, --encrypt encrypt the value at rest + --force bypass read-only protection + -h, --help help for edit + --pin pin the key (sorts to top in list) + --preserve-newline keep trailing newlines added by the editor + --readonly mark the key as read-only + --ttl string set expiry (e.g. 30m, 2h) or 'never' to clear + --unpin unpin the key + --writable clear the read-only flag +``` + +#### `pda move` + +

+ + ↑ · + See also: + Moving & Copying + +

+ +```text +Move a key + +Usage: + pda move FROM[@STORE] TO[@STORE] [flags] + +Aliases: + move, mv + +Flags: + --copy copy instead of move (keeps source) + --force bypass read-only protection + -h, --help help for move + -i, --interactive prompt before overwriting destination + --safe do not overwrite if the destination already exists + -y, --yes skip all confirmation prompts +``` + +#### `pda copy` + +

+ + ↑ · + See also: + Moving & Copying + +

+ +```text +Make a copy of a key + +Usage: + pda copy FROM[@STORE] TO[@STORE] [flags] + +Aliases: + copy, cp + +Flags: + --force bypass read-only protection + -h, --help help for copy + -i, --interactive prompt before overwriting destination + --safe do not overwrite if the destination already exists + -y, --yes skip all confirmation prompts +``` + +#### `pda remove` + +

+ + ↑ · + See also: + Removing, + Filtering + +

+ +```text +Delete one or more keys + +Usage: + pda remove KEY[@STORE] [KEY[@STORE] ...] [flags] + +Aliases: + remove, rm + +Flags: + --force bypass read-only protection + -h, --help help for remove + -i, --interactive prompt yes/no for each deletion + -k, --key strings delete keys matching glob pattern (repeatable) + -s, --store strings target stores matching glob pattern (repeatable) + -v, --value strings delete entries matching value glob pattern (repeatable) + -y, --yes skip all confirmation prompts +``` + +#### `pda meta` + +

+ + ↑ · + See also: + Metadata, + TTL, + Encryption, + Read-Only, + Pinned + +

+ +```text +View or modify metadata (TTL, encryption, read-only, pinned) for a key +without changing its value. + +With no flags, displays the key's current metadata. Pass flags to modify. + +Usage: + pda meta KEY[@STORE] [flags] + +Flags: + -d, --decrypt decrypt the value (store as plaintext) + -e, --encrypt encrypt the value at rest + --force bypass read-only protection for metadata changes + -h, --help help for meta + --pin pin the key (sorts to top in list) + --readonly mark the key as read-only + --ttl string set expiry (e.g. 30m, 2h) or 'never' to clear + --unpin unpin the key + --writable clear the read-only flag +``` + +#### `pda identity` + +

+ + ↑ · + See also: + Identity, + Encryption + +

+ +```text +Show or create the age encryption identity + +Usage: + pda identity [flags] + +Aliases: + identity, id + +Flags: + --add-recipient string add an age public key as an additional encryption recipient + -h, --help help for identity + --new generate a new identity (errors if one already exists) + --path print only the identity file path + --remove-recipient string remove an age public key from the recipient list +``` + +#### `pda export` + +

+ + ↑ · + See also: + Import & Export + +

+ +```text +Export store as NDJSON (alias for list --format ndjson) + +Usage: + pda export [STORE] [flags] + +Flags: + -h, --help help for export + -k, --key strings filter keys with glob pattern (repeatable) + -s, --store strings filter stores with glob pattern (repeatable) + -v, --value strings filter values with glob pattern (repeatable) +``` + +#### `pda import` + +

+ + ↑ · + See also: + Import & Export + +

+ +```text +Restore key/value pairs from an NDJSON dump + +Usage: + pda import [STORE] [flags] + +Flags: + --drop drop existing entries before restoring (full replace) + -f, --file string path to an NDJSON dump (defaults to stdin) + -h, --help help for import + -i, --interactive prompt before overwriting existing keys + -k, --key strings restore keys matching glob pattern (repeatable) + -s, --store strings restore entries from stores matching glob pattern (repeatable) +``` + +#### `pda list-stores` + +

+ + ↑ · + See also: + Stores + +

+ +```text +List all stores + +Usage: + pda list-stores [flags] + +Aliases: + list-stores, lss + +Flags: + -h, --help help for list-stores + --no-header suppress the header row + --short only print store names +``` + +#### `pda move-store` + +

+ + ↑ · + See also: + Stores + +

+ +```text +Rename a store + +Usage: + pda move-store FROM TO [flags] + +Aliases: + move-store, mvs + +Flags: + --copy copy instead of move (keeps source) + -h, --help help for move-store + -i, --interactive prompt before overwriting destination + --safe do not overwrite if the destination store already exists + -y, --yes skip all confirmation prompts +``` + +#### `pda remove-store` + +

+ + ↑ · + See also: + Stores + +

+ +```text +Delete a store + +Usage: + pda remove-store STORE [flags] + +Aliases: + remove-store, rms + +Flags: + -h, --help help for remove-store + -i, --interactive prompt yes/no for each deletion + -y, --yes skip all confirmation prompts +``` + +#### `pda init` + +

+ + ↑ · + See also: + Init, + Git + +

+ +```text +Initialise pda! version control + +Usage: + pda init [remote-url] [flags] + +Flags: + --clean remove .git from stores directory before initialising + -h, --help help for init +``` + +#### `pda sync` + +

+ + ↑ · + See also: + Sync, + Git + +

+ +```text +Manually sync your stores with Git + +Usage: + pda sync [flags] + +Flags: + -h, --help help for sync + -m, --message string custom commit message (defaults to timestamp) +``` + +#### `pda git` + +

+ + ↑ · + See also: + Git + +

+ +```text +Run any arbitrary command. Use with caution. + +The Git repository lives directly in the data directory +("PDA_DATA"). Store files (*.ndjson) are tracked by Git as-is. + +If you manually modify files without using the built-in +commands, you may desync your repository. + +Generally prefer "pda sync". + +Usage: + pda git [args...] [flags] + +Flags: + -h, --help help for git +``` + +#### `pda config` + +

+ + ↑ · + See also: + Config + +

+ +```text +View and modify configuration + +Usage: + pda config [command] + +Available Commands: + edit Open config file in $EDITOR + get Print a configuration value + init Generate default config file + list List all configuration values + path Print config file path + set Set a configuration value + +Flags: + -h, --help help for config + +Use "pda config [command] --help" for more information about a command. +``` + +#### `pda doctor` + +

+ + ↑ · + See also: + Doctor + +

+ +```text +Check environment health + +Usage: + pda doctor [flags] + +Flags: + -h, --help help for doctor +``` + +#### `pda version` + +

+ + ↑ · + See also: + Version + +

+ +```text +Display pda! version + +Usage: + pda version [flags] + +Flags: + -h, --help help for version + --short print only the version string +``` + ### License