Configuration Reference - Hook

Hook Docs / Configuration Reference

Configuration Reference

hook.conf

The main configuration file is hook.conf, a JSON file that is auto-loaded at startup and auto-saved on exit.

The location of hook.conf depends on how Hook is running:

Mode hook.conf location
Linux (development / portable) Same directory as the hook binary
Linux (AppImage) ~/.config/hook/hook.conf (or $XDG_CONFIG_HOME/hook/)
Windows %APPDATA%\Hook\hook.conf

In development mode (no AppImage), all files live next to the binary. In AppImage mode, user data (collections, environments, etc.) is stored in ~/.local/share/hook/ (or $XDG_DATA_HOME/hook/).

Fields

Field Default Description
default_timeout 0 Request timeout in milliseconds. 0 = no timeout.
default_tls_verify 1 1 = verify TLS certs, 0 = skip.
default_follow_redirects 1 1 = follow 3xx redirects automatically.
default_max_redirects 10 Maximum number of redirects to follow.
default_connect_timeout 0 TCP connect timeout in milliseconds.
default_retry_count 0 Number of retries on failure/5xx.
default_retry_delay 1000 Delay between retries in milliseconds.
default_compressed 0 1 = request gzip/deflate compression.
default_user_agent (none) Default User-Agent header string.
proxy_enabled 0 1 = use global proxy.
proxy_url (none) Proxy URL (http://, https://, or socks5://).
no_proxy (none) Comma-separated hosts to bypass proxy.
tls_client_cert (none) Client certificate file path (mTLS).
tls_client_key (none) Client private key file path (mTLS).
cookie_jar_enabled 0 1 = enable cookie jar.
cookie_jar_path (none) Cookie jar file path (Netscape format).
curl_custom_enabled 0 1 = use custom curl binary path.
curl_path (none) Custom curl binary path. Empty = system PATH.
custom_ca_files [] Array of PEM CA file paths. Max 32.
git_enabled 0 1 = enable Git integration. Requires libgit2.
git_author_name (none) Author name for Git commits.
git_author_email (none) Author email for Git commits.
git_auto_stage 0 1 = auto-stage on save.
git_auto_commit 0 1 = auto-commit after staging.
git_repo_url (none) Remote repository URL.
git_branch (none) Target branch name.
git_remote_auth_type 0 0=None, 1=Token, 2=Basic, 3=SSH.
git_token (none) Personal access token (auth type 1).
git_ssh_key_path (none) SSH private key path (auth type 3).
git_remote_user (none) Username for basic auth (auth type 2).
git_remote_password (none) Password for basic auth (auth type 2).
git_pull_check_interval 0 Remote fetch interval in minutes (0=disabled, max 180).
history_max_entries 200 Max history entries in memory and on disk (min 200).
theme_id 0 Active theme: 0=Dark, 1=Light, 2=Solarized Dark, 3=High Contrast.

Example hook.conf

{
  "default_timeout": 30000,
  "default_tls_verify": 1,
  "default_follow_redirects": 1,
  "default_max_redirects": 10,
  "default_compressed": 1,
  "default_user_agent": "Hook/1.0 (API Client)",
  "proxy_enabled": 0,
  "cookie_jar_enabled": 1,
  "cookie_jar_path": "cookies.txt",
  "git_enabled": 1,
  "git_author_name": "Jane Developer",
  "git_author_email": "jane@example.com",
  "git_repo_url": "git@github.com:user/api-collection.git",
  "git_branch": "main",
  "git_remote_auth_type": 3,
  "git_ssh_key_path": "/home/jane/.ssh/id_ed25519",
  "curl_custom_enabled": 0,
  "curl_path": ""
}

Directory structure

In development / portable mode, all files live in one directory:

project/
  hook.conf                  Application configuration (JSON)
  cookies.txt                Cookie jar (Netscape format, if enabled)
  collections/
    my-api.json              Collection files
    another-api.json
  environments/
    dev.json                 Environment files
    staging.json
    production.json
  mock-routes/
    routes.json              Mock server route definitions
  scripts/
    pre-request.hook         Script files
    post-request.hook
  user-agents/
    chrome.json              User-Agent preset files
    curl.json
  history/
    hook.ndjson              Request history log

In AppImage mode on Linux, data directories are under ~/.local/share/hook/ and config is under ~/.config/hook/. On Windows, both data and config are under %APPDATA%\Hook\.

Git watches these directories only: collections/, environments/, mock-routes/, scripts/, user-agents/.

History format

Request history is stored in NDJSON (Newline-Delimited JSON) format. Each line is a self-contained JSON object representing one executed request.

File: history/hook.ndjson

Each entry has these fields:

{
  "timestamp": "2025-03-15T14:30:00",
  "method": "GET",
  "url": "https://api.example.com/users",
  "status_code": 200,
  "elapsed_ms": 42.5,
  "collection_name": "",
  "request_name": "",
  "request_snapshot": "{...full serialized request...}"
}

Fields: timestamp (ISO 8601 string), method (string), url (string, after expansion), status_code (integer, 0 on error), elapsed_ms (number), collection_name (string or empty), request_name (string or empty), request_snapshot (JSON string containing the full serialized HOOK_REQUEST with all settings, auth, body, headers, params, scripts – restored when clicking a history entry).

Entries are appended; most recent at end. Hook loads the last 200 entries in the GUI. The file grows without limit; delete or truncate manually if needed.