Documentation

Start here

One fact frames everything below: the desktop app and the command line are the same binary. StorCat reads its first argument. Hand it a subcommand it recognises and it runs headless, prints to standard output and exits. Hand it nothing and it opens the window instead. There is no separate command-line package to install, and no mode to switch out of.

Opened as an application, the window starts at 1200 × 800. After that it reopens at whatever size and position you left it at, because Remember window size & position is on by default; the setting that governs it also says what you get when it is off.

One window, three columns New in v

Every section below assumes the same shape. Your catalogs sit in a rail down one side of the window. The directory tree of whichever one you have selected fills the middle. A details panel for the selected catalog or file sits on the other side. Nothing is behind a mode you have to enter first, and Escape closes the details drawer and any open dialog from anywhere in the app.

Which side the rail sits on is a setting, and every frame on this page shows it on the left.

Scan a drive

Cataloguing a volume is one pass through the create panel: choose a source, name the result, start it, and watch it walk.

1. Open the create panel. It slides over the workspace rather than replacing it, so the catalogs you already have stay where they were.
2. Choose the source. The volume, drive or folder you want recorded.
3. Name the catalog. If you have set a default filename root in Settings, the field starts from it.
4. Start it. ⌘+Enter — Ctrl+Enter on Windows and Linux — submits the form without reaching for the button.

Progress you can read, and stop New in v

Before the total is known there is no percentage, and StorCat does not invent one. While it is still counting it reports how many files it has seen so far and the directory path it is walking at that moment; a percentage appears only once there is a total to divide by.

Stopping and stepping away are different choices, and the panel treats them as different. Escape, the close control and a click outside the panel all stop the walk. Run in the background leaves the scan running and hands you the rest of the app; nothing is abandoned. Cancelling is not an error either — it produces no error state, just a scan that is no longer running.

If the source disappears mid-walk — the drive is unplugged, the share drops — you are offered the partial catalog rather than losing the walk that already happened.

Search a catalog

There are two ways to find something, and they do not search the same thing. Reach for the wrong one and you will conclude a file is not catalogued when it is simply in a different catalog.

The rail filter narrows what is already in front of you. It works on the catalog you have open, and that is all it claims to do.

The command palette New in v

⌘+K — Ctrl+K on Windows and Linux — opens the palette from anywhere in the app, including while the rail filter has the cursor in it. It searches every catalog in your catalog directory, not only the one you happen to have open.

Activating a result reveals that file in the tree, switching catalogs first if the hit lives in a different one. Two deliberate small behaviours: it waits for two characters before it searches anything, it pauses briefly after you stop typing rather than re-running on every keystroke, and every open starts from an empty field — it never re-runs what you typed last time.

The palette, the create panel and Settings are mutually exclusive by construction: opening any one of them closes the others. That is worth knowing before it surprises you, because a panel closing on its own otherwise reads as a bug.

Re-scan and read the diff

Plug the drive back in, scan it again, and StorCat compares what is on the volume now against the catalog you already had. Three steps: pick the volume, let it scan, read the result.

Reading the result New in v

A comparison sorts what it finds into five states: added, removed, changed, unreadable and unchanged. Four of those become list groups you can open and read. The fifth does not: unchanged entries never enter the entry list at all and are reported as a count in the summary instead. That is deliberate rather than an omission — a list of everything that stayed the same is not a list anyone reads — but it is worth knowing, because a result that looks short is usually a volume that barely moved.

When you keep a result you choose whether it overwrites the catalog or is kept beside it as a second one. Closing the dialog instead discards the comparison; the catalog you had is untouched.

That frame is a scrolled region of one result, showing the ADDED and REMOVED groups. The other two lists sit below its edge.

Manage catalogs

Everything you can do to an existing catalog lives in one menu, on the details panel for the catalog you have selected. Four items, named here exactly as the application names them:

