From 9af7af4687b90a2ceed71af481734d98ed1e3d4a Mon Sep 17 00:00:00 2001
From: "Andrew Phillips (aider)" <andrew.phillips2@canada.ca>
Date: Fri, 16 May 2025 14:32:24 -0300
Subject: [PATCH] docs: add README.org for Keep command-line utility

---
 README.org | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 README.org

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..2394ab0
--- /dev/null
+++ b/README.org
@@ -0,0 +1,141 @@
+#+TITLE: Keep
+#+AUTHOR: Andrew Phillips
+#+EMAIL: andrew@gt0.ca
+#+DATE: 2024-01-01
+
+* Introduction
+Keep is a command-line utility designed to manage temporary files created on the command line. Instead of redirecting output to a temporary file (e.g., *command > ~/whatever.tmp*), you can use *keep* to handle the temporary files for you (e.g., *command | keep*).
+
+* Installation
+To install Keep, you need to have Rust and Cargo installed on your system. You can then build and install Keep using the following commands:
+
+#+BEGIN_SRC sh
+cargo build --release
+cargo install --path .
+#+END_SRC
+
+* Usage
+Keep provides several subcommands to manage temporary files. Below are some examples of how to use Keep.
+
+** Saving an Item
+To save an item with tags and metadata, you can use the *--save* option:
+
+#+BEGIN_SRC sh
+echo "Hello, world!" | keep --save --tag example --meta key=value
+#+END_SRC
+
+** Getting an Item
+To retrieve an item by its ID or by matching tags and metadata, you can use the *--get* option:
+
+#+BEGIN_SRC sh
+keep --get 1
+keep --get --tag example
+keep --get --meta key=value
+#+END_SRC
+
+** Listing Items
+To list all items or filter them by tags and metadata, you can use the *--list* option:
+
+#+BEGIN_SRC sh
+keep --list
+keep --list --tag example
+keep --list --meta key=value
+#+END_SRC
+
+** Updating an Item
+To update an item's tags and metadata, you can use the *--update* option:
+
+#+BEGIN_SRC sh
+keep --update 1 --tag newtag --meta key=newvalue
+#+END_SRC
+
+** Deleting an Item
+To delete an item by its ID or by matching tags, you can use the *--delete* option:
+
+#+BEGIN_SRC sh
+keep --delete 1
+keep --delete --tag example
+#+END_SRC
+
+** Showing Status
+To show the status of directories and supported compression algorithms, you can use the *--status* option:
+
+#+BEGIN_SRC sh
+keep --status
+#+END_SRC
+
+** Diffing Items
+To show a diff between two items by ID, you can use the *--diff* option:
+
+#+BEGIN_SRC sh
+keep --diff 1 2
+#+END_SRC
+
+** Getting Information About an Item
+To get detailed information about an item by its ID or by matching tags and metadata, you can use the *--info* option:
+
+#+BEGIN_SRC sh
+keep --info 1
+keep --info --tag example
+keep --info --meta key=value
+#+END_SRC
+
+* Configuration
+Keep can be configured using environment variables and command-line options. The following environment variables are supported:
+
+- *KEEP_DIR*: Specify the directory to use for storage.
+- *KEEP_LIST_FORMAT*: A comma-separated list of columns to display with *--list*.
+- *KEEP_DIGEST*: Digest algorithm to use when saving items.
+- *KEEP_COMPRESSION*: Compression algorithm to use when saving items.
+
+* Examples
+Here are some examples of how to use Keep with different options:
+
+** Saving an Item with Compression and Digest
+#+BEGIN_SRC sh
+echo "Hello, world!" | keep --save --tag example --meta key=value --compression gzip --digest sha256
+#+END_SRC
+
+** Getting an Item with Human-Readable Sizes
+#+BEGIN_SRC sh
+keep --get 1 --human-readable
+#+END_SRC
+
+** Listing Items with Custom Format
+#+BEGIN_SRC sh
+keep --list --list-format "id,time,size,tags,meta:hostname"
+#+END_SRC
+
+** Updating an Item with New Tags and Metadata
+#+BEGIN_SRC sh
+keep --update 1 --tag newtag --meta key=newvalue
+#+END_SRC
+
+** Deleting an Item by Tag
+#+BEGIN_SRC sh
+keep --delete --tag example
+#+END_SRC
+
+** Showing Status with Verbose Output
+#+BEGIN_SRC sh
+keep --status --verbose
+#+END_SRC
+
+** Diffing Items with IDs
+#+BEGIN_SRC sh
+keep --diff 1 2
+#+END_SRC
+
+** Getting Information About an Item with Metadata
+#+BEGIN_SRC sh
+keep --info 1 --meta key=value
+#+END_SRC
+
+* License
+Keep is licensed under the MIT License. See the LICENSE file for more details.
+
+* Contributing
+Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.
+
+* Contact
+For more information, please contact Andrew Phillips at andrew@gt0.ca.