@guldner/tfmgr (0.1.0)
Installation
@guldner:registry=npm install @guldner/tfmgr@0.1.0"@guldner/tfmgr": "0.1.0"About this package
tfmgr
@guldner/tfmgr provides a keyboard-first terminal file manager (tm) and a compatible tag-management CLI (ftag). Both use the same TypeScript tag library and support per-folder .ftag sidecars or filename-embedded tags.
Install
Configure the Gitea npm registry once:
npm config set @guldner:registry https://git.guldner.eu/api/packages/guldner/npm/
npm config set -- '//git.guldner.eu/api/packages/guldner/npm/:_authToken' "$GITEA_NPM_TOKEN"
Install with mise:
mise use -g npm:@guldner/tfmgr
The package requires Node 26 or newer. This repository pins Node through mise.toml. The tm launcher enables Node's currently experimental FFI support, which OpenTUI requires.
Commands
tm [path]
ftag add report.pdf work year=2026
ftag list report.pdf
ftag find work year=2026
ftag rm report.pdf work
tm starts in the current directory by default. Pass a directory to open it, or pass a file to open its parent directory with that file selected. Key bindings: j/k or arrows move, h/l collapse/expand, Enter opens, Backspace moves to the parent directory, / searches tags and metadata, n searches names, a adds tags or metadata, r removes them, e edits metadata, d deletes a file after confirmation, m moves a file, s reveals it in the native file manager, R refreshes, and q quits. In search results, f focuses the result in the tree.
tm lists folders before files and hides dotfiles by default. Configure ~/.config/tm.json to use a single alphabetical list or show dotfiles:
{
"foldersFirst": false,
"showDotfiles": true
}
Storage
By default tags and metadata are stored in .ftag beside their files. The format is semicolon separated:
report.pdf;important;work;year=2026
Set ~/.config/ftag.json to embed tags in filenames instead. Metadata remains in .ftag:
{
"storage": "filename",
"paths": [{ "glob": "~/Documents/*", "storage": "ftag" }]
}
Filename storage changes report.pdf to report [important,work].pdf.
Library API
import { add, find, inspect, remove } from "@guldner/tfmgr/ftag"
await add("report.pdf", ["work", "year=2026"])
const metadata = await inspect("report.pdf")
const matches = await find(process.cwd(), ["work"])
await remove("report.pdf", ["year=2026"])
Publishing
Push a version tag such as v0.1.0 after setting the repository Actions secret GITEA_NPM_TOKEN to a Gitea personal access token that can write packages. The publish workflow validates, builds, smoke-tests, and publishes the matching package version to Gitea.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @opentui/core | 0.4.5 |
| @opentui/react | 0.4.5 |
| react | 19.2.8 |
Development dependencies
| ID | Version |
|---|---|
| @types/node | ^26.0.0 |
| @types/react | 19.2.17 |
| tsup | ^8.5.1 |
| tsx | ^4.20.6 |
| typescript | ^5.9.3 |
| vitest | ^4.0.18 |