Getting Started - Hook

Hook Docs / Getting Started

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:

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 show-version # print the version stored in version.txt
make bump-version # raise it by one (the only target that changes it)

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. It changes only with make bump-version, which raises the last part by one (make bump-version VERSION=1.2.0 stores that exact value instead); make show-version prints it. No build changes it: make deb, make appimage, make installer-windows and make docker-build package the stored version, so a release is: bump, commit, build.

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, -liphlpapi, -lbcrypt).

Windows, cross-compiled on Linux

hook.exe and its setup file can also be built on Linux, with no Windows machine involved. Install the posix-threads mingw-w64 toolchain, cmake and NSIS (Debian: gcc-mingw-w64-x86-64-posix, cmake, nsis), then:

make windows-deps       # once: build the Windows libraries
make windows            # hook.exe and its DLLs in dist/windows/Hook
make windows-installer  # dist/hook-<version>-setup.exe

make windows-deps downloads the prebuilt Allegro release for mingw and builds zlib, pcre2, libyaml, OpenSSL, libssh2 and libgit2 from source into external/mingw/. Like the other packaging targets, make windows-installer grows the version by one first.

Windows: the signature

hook.exe, the DLLs beside it and the setup file are signed by NiloreaStudio with a self-signed certificate. Windows shows such a signature as not trusted, and SmartScreen still warns, until the certificate is installed on the machine. That is optional: Hook runs the same without it. The certificate is NiloreaStudio.cer, in the folder Hook is installed in. The README section “Windows: the signature” gives its SHA-256 fingerprint to compare first, the certutil commands that install and remove it, and how a build is signed (WIN_SIGN, and the key in ~/.config/nilorea/signing, which a build never creates: without it the build is unsigned).

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:

Resizing the panes

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

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

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