SECRET-TOOL(1)

💖 SECRET-TOOL 💖

okay bestie, gather round, because this is the manual page for secret-tool from the User Commands girlies. she stores passwords. she retrieves passwords. she is, frankly, iconic. 🎀

---

✨ NAME ✨

secret-tool — Store and retrieve passwords 🗝️

---

🌸 SYNOPSIS 🌸

secret-tool store [--collection='collection']--label='Label' {attribute} {value} ...

secret-tool lookup {attribute} {value} ...

secret-tool clear {attribute} {value} ...

secret-tool search [--all]{attribute} {value} ...

secret-tool lock [--collection='collection']

---

🦋 DESCRIPTION 🦋

so secret-tool is a command line tool that can be used to store and retrieve passwords. no cap.

every password lives inside an item. items are uniquely identified by a set of attribute keys and values. so when you're storing a password you must specify unique pairs of attributes names and values, and when you're looking up a password you provide the same attribute name and value pairs. matchy matchy, that's the vibe. 💅

---

🫶 STORE 🫶

to store a password, run secret-tool with the store argument. you also must specify a label for the password with the --label argument. this label will be displayed in the password manager. it's giving name tag energy. 🏷️

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. no new item for you bestie, she's editing.

if invoked from a terminal or tty, then the password to store will be prompted for and only one line will be accepted. one (1) line. that's it. 😭

a password to store can also be piped in via stdin. the password will be the contents of stdin until EOF. and listen — if you provide a newline via stdin it will be stored as part of the password. so don't be sloppy with your echo. 🙈

passwords are stored in the default collection (usually the "login" collection). you can specify a different collection with the --collection argument. main character collection energy, your choice honestly. ✨

---

🔍 LOOKUP 🔍

to lookup a password run secret-tool with the lookup argument. specify the same same attribute names and value pairs that you passed when storing the password. (yes the original says "same same", and honestly? she ate that. 😌)

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.

when printing the password to a terminal or tty, an extra newline will be added after the password. just a lil bonus line break, as a treat. 🎀

---

💀 CLEAR 💀

to remove a password run secret-tool with the clear argument. specify the same attribute name and value pairs that you passed when storing the password.

all unlocked items that match the attributes will be removed. gone. deleted. no trace. this is the villain arc. 🫣

---

⭐ SEARCH ⭐

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:

• --all — 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.
• --unlock — unlock items that are locked and then print out their details. without this option, locked items are skipped. 🙅

---

🔒 LOCK 🔒

to lock collections, run secret-tool with the lock argument. by default, it locks all collections. if you want to lock a single collection, you can specify it with the --collection argument. girl is out here doing security. 👑

---

🌈 EXIT STATUS 🌈

on success 0 is returned, a non-zero failure code otherwise. simple as that, periodt. 💯

---

🧚 EXAMPLES 🧚

Example 1. Storing, retrieving, and clearing a password

$ secret-tool store --label='My password' key1 value1 key2 value2
Password: hunter2

$ secret-tool lookup key1 value1 key2 value2
hunter2

$ secret-tool clear key1 value1 key2 value2

look at her go. store, lookup, clear. the whole trilogy. 🎬

---

🍓 BUGS 🍓

the bug tracker can be reached by visiting the website https://gitlab.gnome.org/GNOME/libsecret/issues. 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. so like… update first bestie, i'm begging. 😭

---

that's the whole page!! sourced from the XDG girlies, version SECRET-TOOL(1), and she's been serving this exact energy since forever. mwah. 💖✨🎀🦋🌸💅🫶👑