'\" t
.\"     Title: secret-tool
.\"    Author: Stef Walter <stefw@gnome.org>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/31/2022
.\"    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 password 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 attribute 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: hunter2
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ secret\-tool lookup key1 value1 key2 value2
hunter2
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ secret\-tool clear key1 value1 key2 value2
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.PP
The bug tracker can be reached by visiting the website
\m[blue]\fBhttps://gitlab\&.gnome\&.org/GNOME/libsecret/issues\fR\m[]\&. Before sending a bug report, please verify that you have the latest version of secret\-tool\&. Many bugs (major and minor) are fixed at each release, and if yours is out of date, the problem may already have been solved\&.