Getting Started

What is Hook

Hook is a graphical HTTP/HTTPS API client written in C99. It runs as a native desktop application on Linux and Windows. Collections are stored as JSON files on disk. There is no cloud component and no account is needed.

Hook has two modes:

• GUI mode: a windowed application for interactive use.
• CLI mode: headless execution for automation and CI.

Dependencies

Linux (Debian / Ubuntu)

Install the build toolchain and libraries:

sudo apt-get install build-essential
sudo apt-get install liballegro5-dev
sudo apt-get install libssl-dev libpcre2-dev libgit2-dev zlib1g-dev libyaml-dev
sudo apt-get install doxygen graphviz cppcheck

The Nilorea C Library must be present at ../../nilorea-library/ relative to the Hook source directory. Nilorea is compiled from source by the Hook Makefile; it is not linked as a shared library.

QuickJS (the JavaScript engine for scripting) is bundled in the quickjs/ subdirectory and compiled from source automatically. No separate installation is needed.

Windows (MSYS2 MinGW-w64)

Open an MSYS2 MinGW64 shell and install:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make
pacman -S mingw-w64-x86_64-allegro
pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-pcre2
pacman -S mingw-w64-x86_64-libgit2 mingw-w64-x86_64-zlib mingw-w64-x86_64-libyaml
pacman -S mingw-w64-x86_64-doxygen mingw-w64-x86_64-graphviz

Building

Linux

make              # build the hook binary
make test         # compile and run all tests
make doc          # generate Doxygen HTML documentation
make check        # run cppcheck static analysis
make clean        # remove build artifacts
make appimage     # build dist/hook-<version>-x86_64.AppImage
make deb          # build dist/hook_<version>_amd64.deb (self-contained)
make docker-build # portable .deb + AppImage in a Debian 13 container
make bump-version # grow version.txt by one

The binary is produced at ./hook in the project root.

make docker-build is the release path: it wraps packaging/docker-build.sh, which builds both Linux artifacts inside a Debian 13 “trixie” (glibc 2.41) container so they run on Debian 13+, Ubuntu 25.04+ and other distributions shipping glibc 2.41 or newer, and tags them with the container’s Debian codename (hook_<version>-trixie_amd64.deb) to set them apart from the generically named local builds. It needs docker (or DOCKER=podman) and the sibling nilorea-library source tree. SUITE=bullseye builds against an older base for a wider glibc reach, at the cost of a .deb Depends list that names trixie packages.

The version lives in version.txt (format MAJOR.MEDIUM.MINOR) and is the single source of truth: the Makefile generates src/hook_version.h from it and stamps it into the .deb control file and into the .deb, AppImage and Windows setup file names. Each packaging build (make deb, make appimage, make installer-windows) grows it by one first, so every artifact carries its own version; a plain make never changes it. Pass VERSION=1.2.0 on the make command line to set an explicit version instead of incrementing.

The .deb package installs Hook under /opt/hook (binary, default data, bundled libraries and the HTML documentation), adds a hook launcher to /usr/bin, and creates two desktop menu entries: Hook (the application) and Hook Documentation (opens the packaged HTML docs). Like the AppImage, an installed Hook keeps user data in ~/.local/share/hook/ and its configuration in ~/.config/hook/, seeded from the packaged defaults on first run.

Windows

From an MSYS2 MinGW64 shell:

make              # Makefile auto-detects OS=Windows_NT
make test
make doc

The Makefile includes Makefile.windows on Windows, which adds the Windows-specific link flags (-lws2_32, -lwinmm, -lgdi32, -lcrypt32).

Running for the first time

GUI mode

./hook

On Linux you can also run ./hook.sh which sets sanitizer suppression options for third-party library leaks.

The main window opens with:

• A left column showing the collection tree. Below the tree are four buttons (+ Folder, + Subfolder, Rename, Delete) that edit the active collection in place. Below those buttons is a history listbox showing recent requests; clicking an entry restores the full request state (URL, method, params, headers, body, auth, scripts, settings) into the editor. Two buttons under the list remove history: Clear Line drops the selected entry (it stays disabled until you select one) and Clear All drops every entry. Both ask for confirmation and update the history file on disk.
• A request editor on the right with tabs for Params, Headers, Body, Auth, Scripts, and Settings.
• A response panel below the request editor showing status, headers, body, the timing waterfall and the activity log.

Resizing the panes

Three draggable dividers set how the space is shared. The pointer turns into a resize cursor over one:

• between the left column and the right part (vertical),
• between the collection tree and the history list (horizontal),
• between the request editor and the response panel (horizontal).

Drag a divider to give one pane more room; each pane stops at a minimum size so it can never be collapsed out of reach. When the collection tree or the history list is too narrow for its longest line, a horizontal scrollbar appears along the bottom of that list so the rest of the line stays reachable. The positions are saved in hook.conf when Hook exits and restored on the next start, and they scale with the window, so a maximised window keeps the same proportions.

Both lists keep your place across a refresh: the collection tree keeps its unfolded folders, its selection and its scroll position when a save reloads the collection, and the history list keeps its scroll position and selection when a request completes, unless it was already scrolled to the bottom, where it keeps following the newest entry.

Tooltips

Resting the pointer on a control for a moment shows a tooltip explaining what it does: what a button acts on, what a field expects, what a checkbox changes. Empty text fields also carry a dimmed hint showing the shape of the value they want, which disappears as soon as you type.

The delay before a tooltip appears is the “Tooltip delay (ms)” field in the Settings tab (600 ms by default, kept between 100 and 5000). Setting it to 0 turns tooltips off. The value applies immediately and is saved in hook.conf.

To send your first request:

1. Select a method (GET, POST, etc.) from the method dropdown.
2. Type a URL in the URL field (focused by default at startup), for example https://httpbin.org/get.
3. Click the Send button or press Enter while the URL field has focus.
4. The response appears in the response panel with status code, elapsed time, headers, and body.

CLI mode

./hook run -f collection.json
./hook export -f collection.json

CLI mode requires a collection JSON file. See the CLI Reference for all available subcommands.

Keyboard shortcuts

• Enter in the URL field: send the current request.
• Ctrl+S: save the request you are editing. If it came from a folder in the active collection it is written straight back into that slot; otherwise the Save-in-Collection popup opens so you can pick a destination. It works with the cursor in any field, and does nothing while the Save-in-Collection popup is already open (use its own Save button there).
• Escape: close the frontmost (focused) popup. If no popup is open, show the quit confirmation dialog.
• Window close button (X): show the quit confirmation dialog instead of quitting immediately.
• Y / N (when the quit dialog is visible): confirm (Yes) or cancel (No) the quit.

Opening a popup (mock server, SSE, WebSocket, Git, collection/environment editor, import, etc.) brings it to the front and gives it keyboard focus, so you can start typing right away, and Escape closes that popup first.

Test CA certificate

Some tests use a self-signed CA. Generate it with:

make fixtures

This creates tests/fixtures/test-ca.pem.

Next steps

• Requests - learn how to compose HTTP requests.
• Collections - organize requests into files.
• CLI Reference - automate Hook from the terminal.