Skip to main content

jzr-tools

jzr-tools puts fast everyday jobs behind one command, jzr: convert images, video and audio, trim and compress media, make GIFs, edit audio tags, free busy ports and clean up your machine. It runs on Windows, Linux and macOS.

Install from PyPI

jzr-tools needs Python 3.11 or newer. Install the jzr command with pipx:

pipx install jzr-tools
jzr --help

Or run it without installing, with uv:

uvx --from jzr-tools jzr --help

The video and audio commands use ffmpeg. If it is not on your PATH, run jzr ffmpeg install once to download it into jzr's own folder.

To upgrade later, run pipx upgrade jzr-tools; uvx picks up new releases with uvx --from jzr-tools@latest jzr.

Install from source

For global usage with pipx, from a clone of the repository:

pipx install .
jzr --help

For development with uv:

uv sync
uv run jzr --help
uv run python -m unittest discover -s tests

You can also run the package directly:

python -m jzr_tools --help

Layout

  • src/jzr_tools/cli.py: root Click group and the command registry. Commands are imported only when invoked, so each jzr call loads just what it needs; a new command is added by listing it in _COMMANDS
  • src/jzr_tools/commands/: CLI-facing command modules
  • src/jzr_tools/core/: plain Python business logic
  • tests/: CLI and core behavior checks

Commands

Commands follow one shape, jzr <thing> <action>, grouped by what they work on. Run jzr -h, or -h after any group or command, for the details.

Command What it does
jzr image convert Convert images between formats, one file or a whole directory
jzr image <from>2<to> Shorthand for a format pair, e.g. jzr image png2jpg
jzr image formats List supported extensions and the conversion engines available
jzr video convert Convert video to mp4, mov, mkv or webm, take the sound out as audio, or make a GIF
jzr video <from>2<to> Shorthand for a format pair, e.g. jzr video mov2mp4
jzr video compress Make videos smaller as H.264 MP4, at a quality or under a size (--size 25MB)
jzr video info Show the container, duration, size and streams of video files
jzr video formats List video targets, the ffmpeg in use and which encoders it has
jzr video trim Cut a time range out of video files, exactly or instantly from a keyframe
jzr video gif Make a looping animated GIF of a video, or of part of it
jzr audio convert Convert audio files to mp3, m4a, opus, ogg, flac or wav
jzr audio <from>2<to> Shorthand for a format pair, e.g. jzr audio wav2mp3
jzr audio info Show the format, streams and tags of audio files
jzr audio formats List audio targets, the ffmpeg in use and which encoders it has
jzr audio trim Cut a time range out of audio files without losing quality
jzr audio tags Show or edit tags, cover art and lyrics of MP3, M4A, FLAC, Ogg and Opus files
jzr ffmpeg install Download ffmpeg and ffprobe into jzr's own folder
jzr ffmpeg status Show which ffmpeg and ffprobe jzr uses and where they come from
jzr ffmpeg remove Delete the ffmpeg that jzr ffmpeg install downloaded
jzr text slug Turn text into a URL-safe kebab-case slug, optionally dated and copied
jzr port show List listening ports and their processes, or show what uses given ports
jzr port kill Force-kill the processes using one or more local ports
jzr killport Shortcut for jzr port kill
jzr host status Show host, CPU, memory, storage and GPU status
jzr host clean Find caches and other disposable data, and remove what you pick
jzr host procs Show what uses the most memory; optionally end what you pick
jzr bind add Save a long command under a short name, run as jzr <name>
jzr bind list List your shortcuts
jzr bind remove Remove shortcuts
jzr completion Print the tab-completion script for bash, zsh, fish or PowerShell
jzr version Print the installed toolkit version

Image Conversion

jzr image converts with Pillow, which is installed with the toolkit, so it needs nothing else on your machine. HEIC and AVIF are included. Pass --backend magick to use ImageMagick from PATH instead.

Name the files, or leave them out to convert a directory:

jzr image convert photo.png --to jpg -q 90          # one file
jzr image convert photo.png -o small/photo.webp     # one file, named output
jzr image convert a.png b.webp --to avif            # several files
jzr image convert --to jpg                          # every image in this directory
jzr image convert --from heic --to jpg -d ~/Photos -r
jzr image convert --to webp --pattern "^IMG_" -q 85 # only names matching a regex

When the source format is fixed, the pair shorthand is shorter. It is the same command as image convert --from <from> --to <to>:

jzr image png2jpg photo.png -q 90
jzr image png2jpg photo                # the extension may be left off
jzr image heic2jpg -d ~/Photos -r      # every .heic under a directory

Options: -t/--to, -f/--from, -q/--quality (1-100), -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, -b/--backend (auto, pillow, magick), --overwrite, --dry-run.

