From 16d8bd6cf6320e8a9b529ea7ec9a65a5a4c97ba7 Mon Sep 17 00:00:00 2001
From: Ross Andrews <ross.andrews@gmail.com>
Date: Fri, 15 May 2026 00:58:22 -0500
Subject: [PATCH] man page

---
 man/drawer.1 | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 man/drawer.1

diff --git a/man/drawer.1 b/man/drawer.1
new file mode 100644
index 0000000..c22449b
--- /dev/null
+++ b/man/drawer.1
@@ -0,0 +1,155 @@
+.TH DRAWER 1 "2026-05-15" "drawer" "User Commands"
+.SH NAME
+drawer \- encrypt and decrypt project directories
+.SH SYNOPSIS
+.B drawer open
+.RB [ \-i
+.IR key ]
+.RB [ \-f ]
+.I drawer_file
+.RI [ target_path ]
+.br
+.B drawer close
+.RB [ \-i
+.IR key ]
+.I target_path
+.RI [ drawer_file ]
+.br
+.B drawer info
+.RB [ \-i
+.IR key ]
+.I drawer_file
+.br
+.B drawer key
+.I filename
+.SH DESCRIPTION
+.B drawer
+stores project directories as encrypted archive files called drawers.
+Each drawer file is a gzip-compressed tar archive encrypted with an
+SSH public key using the age encryption format.
+Only the corresponding SSH private key can open it.
+.PP
+Drawer files must use the
+.B .drawer
+extension.
+The SSH key to use is specified with
+.B \-i
+or the environment variable
+.BR DRAWER_KEY .
+.SH SUBCOMMANDS
+.SS open
+Decrypt
+.I drawer_file
+and expand its contents into
+.IR target_path .
+.PP
+If
+.I target_path
+is omitted it is inferred: a single-file drawer extracts to a file
+named after the stored entry; a directory drawer extracts to a
+directory named after the drawer file stem.
+The inferred path is printed to standard output.
+.PP
+Fails if
+.I target_path
+already exists and is non-empty unless
+.B \-f
+is given.
+.TP
+.BI \-i " key"
+Path to the SSH private key. Overrides
+.BR DRAWER_KEY .
+.TP
+.B \-f
+Force extraction even if
+.I target_path
+is non-empty.
+.SS close
+Compress and encrypt
+.I target_path
+and write the result to
+.IR drawer_file .
+.I target_path
+may be a file or a directory.
+.PP
+If
+.I drawer_file
+is omitted it defaults to
+.I target_path
+with a
+.B .drawer
+extension appended.
+The inferred drawer file path is printed to standard output.
+.PP
+Fails if
+.I drawer_file
+would be written inside
+.IR target_path .
+.TP
+.BI \-i " key"
+Path to the SSH private key. Overrides
+.BR DRAWER_KEY .
+.SS info
+Decrypt
+.I drawer_file
+and print a one-line summary: whether it contains a single file or a
+directory, and the size or file count.
+.TP
+.BI \-i " key"
+Path to the SSH private key. Overrides
+.BR DRAWER_KEY .
+.SS key
+Generate a new Ed25519 SSH key and write it to
+.IR filename .
+Fails if
+.I filename
+already exists or its parent directory does not exist.
+.SH ENVIRONMENT
+.TP
+.B DRAWER_KEY
+Path to the SSH private key used for encryption and decryption.
+Overridden by
+.BR \-i .
+.SH EXAMPLES
+Generate a new key:
+.PP
+.RS
+.B drawer key ~/.keys/mykey
+.RE
+.PP
+Close a directory into a drawer (drawer file inferred):
+.PP
+.RS
+.B drawer close ~/projects/myproject
+.RE
+.PP
+Close with an explicit drawer file path:
+.PP
+.RS
+.B drawer close ~/projects/myproject ~/archive/myproject.drawer
+.RE
+.PP
+Open a drawer (target directory inferred):
+.PP
+.RS
+.B drawer open ~/archive/myproject.drawer
+.RE
+.PP
+Open a drawer into an explicit directory:
+.PP
+.RS
+.B drawer open -i ~/.keys/mykey ~/archive/myproject.drawer ~/projects/myproject
+.RE
+.PP
+Show what is inside a drawer:
+.PP
+.RS
+.B drawer info -i ~/.keys/mykey ~/archive/myproject.drawer
+.RE
+.SH EXIT STATUS
+.B drawer
+exits 0 on success and 1 on any error, printing a diagnostic message
+to standard error.
+.SH SEE ALSO
+.BR ssh-keygen (1),
+.BR age (1)