gocatcli

gocatcli

gocatcli is a catalog tool for your offline data

Did you ever wanted to find back that specific file that should be on one of your backup DVDs or one of your external hard drives? You usually go through all of them hoping to find the right one on the first try? gocatcli indexes external media in a catalog file and allows to quickly find specific files or even navigate in the catalog as if it was a mounted drive.

Features:

• Index filesystem/directories in a catalog
• Multiple ways to explore the catalog (ls, find, tree, tui browser, fzf, etc)
• Use wildcards to search for files
• archives support (index their content as well)
• Save catalog for easy versioning with git
• Support catalog in json or toml
• Multiple outputs (csv, etc)
• Mount file using fuse
• Re-create locally the catalog hierarchy
• ... and much more

Quick start:

gocatcli index <some-path>
gocatcli nav
gocatcli tree

Why gocatcli?

gocatcli gives the ability to navigate, explore and find your files that are stored on external media (DVDs, hard drives, USB sticks, etc) when those are not connected. gocatcli can just as easily index any arbitrary directories.

---

Table of Contents

• Installation

• Usage

  • Index data
  • Reindex and update
  • Index archives
  • Navigate with ls
  • File browser
  • Tree view
  • Find files
  • Find files with fzf
  • Disk usage
  • Create hierarchy locally
  • Mount the catalog filesystem
  • Edit storage
  • Output formats
  • Convert catcli catalog

• From catcli to gocatcli

• Contribution

• Thank you

Installation

Pick a binary in the releases

Or if you have go installed, you can installed it directly

$ go install -v github.com/deadc0de6/gocatcli/cmd/gocatcli@latest
$ gocatcli --help

Or if you want to compile it yourself

$ go mod tidy
$ make
$ ./bin/gocatcli --help

It's also available on Nix (unstable channel only, for now). If you have Nix installed, one way you can try it out is like this:

nix-shell -p gocatcli

Usage

The primary use of gocatcli is to index your data (external hardrives, etc) into a catalog and then have the ability to browse their content (as well as search, navigate, etc) while these are stored away.

$ gocatcli --help
$ gocatcli index --help
$ gocatcli ls --help
$ gocatcli tree --help
$ gocatcli nav --help
...

gocatcli indexes files in a tree-like structure. There are different types of entry in a catalog:

• top node: the root of the hierarchy
• storage node: this represents an indexed storage (a DVD, an external hard drive, an USB drive, some arbitrary directory, etc).
• dir node: this is a directory
• file node: this is a file
• archive node: this is an archive file (tar, zip, etc)
• archived node: this is a file contained in an archive

Wildcards are supported in the <path> arguments of all commands and provide a way to explore the catalog. Make sure to quote these on the command line to avoid your shell interpreting the wildcards.

All command line switches can be provided using environment variables by prefixing with GOCATCLI_ and adding the switch name in capital and - replaced with _. For example --catalog would be GOCATCLI_CATALOG=mycatalog.catalog.

You can generate shell completion scripts using gocatcli completion

## for zsh
## copy the file to a path within ${fpath}
$ gocatcli completion zsh
## for bash
## source the file
$ gocatcli completion bash
## for fish
## mkdir -p ~/.config/fish/completions
## cp gocatcli.fish ~/.config/fish/completions/gocatcli.fish
$ gocatcli completion fish

Index data

$ gocatcli index --help

Index any directories with

# the directory will be stored in the catalog under
# the storage "directory"
$ gocatcli index /some/directory

# you can specify the name of the storage
$ gocatcli index /some/other/path myStorageName

gocatcli uses the basename of the path to index as the storage name unless you specify the name when indexing.

ignore pattern

gocatcli uses shell glob / gitignore like pattern, for more see

• https://git-scm.com/docs/gitignore
• https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html

Examples

• *.go: all .go files in the current directory
• **/*.go: all .go files recursively
• **/.git*: ignore .git directory
• **/.git*/**: ignore .git directory content
• **/.*: ignore all hidden file

The below example ignores any file ending with .go or .md and anything in the .git directory, and the directory .git itself:

$ gocatcli index ../gocatcli --ignore='**/*.go' --ignore='**/*.md' --ignore='**/.git/**' --ignore='**/.git'

To ignore any hidden file for example

$ gocatcli index ../gocatcli --ignore='**/.*'

Reindex and update

To re-index the content of an already indexed storage, simply re-run index on it