• Rename catalog… — give it a different name.
• Re-scan volume & diff… — the entry point to the comparison described above.
• Duplicate catalog — a second copy, which is what you want before an experiment you might not keep.
• Delete catalog… — opens a confirmation that names the exact files, then moves them to your operating system's Trash. The matching .html goes with it unless you clear that checkbox. It is not erased in place: you can restore a catalog from the Trash until the Trash is emptied.

Escape closes the details drawer, and it closes any dialog one of these opens.

Change settings

⌘+, — Ctrl+, on Windows and Linux — opens Settings over the workspace. It does nothing while a scan is running, so a keystroke cannot pull the progress panel out from under a walk.

There is no save step. Every change is applied as you make it. That surprises people who go looking for a confirm button, so it is worth stating plainly: close the dialog whenever you like — what you changed is already in effect.

The frame above shows the dialog from its top: the theme grid, then Row density and Catalog rail position under Layout, then the catalog directory, the default filename root and the first of the file-writing toggles. The remaining toggles continue below its edge, and they are all listed here.

How it looks

• Theme — eleven of them: three light and eight dark. Each card carries a small swatch of its own palette and is tagged light or dark, so you are not choosing from names alone.
• Row density — Compact or Comfortable. How tightly the tree and the lists pack.
• Catalog rail position — Left or Right. The details panel takes the other side.

Where catalogs go, and what gets written

• Catalog directory — the folder StorCat reads catalogs from and writes them to. It is also the scope the command palette searches.
• Default filename root — pre-filled into every new catalog's name field. Empty until you set one.
• Write HTML alongside JSON — on. Every catalog gets a matching .html file beside its JSON, openable in any browser with no StorCat installed.
• Copy catalogs to a secondary location — off, with its own directory field, empty until you turn it on and choose one. A second copy of every catalog, written at the same time.
• Watch catalog directory for changes — off. When on, catalogs added to the directory outside StorCat are picked up without a restart.
• Remember window size & position — on. The window's size and position are restored next launch; with it off, you get 1024 × 768.

The command line

The same binary, without the window. Every command, every flag and every exit code below is read out of the application's own source rather than out of a README, which is why this reference is exhaustive: a reference that omits a flag sends you to --help anyway.

StorCat dispatches on its first argument. create, search, list, show, open, version and help run headless, print to standard output and exit. So do --help and -h, which are the same thing as help. An argument it does not recognise is not an error: main.go dispatches into the command line only for those labels and falls out of the switch to the window for anything else, so storcat wibble opens the window and prints nothing on either stream. With no argument at all, the window opens for the same reason.

Exit codes

Three of them, and a script can rely on them.

• 0 — success. Also what you get when there was simply nothing to report; see below.
• 1 — a runtime error: a path that is not a directory, a catalog that will not load, a browser that would not open.
• 2 — a usage error: a missing argument, a flag the command does not take, or a path that does not end in .json where one is required.

The usage block

storcat 

Usage:
  storcat [command]

Commands:
  create    Create a catalog from a directory
  search    Search catalogs for a term
  list      List catalogs in a directory
  show      Display a catalog's tree structure
  open      Open a catalog's HTML in the default browser
  version   Print the version

Flags:
  -h, --help   Show help for a command

Run 'storcat <command> --help' for command-specific help.

storcat help and -h print that same block, and every command answers --help with a usage block of its own.

Every command

One section each, carrying the usage line the command prints for itself and its complete flag list. --json is defined on four commands — create, search, list and show — and what it emits is indented with two spaces. storcat open and storcat version define no flags at all, so storcat version --json is a usage error and exits 2; storcat help takes the argument, ignores it, and prints the usage block.

storcat create

Usage: storcat create <directory> [flags]

Walks a directory and writes two files: the catalog itself as JSON, and a matching HTML file that opens in any browser on a machine with no StorCat on it. Both land inside the directory it just catalogued and are named after it, unless you say otherwise.

