gopass/docs/commands/list.md

list command

The list command is used to list all the entries in the password store or at a given prefix.

Synopsis

$ gopass ls
$ gopass ls path/to/entries

• List all the entries in the password store including the one in mounted stores: gopass list
• List all the entries in a given folder showing their relative path from the root: gopass list path/to/entries

Note: list will not change anything, nor encrypt or decrypt anything.

Flags

Flag	Aliases	Description
--limit value	-l value	Max tree depth (default: -1)
--flat	-f	Print a flat list of secrets (default: false)
--folders	-d	Print a flat list of folders (default: false)
--strip-prefix	-s	Strip prefix from filtered entries (default: false)

The --flat and --folders flags provide a plaintext list of the entries located at the given prefix (default prefix being the root /). They are notably used to produce the completion results. The --flat one will list all entries, one per line, using its full path. The --folders one will display all the folders, one per line, recursively per level. For instance an entry folder/sub/entry would cause it to list both:

$ gopass list --folders
folder
folder/sub

whereas gopass list --flat would have just displayed one line: folder/sub/entry.

The --strip-prefix flag is meant to be used along with --flat or --folders. It will list the relative path from the current prefix, removing the said prefix, instead of listing the relative paths from the root. For instance on entry folder/sub/entry, running gopass ls -f -s folder would display only sub/entry instead of folder/sub/entry.

The --limit flag starts counting its depth from the root store, which means that a depth of 0 only lists the items in the root gopass store:

$ gopass list -l 0
gopass
├── bar
├── foo
└── test (/home/user/.local/share/gopass/stores/substore1)

A value of 1 would list all the items in the root, plus their sub-items but no more:

$ gopass list -l 1
gopass
├── bar
│   └── bar
├── foo
│   ├── bar
│   └── foo
└── test (/home/user/.local/share/gopass/stores/substore1)
    └── foo

A negative value lists all the items without any depth limit.

$ gopass list -l -1
gopass
├── bar
│   └── bar
├── foo
│   ├── bar
│   │   ├── bar
│   │   │   └── bar
│   │   └── baz
│   └── foo
└── test (/home/user/.local/share/gopass/stores/substore1)
    └── foo

The flags can be used together: gopass -l 1 -d will list only the folders up to a depth of 1:

$ gopass list -l 1 -d
bar
foo
foo/bar
test
test/foo

Shadowing

It is possible to have a path that is both an entry and a folder. In that case the list command will always display the folder and the entry is "shadowed", but it can still be accessed using gopass show path/to/it, while the content of the folder can be listed using gopass list path/to/it.

It should also be noted that the mount command can completely "shadow" an entry in a password store, simply by having the same name and this entry and its subentries will not be visible using ls anymore until the substore is unmounted. The entries shadowed by a mount will not show up in a search and cannot be accessed at all without unmounting.

For instance in our example above, maybe there is an entry test/zaz in the root store, but since the substore is mounted as test/, it only displays the content of the substore. Unmounting it reveals its shadowed entries:

$ gopass list test
test 
└── foo
$ gopass mounts rm test
$ gopass list test
test 
└── zaz