## initial indexing
$ ./bin/gocatcli index /tmp tmp-dir
## re-indexing...
$ ./bin/gocatcli index /tmp tmp-dir
A storage with the name "tmp-dir" already exists, update it? [y/N]: y

Index archives and their content

gocatcli is able to index the content of archives. Simply provide -a --archive to your index command.

Supported archive formats (from https://github.com/mholt/archiver):

• brotli (.br)
• bzip2 (.bz2)
• flate (.zip)
• gzip (.gz)
• lz4 (.lz4)
• snappy (.sz)
• xz (.xz)
• zlib (.zz)
• zstandard (.zst)
• .zip
• .tar (including any compressed variants like .tar.gz)
• .rar
• .7z

Navigate with ls

$ gocatcli ls --help

$ gocatcli ls
$ gocatcli ls storage-name/some/path
$ gocatcli ls 'storage-name/direc*/file'

File browser

A terminal file browser for your catalog

$ gocatcli nav --help

You can type ? to get a list of available options.

Tree view

$ gocatcli tree --help

Find files

With the find command you can easily find all files matching a specific pattern. You can also limit your search to a specific path

$ gocatcli find --help
## lists all files
$ gocatcli find
## find using pattern
$ gocatcli find <pattern>
## find using pattern and limit to a specific path
$ gocatcli find <pattern> --path 'some/path'
$ gocatcli find <pattern> --path 'some/p*th'

<pattern> uses shell glob / gitignore like pattern, for more see

• https://git-scm.com/docs/gitignore
• https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html

Following formats are supported as output for find:

$ gocatcli index internal

$ gocatcli find 'tree' --format=native
internal/commands/tree.go                                    -rw-r--r-- file    1KB 2025-12-26 22:15:53 indexed:2025-12-28 22:33:23
internal/stringer/out_tree.go                                -rw-r--r-- file    3KB 2025-12-26 22:15:53 indexed:2025-12-28 22:33:23
internal/tree                                                drwx------ dir     6KB 2025-12-26 22:15:53 indexed:2025-12-28 22:33:23 children:1
internal/tree/tree.go                                        -rw-r--r-- file    6KB 2025-12-26 22:15:53 indexed:2025-12-28 22:33:23

$ gocatcli find 'tree' --format=csv-with-header
name,type,path,size,indexed_at,maccess,checksum,nbfiles,free_space,total_space,meta,storage
tree.go,file,commands/tree.go,1KB,2025-12-28 22:33:23,2025-12-26 22:15:53,,0,,,,internal
out_tree.go,file,stringer/out_tree.go,3KB,2025-12-28 22:33:23,2025-12-26 22:15:53,,0,,,,internal
tree,dir,tree,6KB,2025-12-28 22:33:23,2025-12-26 22:15:53,,1,,,,internal
tree.go,file,tree/tree.go,6KB,2025-12-28 22:33:23,2025-12-26 22:15:53,,0,,,,internal

$ gocatcli find 'tree' --format=script
op=file; source=/media/mnt; ${op} "${source}/commands/tree.go" "${source}/stringer/out_tree.go" "${source}/tree" "${source}/tree/tree.go"

$ gocatcli find 'tree' --format=filename
tree.go
out_tree.go
tree
tree.go

$ gocatcli find 'tree' 'out' --format=filename
tree.go
out_tree.go
tree
tree.go
out_csv.go
out_debug.go
out_du.go
out_native.go
out_script.go
out_tree.go

Find files with fzf

A terminal fzf file browser for your catalog

$ gocatcli fzfind --help

Disk usage

$ gocatcli du --help

Create hierarchy locally

$ gocatcli create --help

Mount filesystem

$ gocatcli mount --help

Edit storage

$ gocatcli storage --help

List all storages with the storage list command.

Remove a storage and its children with the storage rm command.

Following commands allow to edit a storage and its fields:

• meta: storage description
• tag: add a tag to the storage
• untag: remove a tag from the storage

Output formats

• native: ls-like output
• csv: csv
• csv-with-header: csv with header
• tree: tree
• script: generates a script to handle matches
• debug: debug output
• filename: only filename

Convert catcli catalog

$ gocatcli convert --help

From catcli to gocatcli

https://github.com/deadc0de6/catcli/

$ gocatcli convert --help

Contribution

If you are having trouble installing or using gocatcli, open an issue.

If you want to contribute, feel free to do a PR.

The tests.sh script handles the linting and runs the tests.

Thank you

If you like gocatcli, buy me a coffee.

License

This project is licensed under the terms of the GPLv3 license.