libsecret: add missing man page

1 files changed, 133 insertions, 0 deletions

diff --git a/libsecret/secret-tool.1 b/libsecret/secret-tool.1
new file mode 100644
index 000000000..c5c6a4bb9
--- /dev/null
+++ b/libsecret/secret-tool.1
@@ -0,0 +1,133 @@
+'\" t
+.\"     Title: secret-tool
+.\"    Author: Stef Walter <stefw@gnome.org>
+.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
+.\"      Date: 04/04/2013
+.\"    Manual: User Commands
+.\"    Source: XDG
+.\"  Language: English
+.\"
+.TH "SECRET\-TOOL" "1" "" "XDG" "User Commands"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+secret-tool \- Store and retrieve passwords
+.SH "SYNOPSIS"
+.HP \w'\fBsecret\-tool\ store\ \fR\fB\-\-label=\*(AqLabel\*(Aq\fR\fB\ \fR\fB{attribute}\fR\fB\ \fR\fB{value}\fR\fB\ \&.\&.\&.\fR\ 'u
+\fBsecret\-tool store \fR\fB\-\-label=\*(AqLabel\*(Aq\fR\fB \fR\fB{attribute}\fR\fB \fR\fB{value}\fR\fB \&.\&.\&.\fR
+.HP \w'\fBsecret\-tool\ lookup\ \fR\fB{attribute}\fR\fB\ \fR\fB{value}\fR\fB\ \&.\&.\&.\fR\ 'u
+\fBsecret\-tool lookup \fR\fB{attribute}\fR\fB \fR\fB{value}\fR\fB \&.\&.\&.\fR
+.HP \w'\fBsecret\-tool\ clear\ \fR\fB{attribute}\fR\fB\ \fR\fB{value}\fR\fB\ \&.\&.\&.\fR\ 'u
+\fBsecret\-tool clear \fR\fB{attribute}\fR\fB \fR\fB{value}\fR\fB \&.\&.\&.\fR
+.HP \w'\fBsecret\-tool\ search\ \fR\fB[\-\-all]\fR\fB{attribute}\fR\fB\ \fR\fB{value}\fR\fB\ \&.\&.\&.\fR\ 'u
+\fBsecret\-tool search \fR\fB[\-\-all]\fR\fB{attribute}\fR\fB \fR\fB{value}\fR\fB \&.\&.\&.\fR
+.SH "DESCRIPTION"
+.PP
+\fBsecret\-tool\fR
+is a command line tool that can be used to store and retrieve passwords\&.
+.PP
+Each password is stored in an item\&. Items are uniquely identified by a set of attribute keys and values\&. When storing a password you must specify unique pairs of attributes names and values, and when looking up a password you provide the same attribute name and value pairs\&.
+.SH "STORE"
+.PP
+To store a password run
+\fBsecret\-tool\fR
+with the
+store
+argument\&. You must also specify a label for the passward with the
+\-\-label
+argument\&. This label will be displayed in the password manager\&.
+.PP
+Make sure to pass a unique set of attributes names and values when storing a password\&. If the attributes match an already existing item, it will be updated instead of creating a new item\&.
+.PP
+If invoked from a terminal or tty, then the password to store will be prompted for and only one line will be accepted\&.
+.PP
+A password to store can also be piped in via stdin\&. The password will be the contents of stdin until EOF\&. If you provide a newline via stdin it will be stored as part of the password\&.
+.SH "LOOKUP"
+.PP
+To lookup a password run
+\fBsecret\-tool\fR
+with the
+lookup
+argument\&. Specify the same same attribute names and value pairs that you passed when storing the password\&.
+.PP
+If multiple items match the attribute provided, then the first password that is already unlocked will be returned\&. If necessary an item will be unlocked\&.
+.PP
+When printing the password to a terminal or tty, an extra newline will be added after the password\&.
+.SH "CLEAR"
+.PP
+To remove a password run
+\fBsecret\-tool\fR
+with the
+clear
+argument\&. Specify the same attirbute name and value pairs that you passed when storing the password\&.
+.PP
+All unlocked items that match the attributes will be removed\&.
+.SH "SEARCH"
+.PP
+This command searches for and prints details on matching items in secret service\&. Specify the same attribute and value pairs that you passed in when storing the password\&. You can use the following options:
+.PP
+\fB\-\-all\fR
+.RS 4
+Return all matching results, rather than just the one of the matches\&. Without this option, the first unlocked match returned from the service will be printed\&.
+.RE
+.PP
+\fB\-\-unlock\fR
+.RS 4
+Unlock items that are locked and then print out their details\&. Without this option, locked items are skipped\&.
+.RE
+.SH "EXIT STATUS"
+.PP
+On success 0 is returned, a non\-zero failure code otherwise\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Storing, retrieving, and clearing a password\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ secret\-tool store \-\-label=\*(AqMy password\*(Aq key1 value1 key2 value2
+Password: My password
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ secret\-tool lookup key1 value1 key2 value2
+My password
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ secret\-tool clear key1 value1 key2 value2
+.fi
+.if n \{\
+.RE
+.\}
+