Behavior worth knowing:

  • Without --from, a directory scan picks up every supported image that is not already in the target format.
  • With a known source format, a listed file with a different extension is rejected rather than converted.
  • --dir and --recursive only apply when no files are listed; combining them with listed files is an error.
  • --pattern is a regular expression matched against each candidate's path relative to the search directory (just the file name unless --recursive is used), or against the file name of each listed file.
  • -o/--output FILE names the output of a single listed file; its extension sets the target format, so --to can be left out. For several files use --outdir.
  • Outputs land beside their source unless --outdir is given. When a directory is scanned with --recursive, its subdirectories are recreated under --outdir; explicitly listed sources are written flat.
  • No output is written twice in one run. Sources that would share a name (logo.png and logo.webp both becoming logo.jpg) get -2, -3, ... appended, in sorted source order.
  • Existing outputs are skipped unless --overwrite is passed.
  • An animated source (GIF, WebP) stays animated when the target is gif, webp or avif, with its frame timings. Any other target gets the first frame.
  • Transparent areas become white in formats that cannot hold transparency (jpg, bmp, ppm).
  • Photos are written upright: a rotation stored in EXIF is applied to the pixels. Other EXIF data and the colour profile are kept where the target format can store them.
  • -q/--quality is 1-100, higher is better, and applies to the lossy formats (jpg, webp, avif, heic). Without it they are written at 90. The other formats are lossless; passing -q for them prints a note on stderr and converts anyway.
  • An output is written under a temporary name and renamed when it is complete, so a failed conversion never leaves a broken file behind.
  • A failed file does not stop the batch; the run exits 1 and reports which files failed.
  • --dry-run lists what would be converted and writes nothing.

With --backend magick:

  • --dry-run prints the exact ImageMagick command for each file.
  • For png and tiff, -q tunes compression rather than being ignored.
  • An output whose path contains % is written under a temporary jzr-tmp-... name and then renamed, because ImageMagick would read the % as a numbered-sequence escape; --dry-run prints a note saying so.
  • Some ImageMagick builds cannot write every format (HEIC on Windows, for one). Such a conversion is reported as failed instead of leaving a file in another format under the requested name.

jzr image formats lists the supported extensions, the Pillow versions in use, and whether ImageMagick was found on PATH.

Video and Audio

jzr video and jzr audio use ffmpeg and ffprobe, except jzr audio tags, which needs neither. jzr does not ship them, but it can fetch them for you:

jzr ffmpeg install        # asks first; -y/--yes skips the question
jzr ffmpeg status         # which ffmpeg is used, its version, where it came from
jzr ffmpeg remove         # delete jzr's copy

jzr ffmpeg install says what it will download, from where, how big it is and where it goes, then puts ffmpeg and ffprobe in jzr's own folder: %LOCALAPPDATA%\jzr\ffmpeg on Windows, ~/Library/Application Support/jzr/ffmpeg on macOS, $XDG_DATA_HOME/jzr/ffmpeg (default ~/.local/share/jzr/ffmpeg) elsewhere. Set JZR_DATA_DIR to use another folder. It needs no admin rights and changes nothing else on the system, PATH included. Run it again to update.

  • Windows and Linux (x64, arm64) get the gpl-shared build of the newest ffmpeg release from BtbN/FFmpeg-Builds; macOS (Apple silicon, Intel) gets the release build from ffmpeg.martin-riedl.de. Only ffmpeg, ffprobe and the libraries they load are kept (about 180 MB on Windows, from an 86 MB download).
  • Each download is checked against the SHA-256 checksum its source publishes next to it. That catches a broken or cut-off download; it does not protect against the source itself being compromised, since the checksum comes from the same place.
  • The new copy is run once before it replaces the old one. A failed download, a checksum mismatch or an archive that tries to write outside its folder installs nothing and leaves the previous copy as it was.
  • jzr goes to the network only inside jzr ffmpeg install (or when you say yes to the offer below): no update checks, nothing sent besides the download requests.

ffmpeg and ffprobe are looked for in this order: JZR_FFMPEG and JZR_FFPROBE (paths to the programs), then jzr's own copy, then PATH. When a command finds none and you are at a terminal, it offers to run the install and then carries on. In a script or pipe it asks nothing, prints ffmpeg was not found. Run: jzr ffmpeg install and exits with code 1.

On a machine with no known build (32-bit, BSD), install ffmpeg yourself and it is found on PATH:

winget install Gyan.FFmpeg     # Windows
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian, Ubuntu

info describes files: container, duration, size, overall bitrate, the video stream (codec, resolution, frame rate, pixel format), each audio stream, and rotation (in degrees clockwise) and HDR transfer when present. audio info adds title, artist, album, year, track and whether there is cover art. --json prints one array with the same facts as numbers and every tag. A file that is not media is reported on its own line and the rest are still shown; the exit code is then 1.

jzr video info clip.mov
jzr video info *.mp4 --json
jzr audio info song.mp3

jzr video formats and jzr audio formats list the target formats, which ffmpeg and ffprobe are used, their versions and where they were found, and which of the encoders jzr uses this ffmpeg build has. Include their output when reporting a problem.

Video conversion

jzr video convert turns video files into mp4, mov, mkv or webm, takes their sound out as mp3, m4a, opus, ogg, flac or wav, or makes a gif. It picks its sources and outputs the way jzr audio convert does:

jzr video convert clip.mov --to mp4                # one file
jzr video convert clip.mov -o out/clip.webm        # named output; --to not needed
jzr video convert *.mkv --to mp4 --outdir mp4
jzr video convert --to mp4 -d ~/Videos -r          # every video file under a directory
jzr video convert clip.mp4 --to mp4 --codec h264 -o plays-everywhere.mp4
jzr video convert clip.mov --to mp4 --resize 720 --fps 30
jzr video mov2mp4 clip                             # pair shorthand; extension optional
jzr video mp42mp3 talk.mp4                         # the sound only
jzr video convert clip.mp4 --to gif                # the GIF `jzr video gif` makes by default

