DEV Community: LTD Atlas

Zoxide Setup That Actually Works: Install, Initialize, and Verify

LTD Atlas — Sat, 08 Aug 2026 04:59:40 +0000

Installing zoxide is easy. Getting from “the binary exists” to “the z command works every time I open a terminal” is where people tend to lose ten minutes.

The reason is simple: zoxide has two layers. The executable stores and queries directory history; a small piece of shell code defines z, zi, and the hook that records where you go. A package manager installs the first layer. zoxide init supplies the second.

If the tool is new to you, this short explanation of what zoxide is covers the mental model. The rest of this post is the setup I use to get a clean, testable installation.

Disclosure: I maintain zoxide.org as an independent guide site. It is not the official zoxide project. Commands in this post were checked against the official zoxide repository.

1. Install the binary

Pick one method for your platform. Do not install the same executable with three package managers; that makes later upgrades and PATH debugging needlessly confusing.

Linux and WSL:

curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

macOS with Homebrew:

brew install zoxide

Windows with WinGet:

winget install ajeetdsouza.zoxide

Any platform with a working Rust toolchain:

cargo install zoxide --locked

There are more distribution-specific options in this install zoxide guide. Whichever route you choose, verify the executable before touching your shell config:

zoxide --version

If that command fails, stop here. This is an installation or PATH problem, not a shell-initialization problem.

2. Initialize the shell

Add exactly one matching line near the end of your shell configuration.

Bash (~/.bashrc):

eval "$(zoxide init bash)"

Zsh (~/.zshrc):

eval "$(zoxide init zsh)"

Fish (~/.config/fish/config.fish):

zoxide init fish | source

PowerShell ($PROFILE):

Invoke-Expression (& { (zoxide init powershell | Out-String) })

Nushell uses two files. Generate the integration from the environment file:

zoxide init nushell | save -f ~/.zoxide.nu

Then load it from the config file:

source ~/.zoxide.nu

Restart the terminal after saving the file. Sourcing the file works too, but a fresh process is a better test: it proves the setup survives a normal shell launch.

3. Verify all three layers

A reliable diagnosis checks the executable, generated shell function, and database separately.

Check the executable

command -v zoxide
zoxide --version

PowerShell equivalent:

Get-Command zoxide
zoxide --version

Check the generated command

For Bash and Zsh:

type z
type zi

For Fish:

type -a z
type -a zi

You should see a function rather than a second unrelated executable.

Check the database

Visit a few directories normally, then inspect what zoxide knows:

zoxide query --list --score

If the list stays empty after normal navigation, the hook is not loading. Look for an early return in the shell config, competing cd wrappers, or an init line placed before a framework that overwrites it.

4. Use the small command set that matters

You do not need to memorize much:

z project            # Jump to the best match
z client api         # Match multiple keywords
z -                  # Return to the previous directory
zi project           # Choose interactively with fzf

The underlying database commands are useful when a match looks wrong:

zoxide query --list --score project
zoxide add ~/src/important-project
zoxide remove ~/src/old-project

The extended zoxide commands reference covers import, query flags, environment variables, and database maintenance. For daily use, the six commands above are usually enough.

5. Fix the common failure modes

`zoxide` works, but `z` is not found

The binary is installed; the shell integration is missing or loaded from the wrong file. Confirm which shell is actually running:

ps -p $$ -o comm=

Then put the matching init line in the startup file that interactive sessions read.

`zi` says it cannot find fzf

zi uses fzf for interactive selection. Install fzf, verify it is on PATH, and restart the shell:

fzf --version

Plain z keyword works without the interactive picker.

A keyword opens the wrong directory

Inspect the candidates before changing anything:

zoxide query --list --score keyword

Zoxide ranks by frequency and recency. Visiting the intended directory, or explicitly adding it, raises its score. Remove a stale entry only when you are sure it is no longer useful.

Aliasing `cd` causes recursion or odd behavior

Do not write alias cd=z. Let zoxide generate a safe replacement:

eval "$(zoxide init zsh --cmd cd)"

Use the equivalent command for your shell. If the behavior is still strange, return to the default z command first and rule out other cd wrappers.