• --title — the title recorded inside the catalog. Defaults to the directory's own name. Quote it if it contains spaces.
• --name — the output filename stem, without an extension. Defaults to the directory's own name.
• --output — copy both catalog files into this directory as well, so a second set lands somewhere that is not the drive you just catalogued.
• --json — emit the result as JSON instead of the summary.

On success it prints where both files went, how many files it recorded, and how much they add up to — plus the copy destination when you gave it --output:

Created catalog: /Volumes/Archive/archive.json
  HTML:  /Volumes/Archive/archive.html
  Files: 4821
  Size:  3.4M
  Copied to: /Volumes/Backup/Catalogs

storcat search

Usage: storcat search <term> [directory] [flags]

Searches every catalog in the directory you name — the current directory when you name none — and prints one row per hit, under File, Path, Type, Size and Catalog. The last column is what tells you which drive the hit is on.

• --json — emit the results as JSON instead of the table.

storcat list

Usage: storcat list [directory] [flags]

Names every catalog in the directory you point it at — the current directory when you point it at nothing — under Name, Title, Size and Modified.

• --json — emit the listing as JSON instead of the table.

storcat show

Usage: storcat show <catalog.json> [flags]

Prints a catalog's directory tree without opening anything. Useful when you want to look inside a catalog from a shell, or pipe it somewhere.

• --depth N — how far down to print. -1 is unlimited and is the default; 0 prints the root only. The value has to sit immediately after the flag.
• --json — emit the catalog's raw JSON instead of the tree.
• --no-color — drop the colour, which is what you want when the output is going into a file or a pipe.

storcat open

Usage: storcat open <catalog.json>

Opens the catalog's HTML report in your default browser. No flags. It works out the HTML path by swapping the .json extension for .html, so it fails if that file was never written or has since been moved.

storcat version

Usage: storcat version

Prints the version and exits. No flags.

storcat help

Usage: storcat help, or --help, or -h. All three print the usage block above.

Behaviour worth knowing

The handful of things a reader otherwise discovers by being confused.

Give create its directory before its flags

storcat create splits its arguments at the first one beginning with a dash and treats everything from there on as flags. So the directory has to come first:

Written the other way round — storcat create --title Archive /Volumes/Archive — the directory lands on the flag side of that split and the command reports a missing directory argument. This is the one command that cares: search, list, show and open sort each argument individually and do not mind the order.

Keep --depth next to its number

storcat show takes the argument immediately after --depth as that flag's value, and only for that flag. --depth 2 works; a --depth with its number pushed to the end of the line does not.

Both catalog commands insist on a .json path

storcat show and storcat open reject a path that does not end in .json, and exit 2. Hand either of them the HTML file by mistake and that is the message you get. storcat open then works out the HTML file for itself, by swapping the extension — so it fails if the JSON is there but the HTML beside it is not.

Finding nothing is a success, not a failure

This one matters if you are scripting. storcat list with no catalogs to list prints No catalogs found. and exits 0. storcat search with no hits prints No results found. and exits 0 as well. An empty result is not an error, so a script that branches on the exit code should not treat “nothing found” as a failure — read the output, or ask for --json and count the entries.

The sizes it prints are not the sizes the download page prints

Every size the command line prints — the Size: line after a create, the Size column in the two tables — is 1024-based. That is why the output reads 271K and 3.4M rather than in kilobytes and megabytes spelled out.

The download page uses a different convention: plain decimal megabytes, matching what the release page shows beside each file. Two figures written in two conventions look alike and are not on the same scale, so do not read one against the other.

Check what your install named the executable

The release artifacts ship the executable as StorCat, capitalised — the .deb puts it at /usr/bin/StorCat. The commands on this page are written in lowercase because that reads better, and on a case-sensitive system that is not the same name. Nothing else differs: same binary, same commands, same flags. If lowercase is what you would rather type, a symlink or a shell alias settles it once.