Options: -t/--to, -f/--from, -c/--codec (h264, hevc, av1, vp9), -q/--quality (high, balanced, small; default balanced), --crf N, --resize N, --fps N, --no-audio, -b/--bitrate (audio targets), -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, --overwrite, --dry-run.

  • Each stream is copied when the target container can hold its codec, which is quick and loses nothing (clip.mov -> clip.mp4 (video copied, audio copied)). What does not fit is encoded to the container's default: H.264 and AAC for mp4, mov and mkv, VP9 and Opus for webm.
  • --codec always encodes the video with that codec; the audio is still copied when it fits. A codec the container cannot hold is refused (webm takes vp9 and av1, mov takes h264 and hevc).
  • --quality and --crf set the encoder's constant quality (lower CRF is better and bigger). They only matter when the video is encoded; when it is copied, the result line says so.
  • --resize N scales the short edge down to N pixels (never up, even sizes), and --fps N lowers the frame rate; both make the video encode, unless the source is already that small or slow.
  • Encoded H.264 is 8-bit 4:2:0 so that every player opens it; HEVC in mp4/mov is tagged hvc1 for Apple players. mp4 and mov outputs have their index at the front, so they start playing before they are fully downloaded. An HDR source encoded to H.264 is not tone-mapped and looks washed out; the result line warns about it.
  • Rotation is kept: a copied stream keeps its rotation flag, an encoded one is turned upright.
  • The best video stream and the audio stream with the most channels are used. Other audio tracks, subtitles and cover art are left out, and the result line names them. Tags are kept.
  • An audio target works like jzr audio convert on the video's sound: AAC goes into .m4a untouched, and --bitrate applies. The video options are refused with it, and a video with no audio track fails with no audio track.
  • --to gif (and pairs such as mp42gif) makes the same GIF as jzr video gif with its defaults: the whole video, at most 480 pixels wide and 15 frames a second. The other options are refused with it; jzr video gif is the command with the GIF options.
  • Scanning a directory picks video files (mp4 m4v mov mkv webm avi wmv flv mpg mpeg ts mts m2ts 3gp ogv) that are not already in the target container.
  • A file that cannot be read, or that needs an encoder this ffmpeg build lacks (this ffmpeg build has no libx265 encoder), fails on its own; the rest still convert and the exit code is 1. jzr video formats shows which encoders the build has.
  • --dry-run, the temporary jzr-tmp-... output and the progress line work as in jzr audio convert.

Video compression

jzr video compress makes video files smaller. The output is always MP4 with H.264 and AAC, so it plays everywhere, and is named <name>_compressed.mp4:

jzr video compress clip.mov                        # constant quality, at most 1080p
jzr video compress clip.mov -q small --resize 720
jzr video compress clip.mov --size 25MB            # at or under 25 MB
jzr video compress clip.mov --for discord -o share.mp4
jzr video compress -d ~/Videos -r --for email --outdir small

Options: -q/--quality (high, balanced, small; default balanced), -s/--size SIZE, --for email|discord, --resize N, --no-audio, --strip, -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, --overwrite, --dry-run.

  • Without a size, the video is encoded at constant quality, with the short edge capped at 1080 pixels (--resize N sets another cap; never scaled up). A result that is not smaller than its source is thrown away: skip clip.mp4: already smaller than the result.
  • --size takes decimal sizes (25MB, 8M, 500KB, 1.5GB). The video is encoded in two passes at the bitrate that fills the size, less 4% for the container. The highest resolution of the source (at most 1080p), 720p, 480p and 360p that still has enough bits for each pixel is used, and the audio is 128 kb/s, or 96 kb/s when the size is tight.
  • --for email is 18 MB (mail adds about a third for encoding, so this fits a 25 MB limit) and --for discord is 20 MB, Discord's limit for free accounts.
  • A size that cannot work is refused before anything is encoded, with the smallest that would: too small for a 12:04 video; the smallest is about 42 MB (or use --no-audio). A source already at or under the size is skipped.
  • If the encoder still overshoots, the file is encoded once more at a lower bitrate; if that is still too big, the file fails. A result over the size is never kept, and an existing output is only replaced by a result that fits.
  • AAC audio that is already stereo and no larger than the planned bitrate is copied; other audio is encoded, and surround is mixed down to stereo.
  • Tags such as the title, date and location are kept; --strip leaves every tag out. Apple's com.apple.quicktime.* keys (the device, and the location in iPhone clips) are not written to MP4 by ffmpeg, so they are gone either way. The video is turned upright, so a rotated phone clip needs no rotation flag.
  • A directory scan picks every video file except earlier ..._compressed results. Sources, outputs, --dry-run (both passes are shown), the progress line and failures work as in jzr video convert.

Audio conversion

jzr audio convert turns audio files into mp3, m4a, opus, ogg, flac or wav. It picks its sources and outputs the way jzr image convert does:

jzr audio convert song.wav --to mp3               # one file
jzr audio convert song.wav -o out/song.mp3        # named output; --to not needed
jzr audio convert *.flac --to m4a --outdir m4a
jzr audio convert --to mp3 -d ~/Music -r          # every audio file under a directory
jzr audio wav2mp3 song                            # pair shorthand; extension optional