A clean setup is observable

The most useful habit is to test one layer at a time:

zoxide --version proves installation and PATH.
type z proves shell initialization.
zoxide query --list --score proves the hook is recording directories.

Once those three checks pass, zoxide stops feeling magical and becomes a small, predictable terminal tool—which is exactly what a navigation utility should be.

Building an Uncertainty-Aware Practice-Exam Score Calculator in Java

LTD Atlas — Mon, 03 Aug 2026 15:51:26 +0000

Building an uncertainty-aware practice-exam score calculator in Java

A score calculator is easy to write if it returns one number. The harder and
more honest problem is preserving uncertainty, source quality, and timing.

This tutorial uses the open-source nbmecalc-core Java package maintained by
the team behind the USMLE score predictor. It runs
offline, performs no tracking, and treats every mapping as an independent model
assumption rather than an official conversion.

Install the library

<dependency>
  <groupId>io.github.jiankn</groupId>
  <artifactId>nbmecalc-core</artifactId>
  <version>1.0.0</version>
</dependency>

Represent heterogeneous observations

Different assessment families do not share one native scale, so the API keeps
the source explicit:

var exams = List.of(
    PracticeExam.nbme(240, 30, 21),
    PracticeExam.uwsa2(250, 7),
    PracticeExam.free120(76, 2)
);

The optional age enables recency weighting. The NBME form number is optional
because the model only applies a bias when it has an explicit rule for that
form.

Return a range, not false precision

Prediction result = ScorePredictor.predict(exams, StepKind.STEP_2, 10);

System.out.printf(
    "Estimate %d, interval %d-%d, model version %s%n",
    result.pointEstimate(),
    result.ciLower(),
    result.ciUpper(),
    result.algorithmVersion()
);

The model converts each observation, multiplies recency and source-quality
weights, and rounds the weighted mean. Its half-width begins at 16 / sqrt(n)
and is adjusted for low-weight-only inputs and examination horizon.

Persist the algorithm version with any cached result. Otherwise a future model
revision can silently mix incompatible values in the same progress chart.

Validate boundary behavior

Tests should cover more than a happy-path example:

interpolation at and between anchors;
clamping beyond the outer anchors;
source-specific adjustments;
non-finite scores and negative ages;
uncertainty widening and probability bounds.

The source repository includes these
tests and generated API documentation. The published package is also available
from Maven Central.
For the user-facing methodology and limitations, see
public methodology and validation plan.

Responsible use

This is an educational planning example. It is not affiliated with or endorsed
by NBME, FSMB, USMLE, UWorld, AMBOSS, or CMS, and it must not be presented as a
guarantee of an actual examination result.

Parsing Pinterest URLs Safely in JavaScript (Without Network Requests)

LTD Atlas — Mon, 03 Aug 2026 13:37:02 +0000

Pinterest URLs look simple until an application has to accept them from users.

A Pin can arrive on a country-specific domain, contain tracking parameters, or use a short pin.it URL. A loose check such as hostname.includes("pinterest") also accepts lookalike domains. Fetching every URL to determine what it represents adds latency and creates an avoidable server-side request forgery risk.

This article shows a stricter, network-free approach.

Define the result before writing the parser

The useful output is not just true or false. A consuming application usually needs to know:

whether the URL is supported;
whether it represents a Pin, profile, board, Ideas page, or short link;
the numeric Pin or Ideas ID when one exists;
a canonical URL with tracking parameters removed.

A discriminated result makes those decisions explicit:

type PinterestUrlKind = "pin" | "short" | "profile" | "board" | "ideas";

interface ParsedPinterestUrl {
  kind: PinterestUrlKind;
  originalUrl: string;
  normalizedUrl: string;
  pinId?: string;
  shortcode?: string;
  username?: string;
  boardSlug?: string;
  ideaId?: string;
}

Validate the URL object first

Use the platform URL parser before applying path rules:

