#+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.