Options: -t/--to, -f/--from, -b/--bitrate (kb/s, e.g. 128k), -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, --overwrite, --dry-run.

  • When the target can hold the source's codec, the audio is copied, with no quality loss and almost instantly (AAC from an .mp4 or .m4a into .m4a, MP3 into .mp3 under --outdir). Otherwise it is encoded. The result line says which: song.wav -> song.mp3 (audio encoded to mp3).
  • Encoding defaults: MP3 VBR about 190 kb/s, AAC 192 kb/s, Opus 128 kb/s, Vorbis quality 5, FLAC level 5, WAV PCM. FLAC and WAV keep 24-bit sources at 24 bits and write 16 bits otherwise. --bitrate sets the rate of the lossy targets and forces an encode; for flac and wav it prints a note and is ignored.
  • Tags are carried over. Cover art is carried into mp3, m4a and flac; the other formats get none, and the result line says it was dropped.
  • Scanning a directory picks audio files only (mp3 m4a aac opus ogg oga flac wav aif aiff wma mka) that are not already in the target format. A listed video file is accepted too, and its first audio track is converted; jzr video is the place for video work.
  • A file with no audio track, or one ffmpeg cannot read, fails on its own; the rest still convert and the exit code is 1.
  • --dry-run prints the ffmpeg command for each file and writes nothing.
  • Output is written under a temporary jzr-tmp-... name and renamed when ffmpeg succeeds, so a failure or Ctrl+C leaves no partial file and never damages an existing one. On a terminal a progress line is shown on stderr.

Audio tags

jzr audio tags shows and edits the tags of MP3, M4A, FLAC, Ogg Vorbis and Opus files in place. It reads and writes the tags with mutagen, so it needs no ffmpeg and never touches the audio itself.

jzr audio tags song.mp3                                  # print the tags
jzr audio tags *.flac --json                             # one JSON array
jzr audio tags song.mp3 --set "title=Song" -s artist=Band -s track=3/12
jzr audio tags *.mp3 -s album=Record -s year=2020        # same change to every file
jzr audio tags song.m4a --unset comment
jzr audio tags song.opus --clear --set title=Song        # only the title is left
jzr audio tags song.mp3 --cover front.jpg --lyrics words.txt
jzr audio tags song.flac --no-cover
jzr audio tags song.mp3 --export-cover front.jpg
  • Keys: title, artist, album, albumartist, year, track, disc, genre, comment, composer. year is YYYY, YYYY-MM or YYYY-MM-DD; track and disc are N or N/M.
  • Printing shows the format, each tag that is set, the cover (type and size) and how many lines of lyrics there are. A tag with several values is shown joined with ; .
  • -s/--set KEY=VALUE and -u/--unset KEY repeat; --unset lyrics removes the lyrics. --clear removes every tag (including ones outside the list above), the cover and the lyrics, and runs before the other changes.
  • --cover IMAGE embeds a JPEG or PNG (told apart by content, not by name) as the front cover and replaces any picture already there; --no-cover removes the pictures. --lyrics FILE embeds the lyrics from a UTF-8 text file. --export-cover FILE writes the embedded cover out; the name must end in .jpg/.jpeg or .png to match the picture, and an existing file is not replaced.
  • The format is read from the file's content, so a file with the wrong extension is still handled as what it is. MP3 tags are written as ID3v2.3, which Windows Explorer and older players read best.
  • Edits are written to a temporary jzr-tmp-... copy next to the file, which then replaces it, so a failed write leaves the file as it was. A read-only file is refused.
  • Unknown keys, bad values and options that contradict each other are usage errors (exit code 2) and change nothing. A file that cannot be read or written fails on its own; the rest are still handled and the exit code is 1.

Trimming

jzr video trim and jzr audio trim keep a time range of a file and write it beside the source as <name>_trim.<ext>, in the same container or format:

jzr video trim clip.mp4 --start 1:05 --end 1:30          # exact: starts on the asked frame
jzr video trim clip.mp4 --start 1:05 --duration 25 --fast  # instant copy from the keyframe
jzr video trim clip.mov --end 10 -o first-ten-seconds.mov
jzr video trim *.mp4 --start 3 --outdir trimmed           # same cut of every file
jzr audio trim song.flac --start 0:30 --end 2:10.500
jzr audio trim talk.mp3 --start 90 --exact                 # re-encode for a cut to the millisecond

Options: --start TIME (default 0), --end TIME or --duration TIME (default: to the end of the file), --fast (video) or --exact (audio), -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, --overwrite, --dry-run. Times are seconds (90, 7.5) or [H:]MM:SS[.mmm] (1:30, 0:01:30.250).

  • A video cut is exact by default: it starts on the asked frame and lasts the asked time. The video is encoded again at high quality in the source's codec (H.264, HEVC, AV1 or VP9), or in H.264 (VP9 for webm) when there is no encoder for it; the audio is copied. This takes as long as an encode of the cut part.
  • --fast copies the streams instead: instant and lossless, but a cut can only start on a keyframe, so it starts at the keyframe at or before --start and the result line says where: clip.mp4 -> clip_trim.mp4 (video copied, audio copied; starts at 0:05.000, the keyframe before 0:07.000). The end is where you asked, give or take a frame or two, since copied video can only be cut between whole packets. .ogv (Theora) can only be cut with --fast.
  • WAV and FLAC are cut to the sample and stay lossless. MP3, AAC, Opus and Vorbis are cut by copying, with no quality loss and to within one audio frame (about 1/40 s); --exact encodes them again at the source's bitrate for a cut to the millisecond.
  • Tags are kept, and so is cover art (in MP3, M4A, FLAC, Ogg and Opus). The best video stream and the audio stream with the most channels are kept in a video; other audio tracks and subtitles are left out, and the result line names them.
  • --output must keep the source's extension; use jzr video convert or jzr audio convert to change the format. --start, --end and --duration that contradict each other are usage errors (exit code 2). A start past the end of a file fails that file and names its length; an end past it cuts to the end, and the result line says so.
  • Scanning a directory picks video (or audio) files and leaves out earlier _trim results. An audio file given to jzr video trim, or a video given to jzr audio trim, fails on its own, as does any file ffmpeg cannot read; the rest are still cut and the exit code is 1.
  • --dry-run, the temporary jzr-tmp-... output and the progress line work as in jzr audio convert.