function parseHttpsUrl(input) {
  const value = input.trim();
  if (!value) throw new Error("URL is empty");

  const url = new URL(value);

  if (url.protocol !== "https:") {
    throw new Error("Only HTTPS URLs are supported");
  }

  if (url.username || url.password || (url.port && url.port !== "443")) {
    throw new Error("Credentials and custom ports are not supported");
  }

  return url;
}

This rejects inputs such as http://pinterest.com/..., URLs containing credentials, and unexpected ports before any classification occurs.

Use an exact host allow list

Do not use suffix or substring matching alone. These checks are unsafe:

hostname.includes("pinterest");
hostname.endsWith("pinterest.com");

The first accepts pinterest.example; the second accepts notpinterest.com unless the dot boundary is handled correctly. An explicit set is easier to audit:

const PINTEREST_HOSTS = new Set([
  "pinterest.com",
  "www.pinterest.com",
  "de.pinterest.com",
  "fr.pinterest.com",
  "pinterest.co.uk",
  "www.pinterest.co.uk",
  "pinterest.com.au",
  "www.pinterest.com.au",
]);

function isAllowedHost(hostname) {
  return PINTEREST_HOSTS.has(hostname.toLowerCase());
}

In production, the set can include every Pinterest country domain that the application intentionally supports. Unknown hosts should fail closed.

Match paths by type

Once the scheme and host are trusted, classify the pathname. A numeric Pin path can be handled without looking at query parameters:

const pinMatch = url.pathname.match(/^\/pin\/(\d{1,20})\/?$/);

if (pinMatch) {
  const pinId = pinMatch[1];

  return {
    kind: "pin",
    originalUrl: input,
    normalizedUrl: `https://www.pinterest.com/pin/${pinId}/`,
    pinId,
  };
}

The normalized URL deliberately discards parameters such as utm_source, fragments, and country-specific hosts. Profile and board paths can be classified from their segment count, while reserved paths such as /search/ and /settings/ should be rejected before treating a single segment as a username.

Treat `pin.it` as a separate type

Short links are valid input, but resolving one requires a network request. A pure parser should classify and normalize the short URL without pretending to know its final Pin:

const shortMatch = url.pathname.match(/^\/([A-Za-z0-9_-]+)\/?$/);

if (url.hostname === "pin.it" && shortMatch) {
  return {
    kind: "short",
    originalUrl: input,
    normalizedUrl: `https://pin.it/${shortMatch[1]}/`,
    shortcode: shortMatch[1],
  };
}

The consuming application can decide whether it is allowed to follow redirects. Keeping that policy outside the parser makes the library deterministic and safe to use in build tools, CLIs, and server validation.

Use a tested package when the edge cases matter

I extracted these rules into the small MIT-licensed pinterest-url-normalizer package. It recognizes Pin, pin.it, profile, board, and Ideas URLs across supported country domains and performs no network requests.

npm install pinterest-url-normalizer

import {
  isPinterestUrl,
  normalizePinterestUrl,
  parsePinterestUrl,
} from "pinterest-url-normalizer";

const parsed = parsePinterestUrl(
  "https://de.pinterest.com/pin/987654321/?utm_source=share",
);

console.log(parsed.kind);          // pin
console.log(parsed.pinId);         // 987654321
console.log(parsed.normalizedUrl); // https://www.pinterest.com/pin/987654321/

isPinterestUrl("https://pin.it/AbC123"); // true
normalizePinterestUrl("https://pinterest.co.uk/example/media-tools/");
// https://www.pinterest.com/example/media-tools/

The parser is maintained alongside SavePinner's Pinterest downloader, where canonical URL handling is needed before a user starts a media workflow. The library itself contains no downloader, browser automation, analytics, or remote code.

A short validation checklist

Before accepting a Pinterest URL in an application, verify that you:

parse it with the platform URL class;
require HTTPS;
reject credentials and nonstandard ports;
compare the hostname against an exact allow list;
classify known path shapes and reject reserved paths;
remove queries and fragments from canonical output;
keep short-link resolution outside the pure parser;
test lookalike hosts and malformed paths as aggressively as valid examples.

URL normalization is a small boundary with security consequences. Making the accepted forms explicit is usually simpler than trying to repair permissive parsing later.