keep/README.org

Keep

• Introduction
• Installation
• Usage
  • Saving an Item
  • Getting an Item
  • Listing Items
  • Updating an Item
  • Deleting an Item
  • Showing Status
  • Diffing Items
  • Getting Information About an Item
• Configuration
• Examples
  • Saving an Item with Compression and Digest
  • Getting an Item with Human-Readable Sizes
  • Listing Items with Custom Format
  • Updating an Item with New Tags and Metadata
  • Deleting an Item by Tag
  • Showing Status with Verbose Output
  • Diffing Items with IDs
  • Getting Information About an Item with Metadata
• License
• Contributing
• Contact

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:

cargo build --release
cargo install --path .

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:

echo "Hello, world!" | keep --save example --meta key=value

Getting an Item

To retrieve an item by its ID or by matching tags and metadata, you can use the --get option:

keep --get 1
keep --get example
keep --get --meta key=value
keep 1
keep example

Listing Items

To list all items or filter them by tags and metadata, you can use the --list option:

keep --list
keep --list example
keep --list --meta key=value

Updating an Item

To update an item's tags and metadata, you can use the --update option:

keep --update 1 newtag --meta key=newvalue

Deleting an Item

To delete an item by its ID or by matching tags, you can use the --delete option:

keep --delete 1
keep --delete example

Showing Status

To show the status of directories and supported compression algorithms, you can use the --status option:

keep --status

Diffing Items

To show a diff between two items by ID, you can use the --diff option:

keep --diff 1 2

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:

keep --info 1
keep --info example
keep --info --meta key=value

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

echo "Hello, world!" | keep --save example --meta key=value --compression gzip --digest sha256

Getting an Item with Human-Readable Sizes

keep --get 1 --human-readable

Listing Items with Custom Format

keep --list --list-format "id,time,size,tags,meta:hostname"

Updating an Item with New Tags and Metadata

keep --update 1 newtag --meta key=newvalue

Deleting an Item by Tag

keep --delete example

Showing Status with Verbose Output

keep --status --verbose

Diffing Items with IDs

keep --diff 1 2

Getting Information About an Item with Metadata

keep --info 1

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.