Documentation

Start in the terminal.

No new interface or setup-heavy workspace. Install byhand, open a compatible model, and step through its architecture where you already work.

Requirements

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

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"

Use

The terminal visualization is the default. Run one command, then navigate the model without switching to another application.

Ollama model

byhand model --ollama llama3.2
byhand model --ollama tinyllama

Local GGUF file

byhand model /path/to/model.gguf

Public remote GGUF file

byhand model --url https://example.com/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.

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.

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.4.3 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

Make sure Ollama is running and the requested model is already installed locally.

Remote URL does not open

The server must make the GGUF file publicly available and support HTTP range requests.

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