Start in the terminal.

Requirements

• macOS on Apple Silicon (arm64), including M1 and newer Macs
• A compatible model from Ollama, a local GGUF file, or a public GGUF URL
• HTTP range-request support when using a remote model URL

Not supported yet: Intel Macs (x86_64), Windows, and Linux. To check your Mac, run uname -m. A supported Mac prints arm64.

The current build is unsigned and has not been notarized by Apple.

Install

Review the installer before running it:

curl -fsSL https://raw.githubusercontent.com/imruljubair/byhand/main/install.sh

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/imruljubair/byhand/main/install.sh | sh

The default location is /usr/local/bin/byhand. To install without administrator permission:

mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/imruljubair/byhand/main/install.sh \
  | BYHAND_INSTALL_DIR="$HOME/.local/bin" sh

If necessary, add that directory to your shell path:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$HOME/.zprofile"
source "$HOME/.zprofile"

Quick start

Use this known-working public Llama 3.2 GGUF for the fastest first run. This method does not require Ollama or a local model download.

byhand model --url https://huggingface.co/tensorblock/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q2_K.gguf

The terminal visualization opens after byhand reads the model metadata and tensor descriptors.

Choose a model source

Public GGUF URL—recommended for first-time users

No Ollama installation or local GGUF download is required. To get a URL from Hugging Face:

1. Open a model repository and select Files and versions.
2. Choose a file whose name ends in .gguf.
3. Open the file and copy its direct download link.
4. Pass that URL to byhand model --url.

byhand model --url DIRECT_GGUF_URL

The file must be public, and its server must support HTTP range requests.

Ollama model

Installing Ollama does not install a model automatically. Install Ollama, pull a supported model, and then open it with byhand:

ollama pull llama3.2
ollama list
byhand model --ollama llama3.2

Local GGUF file

Use this method when you already have a compatible GGUF file on disk:

byhand model /path/to/model.gguf

Help and version

byhand
byhand model --help
byhand --version

Model availability is determined from GGUF metadata, not the filename, Ollama repository name, or input source.

Supported models

The current release supports Llama-family GGUF architectures. Support is determined from the architecture stored in GGUF metadata, not the model filename or source.

HTML export

byhand model --ollama llama3.2 --output html

HTML is an optional extension of the terminal-first workflow. Use it when you want to share a visualization or explore it on a larger canvas. The exported file contains every model step and Operation Explainer and opens without a web server or external dependencies.

Full is the default Explainer layout. Select Side before opening the Explainer to keep the model visible beside it, or above it on narrow screens.

Excel export

byhand model --ollama llama3.2 --output excel

When --step is omitted, Excel export includes the complete model pipeline. The workbook uses named ranges and native formulas such as MMULT, so each calculated output flows into the operations that follow it.

Pass --step N to stop the workbook at a specific operation:

byhand model --ollama llama3.2 --output excel --step 10

The file is written to the current directory using the model reference as its name, such as llama3.2.xlsx.

Update

byhand checks for a newer stable release at most once every 24 hours and asks before downloading. You can also check or update explicitly:

byhand update --check
byhand update
byhand update --yes

Downloaded updates are verified against the release's SHA256SUMS before the executable is replaced. Set BYHAND_NO_UPDATE_CHECK=1 to disable automatic checks.

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/imruljubair/byhand/main/install.sh \
  | BYHAND_VERSION=v0.5.1 sh

Uninstall

For the default installation:

sudo rm /usr/local/bin/byhand

For a user installation:

rm "$HOME/.local/bin/byhand"

Troubleshooting

Command not found

Confirm the installation directory is included in your PATH. User installations normally use $HOME/.local/bin.

Ollama model not found

Installing Ollama is only the first step. Confirm the model is installed locally, pull it if necessary, and try again:

ollama list
ollama pull llama3.2
byhand model --ollama llama3.2

This Mac is not supported

Run uname -m. The current release requires arm64, which identifies an Apple Silicon Mac. An x86_64 result identifies an unsupported Intel Mac.

Model architecture is unsupported

The current release supports Llama-family GGUF architectures. Qwen and other non-Llama architectures are not supported yet. See Supported models for tested families.

Remote URL does not open

The server must make the GGUF file publicly available and support HTTP range requests. Version 0.5.1 uses the certificate authorities bundled with the standalone binary for reliable HTTPS access, grows range sizes to reduce round trips, and shows live metadata-fetch progress.

Updating version 0.3.0

That release did not include its CA certificate bundle correctly. Use the macOS system bundle for the one-time update:

SSL_CERT_FILE=/etc/ssl/cert.pem byhand update