GIFs

jzr video gif makes an animated GIF of a video, or of a part of it, and writes it beside the source as <name>.gif:

jzr video gif clip.mp4                                   # the whole clip, 480 px wide, 15 fps
jzr video gif clip.mp4 --start 1:05 --duration 4         # four seconds from 1:05
jzr video gif clip.mov --end 3 --width 320 --fps 10 -o reaction.gif
jzr video gif *.mp4 --outdir gifs

Options: --start TIME (default 0), --end TIME or --duration TIME (default: to the end of the file), --width N (default 480), --fps N (default 15), -d/--dir, -p/--pattern, -r/--recursive, -o/--output, --outdir, --overwrite, --dry-run. Times are written as for jzr video trim.

  • --width is the most the GIF may be wide; a narrower video keeps its size, and the height follows the picture's shape. --fps likewise only lowers the frame rate. A rotated phone video comes out upright.
  • The colours come from a palette made for the clip in the same ffmpeg run, so no palette file is written. The GIF loops forever and has no sound.
  • GIFs grow fast. There is no length limit, but a GIF longer than 30 seconds gets a note with the range of sizes to expect (long GIF (0:45): expect a few to tens of MB; ...); a shorter part, a smaller --width or a lower --fps makes it smaller.
  • The range works as in jzr video trim: contradicting times are usage errors (exit code 2), a start past the end of a file fails that file, and an end past it stops at the end. A file without a video track (an audio file) fails on its own, as does any file ffmpeg cannot read; the rest are still made and the exit code is 1.
  • --dry-run, the temporary jzr-tmp-... output and the progress line work as in jzr audio convert.

Ports

See what is using a port, then free it:

jzr port show              # every listening TCP port and its process
jzr port show --udp        # ...and bound UDP ports too
jzr port show 3000 8080    # every socket on these ports
jzr port show --json       # for scripts
jzr port kill 3000
jzr killport 3000 8080     # shortcut for `jzr port kill`, several ports at once

Without a port, jzr port show prints a table sorted by port. A process that listens on the same port over IPv4 and IPv6 gets one row:

PORT  PROTO  PID    NAME         ADDRESS
135   TCP    1700   svchost.exe  0.0.0.0, [::]
445   TCP    4      System       0.0.0.0, [::]
3000  TCP    18472  node.exe     127.0.0.1

With ports, it prints one line per socket with the PID, name, protocol, local address and state. --json prints one array of sockets in both cases, each with port, protocol, address, pid (null when unknown), name and status (null for UDP). port show changes nothing.

jzr port kill force-kills all visible processes bound to the exact local port, for TCP and UDP over IPv4 and IPv6. Works on Windows, Linux, and macOS using psutil, installed with the toolkit. On Unix this sends SIGKILL; on Windows it uses TerminateProcess. Remote connections to the port are not targeted, and unrelated child processes are not killed. There is no confirmation prompt.

Ports must be between 1 and 65535. Give several ports to free them in one call; a process holding more than one of them is killed once and reported for each. The command prints each killed PID and returns success if no process or Windows port exclusion is found; a failure on one port does not stop the others. Permission errors or processes that do not exit produce a nonzero exit code, while other matching processes are still attempted. Processes that restart automatically may reclaim the port.

Use an Administrator terminal on Windows or sudo jzr killport 3000 on Unix when permissions prevent inspection or termination. macOS requires root for system-wide socket inspection; Linux may omit sockets without sufficient permissions (see the psutil documentation).

Windows excluded ports (EACCES)

Windows can reserve a port even when no process is listening. jzr killport checks active TCP/UDP exclusion ranges for IPv4 and IPv6, prints matching ranges, and returns a nonzero exit code when the port is excluded. This explains cases such as Next.js reporting listen EACCES: permission denied 0.0.0.0:3000 while no port owner is visible.

Choose an unreserved port, or try your HNS recovery workflow from an Administrator terminal:

jzr killport 3000 --restart-hns

The flag stops and starts the Host Network Service only when an exclusion is detected. This can interrupt Docker, containers, and WSL networking. The command rechecks all exclusion ranges and tests local binds afterward; it fails if the port is still unavailable. With several excluded ports, HNS is restarted once. A restart is not guaranteed to clear a reservation, and Windows may reserve the port again later. Administered exclusions (*) are reported without restarting HNS. The command does not delete reservations or change dynamic port ranges. Linux and macOS reject --restart-hns.

Host status

See what the machine is and how busy it is:

