Debian Codegraph @

docs/man/secret-tool.xml

raw
1 <?xml version='1.0'?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <refentry id="secret-tool">
6
7 <refentryinfo>
8 <title>secret-tool</title>
9 <productname>XDG</productname>
10
11 <authorgroup>
12 <author>
13 <contrib>Maintainer</contrib>
14 <firstname>Stef</firstname>
15 <surname>Walter</surname>
16 <email>[email protected]</email>
17 </author>
18 </authorgroup>
19 </refentryinfo>
20
21 <refmeta>
22 <refentrytitle>secret-tool</refentrytitle>
23 <manvolnum>1</manvolnum>
24 <refmiscinfo class="manual">User Commands</refmiscinfo>
25 </refmeta>
26
27 <refnamediv>
28 <refname>secret-tool</refname>
29 <refpurpose>Store and retrieve passwords</refpurpose>
30 </refnamediv>
31
32 <refsynopsisdiv>
33 <cmdsynopsis>
34 <command>secret-tool store <arg choice="plain">--label='Label'</arg> <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
35 </cmdsynopsis>
36 <cmdsynopsis>
37 <command>secret-tool lookup <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
38 </cmdsynopsis>
39 <cmdsynopsis>
40 <command>secret-tool clear <arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
41 </cmdsynopsis>
42 <cmdsynopsis>
43 <command>secret-tool search <arg choice="opt">--all</arg><arg choice="req">attribute</arg> <arg choice="req">value</arg> ...</command>
44 </cmdsynopsis>
45 </refsynopsisdiv>
46
47 <refsect1>
48 <title>Description</title>
49
50 <para><command>secret-tool</command> is a command line tool that
51 can be used to store and retrieve passwords.</para>
52
53 <para>Each password is stored in an item. Items are uniquely
54 identified by a set of attribute keys and values. When storing
55 a password you must specify unique pairs of attributes names
56 and values, and when looking up a password you provide the same
57 attribute name and value pairs.</para>
58
59 </refsect1>
60
61 <refsect1>
62 <title>Store</title>
63
64 <para>To store a password run <command>secret-tool</command>
65 with the <arg choice="plain">store</arg> argument. You must
66 also specify a label for the password with the
67 <arg choice="plain">--label</arg> argument. This label will be
68 displayed in the password manager.</para>
69
70 <para>Make sure to pass a unique set of attributes names and
71 values when storing a password. If the attributes match an
72 already existing item, it will be updated instead of creating
73 a new item.</para>
74
75 <para>If invoked from a terminal or tty, then the password to store
76 will be prompted for and only one line will be accepted.</para>
77
78 <para>A password to store can also be piped in via stdin. The
79 password will be the contents of stdin until EOF. If you provide
80 a newline via stdin it will be stored as part of the password.</para>
81 </refsect1>
82
83 <refsect1>
84 <title>Lookup</title>
85
86 <para>To lookup a password run <command>secret-tool</command>
87 with the <arg choice="plain">lookup</arg> argument. Specify the
88 same same attribute names and value pairs that you passed when
89 storing the password.</para>
90
91 <para>If multiple items match the attribute provided, then the
92 first password that is already unlocked will be returned. If
93 necessary an item will be unlocked.</para>
94
95 <para>When printing the password to a terminal or tty, an extra
96 newline will be added after the password.</para>
97 </refsect1>
98
99 <refsect1>
100 <title>Clear</title>
101
102 <para>To remove a password run <command>secret-tool</command>
103 with the <arg choice="plain">clear</arg> argument. Specify the
104 same attribute name and value pairs that you passed when
105 storing the password.</para>
106
107 <para>All unlocked items that match the attributes will be
108 removed.</para>
109 </refsect1>
110
111 <refsect1>
112 <title>Search</title>
113
114 <para>This command searches for and prints details on matching
115 items in secret service. Specify the same attribute and value
116 pairs that you passed in when storing the password. You can use the
117 following options:</para>
118
119 <variablelist>
120 <varlistentry>
121 <term><option>--all</option></term>
122 <listitem><para>Return all matching results, rather than
123 just the one of the matches. Without this option, the
124 first unlocked match returned from the service will
125 be printed.</para></listitem>
126 </varlistentry>
127 <varlistentry>
128 <term><option>--unlock</option></term>
129 <listitem><para>Unlock items that are locked and then
130 print out their details. Without this option, locked items
131 are skipped.</para></listitem>
132 </varlistentry>
133 </variablelist>
134 </refsect1>
135
136 <refsect1>
137 <title>Exit status</title>
138
139 <para>On success 0 is returned, a non-zero failure code otherwise.</para>
140 </refsect1>
141
142 <refsect1>
143 <title>Examples</title>
144 <example>
145 <title>Storing, retrieving, and clearing a password</title>
146 <programlisting>
147 $ secret-tool store --label='My password' key1 value1 key2 value2
148 Password: hunter2
149 </programlisting>
150 <programlisting>
151 $ secret-tool lookup key1 value1 key2 value2
152 hunter2
153 </programlisting>
154 <programlisting>
155 $ secret-tool clear key1 value1 key2 value2
156 </programlisting>
157 </example>
158 </refsect1>
159
160 <refsect1>
161 <title>Bugs</title>
162
163 <para>The bug tracker can be reached by visiting the
164 website <ulink url="https://gitlab.gnome.org/GNOME/libsecret/issues">https://gitlab.gnome.org/GNOME/libsecret/issues</ulink>.
165 Before sending a bug report, please verify that you have
166 the latest version of secret-tool. Many bugs (major and
167 minor) are fixed at each release, and if yours is out of
168 date, the problem may already have been solved.</para>
169 </refsect1>
170
171 </refentry>