FAQ

Quick answers about UBLX, Nefaxer, and ZahirScan. For workflows and flags, see the Guides overview and linked pages below.

What is UBLX?

UBLX is a terminal catalog for a project directory: index once, browse paths in a flat TUI, enrich files on demand, and export or diff snapshots. It is built on Nefaxer for indexing and ZahirScan for deep metadata when you enhance.

How do the three projects fit together?

Tool	Role
Nefaxer	Parallel directory walk → SQLite snapshot, change detection, optional content hashes
ZahirScan	Template mining and per-format metadata when you batch- or on-demand enhance
UBLX	TUI, lenses, Delta tab, config, headless --snapshot-only / --export, query / doctor / serve (--url client), per-root cache

See Install, Nefaxer UBLX integration, and ZahirScan UBLX integration.

Why is my catalog “path-only”?

By default UBLX only stores paths and filetype hints on snapshot — fast for large trees. Rich previews and Metadata / Writing tabs need ZahirScan output.

• Turn on full enhance globally: enable_enhance_all = true or ublx --full-snapshot
• Scope enhance per folder: [[enhance_policy]] with policy = "auto" or "manual"
• Enhance one file in the TUI: Enhance with ZahirScan (quick actions)

Details: Path-only vs full enhance, Enhance policies, Configuration.

Where is the index stored?

UBLX keeps a per-root SQLite catalog under your user cache (ubli/, keyed by sanitized path + hash). Local project behavior lives in .ublx.toml or ublx.toml in the indexed directory. Nefaxer can also use a standalone .nefaxer index in-tree when you run the CLI directly.

Is UBLX a file manager?

No. It is aimed at project trees: snapshot browse, lenses, Delta diffs, duplicate detection, and headless export — not drag-and-drop or bulk rename across the OS.

How do I run UBLX without the TUI?

ublx --snapshot-only /path/to/project
ublx --full-snapshot --export /path/to/project

See Headless snapshot + export.

Why is ublx serve a blank page / 404 on /?

Either the binary was built without --features serve / ui (so there is no serve subcommand), or it has serve but not ui (API-only: GET / is 404). Install with the SPA:

brew install Latka-Industries/ublx/ublx   # includes UI
cargo install ublx --features ui

Then ublx serve . --open. Log should mention serve UI static mount (Embedded).

Default cargo install ublx is TUI + query/doctor — no HTTP server. Add --features serve for API-only, or --features ui for serve + browser UI.

Where is the Rust API documentation?

Each product menu in the top nav ends with API reference → docs.rs for ublx, nefaxer, and zahirscan. User guides on this site expand the GitHub READMEs.

Do I need ZahirScan or Nefaxer installed separately?

UBLX bundles the stack for normal use. You may install nefaxer or zahirscan on their own for CLI-only indexing or batch extraction outside the TUI — see Nefaxer install and ZahirScan install.

What terminal do I need?

Truecolor (24-bit) and image support are expected; a Nerd Font is strongly recommended. Optional helpers (tree, resvg, pdftoppm / mutool, ffmpeg, etc.) improve previews — listed in Install.

Graphics-protocol previews (Kitty / iTerm2 / Sixel) need the terminal to answer capability queries. Over SSH, those queries often fail and the Viewer falls back to halfblocks unless the remote session still looks like your local terminal. See Viewer images look blocky over SSH.

Viewer images look blocky over SSH

UBLX uses ratatui-image. If Settings → External apps shows halfblocks over SSH, the remote process did not detect Kitty / iTerm2 / WezTerm.

1. Prefer the terminal’s own SSH (when available): wezterm ssh, Kitty’s kitten ssh, etc. Plain ssh can still work if env is forwarded.

2. Forward terminal identity (client + server)

On the client (~/.ssh/config):

Host your-server
  SendEnv TERM_PROGRAM TERM_PROGRAM_VERSION COLORTERM KITTY_WINDOW_ID
  # WezTerm / iTerm-family hint if the local shell does not already export it:
  SetEnv TERM_PROGRAM=WezTerm

Use the TERM_PROGRAM value that matches your app (WezTerm, iTerm.app, kitty, …). For Kitty, also forwarding KITTY_WINDOW_ID (and keeping TERM=xterm-kitty) helps.

On the server (/etc/ssh/sshd_config or a drop-in under sshd_config.d/):

AcceptEnv TERM_PROGRAM TERM_PROGRAM_VERSION COLORTERM KITTY_WINDOW_ID

Then reload sshd (sudo systemctl reload sshd on Fedora/systemd).

3. Remote shell fallback (put in ~/.zshrc / ~/.bashrc on the remote, or a file you source):

# Graphics-terminal hints for UBLX / ratatui-image over SSH
if [[ -n ${SSH_CONNECTION:-} ]]; then
  export TERM_PROGRAM="${TERM_PROGRAM:-WezTerm}"   # or kitty / iTerm.app
  # WezTerm only — safe no-op for other terminals:
  export WEZTERM_EXECUTABLE="${WEZTERM_EXECUTABLE:-1}"
fi

For Kitty-only remotes, prefer:

if [[ -n ${SSH_CONNECTION:-} ]]; then
  export TERM_PROGRAM="${TERM_PROGRAM:-kitty}"
  export TERM="${TERM:-xterm-kitty}"
fi

After reconnecting, open an image in the Viewer and check Settings → Image protocol — you want Kitty, iTerm2, or Sixel, not halfblocks.

Is UBLX stable?

UBLX is in active development — expect breaking changes. Watch the UBLX repo for releases.

Something broke — where do I look?

1. CLI and Configuration
2. Snapshot vs enhance: Path-only vs full enhance
3. Keys and panes: TUI overview and Command mode & menus
4. Open an issue on the relevant GitHub repo (UBLX, Nefaxer, or ZahirScan)