jzr host status                 # host, CPU, memory, storage, GPU
jzr host status --detail        # plus per-core usage, swap, every mount, network, sensors
jzr host status --live          # keep refreshing until Ctrl+C
jzr host status --live -n 0.5   # refresh every half second
jzr host status --json          # everything, for scripts
╭─ fedora ──────────────────────────────────────────────────────╮
│  Fedora Linux 42 (Workstation Edition)  x86_64  up 4h 30m     │
├─ CPU ─────────────────────────────────────────────────────────┤
│  12th Gen Intel(R) Core(TM) i7-12700  (12 cores, 20 threads)  │
│  Usage      ████░░░░░░░░░░░░░░░░   19%                        │
│  Load       1.94  2.13  2.32                                  │
├─ Memory ──────────────────────────────────────────────────────┤
│  RAM        ██████████████░░░░░░   70%     21.8 / 31.1 GiB    │
├─ Storage ─────────────────────────────────────────────────────┤
│  /          ████████████████░░░░   81%   363.5 / 451.6 GiB    │
│  /boot      ██████████░░░░░░░░░░   48%   430.6 / 973.4 MiB    │
├─ GPU ─────────────────────────────────────────────────────────┤
│  NVIDIA GeForce RTX 4080                                      │
│  Usage      ██████░░░░░░░░░░░░░░   31%                        │
│  Memory     █████░░░░░░░░░░░░░░░   25%      4.0 / 16.0 GiB    │
│  Temp       63°C                                              │
│                                                               │
│  Intel UHD Graphics 770                                       │
╰───────────────────────────────────────────────────────────────╯

Works on Windows, Linux and macOS using psutil, installed with the toolkit. Anything a system does not expose is left out of the text and is null in JSON; the command still exits 0.

Options: -l/--live, -n/--interval SECONDS (default 2, minimum 0.2, only with --live), -d/--detail, --json.

Behavior worth knowing:

  • CPU usage is measured over a quarter of a second for a single reading, and over the whole interval for each --live refresh.
  • Memory "used" is total minus available, so cache the system can give back does not count as used.
  • Storage lists each device once, at its shortest mount point; --detail lists every mount with its device, filesystem and free space. Loop devices and snap images are never listed.
  • GPUs: NVIDIA cards are read through nvidia-smi on every system (usage, memory, temperature, and in --detail driver and power). On Linux, AMD cards report the same through the kernel, and Intel cards are listed by name. On Windows and macOS other adapters are listed by name only, because neither system offers a simple way to read their usage.
  • Load average is not shown on Windows, which has none. Temperatures come from the kernel's sensors and are only available on Linux.
  • --json always carries everything, with or without --detail. Sizes are bytes, percentages run 0-100, and times are ISO 8601. With --live it prints one compact JSON document per line.
  • --live redraws in place on a terminal and leaves the last reading on screen when you stop it. Piped to a file, readings are appended one after another.
  • Colour is used only on a terminal, and never when NO_COLOR is set.
  • The frame is drawn with box characters. Where the output cannot show them (a redirected stream on Windows, an ASCII locale) it falls back to +, -, | and [####....] bars.
  • On a terminal the report never exceeds the window: lines that do not fit are cut with …, and --live also stops at the window's height. Piped output is never cut.

Linux and Windows 11 (with an NVIDIA card) have been run on real hardware. The macOS code path, AMD GPU readings and battery reporting are covered by tests on recorded sample output only.

Host clean

Find what can be deleted to get disk space back, tick what should go, confirm:

jzr host clean                    # scan, pick from a checkbox list, confirm, remove
jzr host clean --dry-run          # only look: what was found and what would be done
jzr host clean --yes              # no questions: remove everything that is safe to remove
jzr host clean --only uv,pip      # just these items (asks once; add --yes to skip that)
jzr host clean --json             # the scan, for scripts; removes nothing
? What should be removed? (Use arrow keys to move, <space> to select, <a> to toggle, <i> to invert)
   Safe to remove
 » ● uv cache                         24.1 GiB
   ● Docker build cache               19.9 GiB
   ● pip cache                        15.6 GiB
   Review first
   ○ Docker images no container uses  35.3 GiB
   ○ Trash                             4.2 GiB
  Description: Packages are downloaded and built again when needed. Runs: uv cache clean
? Remove 3 items, about 59.6 GiB? (y/N)

What it looks for on Linux:

Tier Items Ticked by default
Safe to remove Docker build cache; uv, pip, npm, Cargo, Yarn, pnpm, Go build, node-gyp, Mesa shader and thumbnail caches yes
Review first Trash; stopped Docker containers; Docker images no container uses; any other folder of 100 MiB or more in ~/.cache (listed as cache:<name>) no
Needs root systemd journal beyond the newest 500 MiB; the dnf or apt package cache no

And on Windows, mostly under %LOCALAPPDATA%:

Tier Items Ticked by default
Safe to remove Docker build cache; uv, pip, npm, Cargo, Yarn, pnpm, Go build and node-gyp caches; the graphics drivers' shader caches (NVIDIA, AMD, Intel, Direct3D) yes
Review first Temp files (%TEMP%, SquirrelTemp); crash dumps; the Recycle Bin; Docker containers and images; other large folders in ~/.cache no
Needs administrator C:\Windows\Temp; Windows Update downloads no

The ids for --only are the same everywhere (jzr host clean --only x with an id the other system has prints x: nothing to remove). GOCACHE, YARN_CACHE_FOLDER, UV_CACHE_DIR, PIP_CACHE_DIR, npm_config_cache and CARGO_HOME move a cache on either system.

Behavior worth knowing:

  • Nothing is removed before you confirm, and --dry-run and --json never remove anything. --yes on its own removes the safe tier only; anything else has to be ticked or named with --only.
  • It only looks in known places. It does not hunt for "temporary-looking" files, and it never offers Docker volumes, project folders or /tmp.
  • Where a tool has its own clean-up command it is used (uv cache clean, npm cache clean --force, docker builder prune --all --force, journalctl --vacuum-size=500M, dnf clean all); otherwise the cache folder is emptied and kept. --dry-run shows which.
  • Root items run through sudo, which asks for your password itself. With --yes they run as sudo -n and fail instead of asking.
  • On Windows, administrator items are offered in an elevated terminal, or when Windows sudo is turned on; then jzr runs itself through sudo for them and measures again afterwards. With --yes and no elevation they fail instead of raising a prompt nobody answers. C:\Windows\Temp cannot be read without elevation, so it shows up only in an elevated terminal.
  • On Windows, files a program still has open cannot be deleted; they are left in place and counted (Temp files: removed 8.0 GiB; 31 files in use were kept), and the item still counts as cleaned. Read-only files are removed.
  • The Recycle Bin is sized and emptied through the Windows shell, on every drive at once.
  • Sizes are estimates. The uv cache shares files with your environments, so less may come back than shown; the last line reports the free space before and after.
  • Symbolic links (and Windows junctions) are never followed, and a link inside ~/.cache is never offered as a cache.
  • On Windows a hard-linked file counts once per link: Windows does not report link counts while listing a folder, and asking per file made sizing the uv cache ten times slower.
  • A scan of a large cache takes a while (about 25 seconds here for 68 GiB).
  • Without a terminal it refuses to guess: pass --dry-run, --json or --yes.
  • Exit code 1 means something could not be removed (the rest still was) or the list was cancelled.

Removal has been run against throwaway folders only, on Linux and Windows; the Docker, sudo, journal, dnf and apt commands, the Recycle Bin and Windows sudo are covered by tests with them faked and have not been run for real. The Windows scan has been run on a real machine.

Host procs

See what is using memory, by application, and optionally end some of it:

jzr host procs                  # the 15 biggest applications
jzr host procs chrome           # only rows whose name or command line contains "chrome"
jzr host procs --each -n 30     # single processes, with PID and command line
jzr host procs --kill           # tick rows, confirm, and end them
jzr host procs --kill --force   # ...and force-kill whatever ignores the request
jzr host procs --json           # for scripts
╭─ Memory ───────────────────────────────────────────────╮
│  RAM   ██████████████░░░░░░   72%   22.3 / 31.1 GiB    │
│  Swap  ████████████████████  100%     8.0 / 8.0 GiB    │
├─ Applications (5 of 166) ──────────────────────────────┤
│  Application         Procs    Memory       Swap  User  │
│  qemu-system-x86_64      1   3.4 GiB   36.1 MiB  sam   │
│  pycharm                 1   2.9 GiB  263.3 MiB  sam   │
│  msedge                 29   2.4 GiB  577.4 MiB  sam   │
│  node                   40   2.0 GiB    2.0 GiB  sam   │
│  claude                  4   1.1 GiB   86.9 MiB  sam   │
├─ Total ────────────────────────────────────────────────┤
│  Top 5                  75  11.8 GiB    2.9 GiB        │
│  All 166               354  17.1 GiB    6.7 GiB        │
│  Outside processes           5.2 GiB    1.3 GiB        │
│  In use                     22.3 GiB    8.0 GiB        │
╰────────────────────────────────────────────────────────╯

Behavior worth knowing:

  • A row is every process of one user running the same program, so a browser is one line. All scripts run by the same interpreter also share a line; use --each to tell them apart.
  • Memory and swap are each process's fair share of what it uses (pages shared by several processes are split between them), so the numbers add up. For other users' processes only the plain resident size is readable.
  • The Total section adds up the Procs, Memory and Swap columns. Top N is the rows in the table; All M is everything that matched, including what --top left out (only All M appears when nothing was left out).
  • Outside processes is what the machine has in use that belongs to no process: the kernel's own memory, shared memory, and cache it does not count as free. All plus Outside processes gives In use, the same figures as the bars at the top. Both rows are left out when you filter with a pattern, because the sums then cover only what matched.
  • The report uses the same frame as jzr host status: plain + - | characters where the output cannot show boxes, and cut to the window's width on a terminal. A protected row ends with the reason, such as (system) or (this terminal).
  • --kill ticks nothing for you. Processes are first asked to exit; after 5 seconds it asks whether to force-kill what is left (--force skips that question). Only the processes listed are signalled, not their children.
  • It will not end this terminal (the jzr process and its parents), other users' processes, or the session itself: systemd, the desktop shell, the display server, the sound and message services, sshd. A group that contains one of these can still be ticked; the protected ones are kept.
  • --kill needs a terminal. For scripted killing use pkill.
  • Exit code 1 means a process could not be ended or is still running.

On Windows:

  • "Asked to exit" means each chosen program's windows are told to close, as clicking their X would, so it can save or ask you first. A program without a window cannot be asked, so it goes straight to the force-kill question. Force-killing is TerminateProcess.
  • Windows keeps no per-process share of the page file, so the table has no Swap column and --json gives null for it. The Swap bar at the top is the page file.
  • Protected as (system): services and anything owned by NT AUTHORITY, and the shell and log-on processes (explorer.exe, dwm.exe, csrss.exe, winlogon.exe, sihost.exe, svchost.exe and the like).

Tried on Linux and Windows 11; ending processes only on throwaway child processes.

Bind

Save a long command under a short name, then run it as jzr <name>:

jzr bind add tunnel ngrok http 5173 --url https://example.ngrok-free.dev
jzr tunnel                     # runs the command
jzr tunnel --log stdout        # anything after the name is added to it
jzr bind list
jzr bind remove tunnel

The command can also be given as one quoted string; both forms store the same thing:

jzr bind add tunnel "ngrok http 5173 --url https://example.ngrok-free.dev"

Other commands: jzr bind add --force NAME ... replaces an existing shortcut, jzr bind run NAME is the long way to run one, jzr bind path prints where they are stored, and jzr bind list --json is for scripts.

Behavior worth knowing:

  • The command runs directly, without a shell, so it behaves the same on Linux, macOS and Windows. The price: no pipes, &&, $VARIABLES or ~. One shortcut is one command.
  • Everything after the name belongs to the command, including --options, both when binding and when running. --force therefore goes before the name, and jzr tunnel --help shows ngrok's help, not jzr's.
  • Built-in commands always win. jzr bind add host ... is refused, and if a later version of jzr adds a command with the name of one of your shortcuts, jzr bind list marks it and jzr bind run NAME still reaches it.
  • Names start with a letter or digit and may contain letters, digits, ., _ and -.
  • The exit code is the command's own. Ctrl+C goes to the command, and jzr waits for it to finish. A program that is not installed gives exit 127.
  • Shortcuts live in bindings.json in jzr's config folder: ~/.config/jzr (or $XDG_CONFIG_HOME/jzr), %APPDATA%\jzr on Windows, or wherever JZR_CONFIG_DIR points. It is plain JSON that you can edit or copy to another machine. It is only readable by you, but anything in it, tokens included, is stored as plain text.
  • A bindings file that is damaged is reported and never overwritten.
  • jzr -h does not list your shortcuts; jzr bind list does.

On Windows:

  • What you type reaches the command as typed: $HOME, %PATH%, ~ and *.txt are not expanded by jzr (other jzr commands do expand wildcards, since cmd and PowerShell leave that to the program).
  • One quoted string is split by Windows rules: double quotes group words and backslashes in paths are kept; single quotes are ordinary characters. jzr bind list writes commands back the same way.
  • Programs that are .cmd or .bat files, such as npm, pnpm and yarn, have to run through cmd.exe. jzr quotes every argument so &, |, < and > stay literal, and refuses to run one with %, ", ! or a line break in it, which cmd.exe would act on whatever the quoting.

Tried on Linux and Windows 11.

Text

Turn text into a lowercase kebab-case slug:

jzr text slug "ApiSix deployment Notes"         # api-six-deployment-notes
jzr text slug "ApiSix deployment Notes" --date  # 2026-11-15_api-six-deployment-notes
jzr text slug "ApiSix deployment Notes" -c      # ...and copy it to the clipboard
jzr text slug "myVarName" -s _                  # my_var_name
jzr text slug "Read Me" --preserve-case         # Read-Me

Omit the text argument to paste or pipe multiline content. Runs of spaces, newlines, and punctuation collapse into one separator, and camelCase or PascalCase words are split (HTTPServer becomes http-server). The date prefix is always followed by _. jzr text kebab is the same command under its old name.

The result is ASCII. Accented Latin letters lose their accents, Russian and Uzbek Cyrillic are transliterated (Привет мир becomes privet-mir), and letters such as ß and ø are spelled out. Other scripts are dropped; if nothing is left, the command exits 1 instead of printing an empty result.

Shell completion

jzr completion SHELL prints a script that makes Tab complete commands, options and choices. Load it from your shell's start-up file:

echo 'eval "$(jzr completion bash)"' >> ~/.bashrc
echo 'eval "$(jzr completion zsh)"' >> ~/.zshrc
jzr completion fish > ~/.config/fish/completions/jzr.fish
Add-Content $PROFILE 'jzr completion powershell | Out-String | Invoke-Expression'

Open a new shell afterwards. File arguments fall back to the shell's own path completion. Your jzr bind shortcuts are not completed. Windows PowerShell 5.1 does not offer completions for a bare - or --; type the first letter of the option.

Contributing

Pull requests are welcome. See CONTRIBUTING.md for how a tool is laid out, how to add one and how to run the tests.

License and credit

jzr-tools is created by JZR SUPOVE and released under the Apache License 2.0. You may use, change and redistribute it, including in commercial products. When you redistribute it or a work based on it, keep the NOTICE file with its credit line, as section 4 of the license asks.

Metadata

Release files for jzr-tools 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jzr-tools 0.1.0
File Size Uploaded Provenance Actions
jzr_tools-0.1.0.tar.gz 415.6 kB With provenance Details for jzr_tools-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jzr-tools 0.1.0
File Interpreter ABI Platform Actions
jzr_tools-0.1.0-py3-none-any.whl Python 3 none any Details for jzr_tools-0.1.0-py3-none-any.whl

Total release size: 574.8 kB

Release files / jzr_tools-0.1.0.tar.gz

Download URL jzr_tools-0.1.0.tar.gz
Size 415.6 kB
Tags Source
SHA-256 checksum
How to use checksums
9efe111a563cdf37fe1cc1f20a3478695e9f68ba30323b7d98eb7a0debc91ace
BLAKE2b-256 checksum
How to use checksums
6ff4d55c9594428f4f239d55dcab7153fbf341eae11053b2e93c31973c7b00e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / jzr_tools-0.1.0-py3-none-any.whl

Download URL jzr_tools-0.1.0-py3-none-any.whl
Size 159.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f795cb9f08077b8eb91329540678dc2dbc2d2bb87bf83728cf0453c584f11acb
BLAKE2b-256 checksum
How to use checksums
8a1386afadc7cc160f97b891d6e95b99f47ebc82d50e1ca3ba61cb181e047601
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for jzr-tools 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jzr_tools-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page