CLI Reference

Overview

Hook supports headless CLI operation for automation and CI. CLI mode has no GUI and no Allegro 5 dependency at runtime.

All subcommands return exit code 0 on success and 1 on error. Output goes to stdout; errors and warnings go to stderr.

General syntax

hook <command> [options]

Running hook with no arguments or an unknown command prints the usage summary to stderr and exits with code 1.

run

Execute the first request in a collection.

hook run -f <collection.json> [-e <env.json>] [--curl]

Flags:

• -f <path>: path to the collection JSON file (required).
• -e <path>: path to an environment JSON file (optional). Variables from this environment are expanded in the request.
• --curl: force the curl subprocess backend instead of the native OpenSSL backend.

Output on success:

Status: 200 OK
Time: 42 ms

--- Headers ---
Content-Type: application/json
...

--- Body ---
{ "key": "value" }

Output on error:

Error: request failed: <message>

Exit codes: 0 = request succeeded, 1 = request failed or bad arguments.

export

Print the equivalent curl command for the first request.

hook export -f <collection.json> [-e <env.json>]

Flags:

• -f <path>: path to the collection JSON file (required).
• -e <path>: path to an environment JSON file (optional).

Output: a single curl command line printed to stdout.

curl -X GET https://api.example.com/users -H "Accept: application/json"

Exit codes: 0 = success, 1 = error.

import postman

Import a Postman Collection v2.1 JSON file into Hook format.

hook import postman <file.json> -o <output.json>

Arguments:

• <file.json>: path to the Postman collection file (required).
• -o <output.json>: path for the output Hook collection (required).

Output on success:

Imported myapi.postman_collection.json -> myapi.json (My API)

Exit codes: 0 = success, 1 = error.

import bruno

Import a Bruno .bru file or directory into Hook format.

hook import bruno <file_or_dir> -o <output.json>

Arguments:

• <file_or_dir>: path to a .bru file or a directory containing .bru files (required). If a directory, all .bru files in it are imported into one collection.
• -o <output.json>: path for the output Hook collection (required).

Output on success:

Imported ./bruno_dir/ -> myapi.json (bruno_dir)

Exit codes: 0 = success, 1 = error.

import postman-env

Import a Postman Environment v2.1 JSON file into Hook format.

hook import postman-env <file.json> -o <output.json>

Arguments:

• <file.json>: path to the Postman environment file (required).
• -o <output.json>: path for the output Hook environment (required).

Output on success:

Imported env dev.postman_environment.json -> dev.json (dev)

Exit codes: 0 = success, 1 = error.

import bruno-env

Import a Bruno environment file into Hook format.

hook import bruno-env <file.json> -o <output.json>

Arguments:

• <file.json>: path to a Bruno environment file (required).
• -o <output.json>: path for the output Hook environment (required).

Output on success:

Imported env bruno_env.json -> myenv.json (myenv)

Exit codes: 0 = success, 1 = error.

mock

Start a mock HTTP server.

hook mock <routes.json> [--port N]

Arguments:

• <routes.json>: path to the routes JSON file (required). See Mock Server for the format.
• --port N: TCP port to listen on. Default: 18080.

The server runs in the foreground. Stop it with Ctrl+C.

Exit codes: 0 = clean shutdown, 1 = error.

git subcommands

All git subcommands operate on the current working directory. Status flags: M = modified, ? = new/untracked, S = staged, D = deleted. Author defaults to “Hook User hook@localhost” unless configured.

hook git status                   Print changed files (or "No changes")
hook git stage <path>             Stage a file ("Staged.")
hook git stage --all              Stage all changed files ("Staged.")
hook git unstage <path>           Unstage a file ("Unstaged.")
hook git commit -m "message"      Commit staged changes ("Committed.")
hook git log [--max N]            Show last N commits (default 20)
hook git diff [path]              Unified diff (or "No changes")
hook git restore <path>           Discard changes ("Restored.")
hook git branch                   List branches (* = current)
hook git branch <name>            Create branch at HEAD
hook git switch <name>            Switch to branch

Examples

hook run -f api.json -e production.json
hook export -f api.json -e dev.json
hook import postman export.json -o api.json && hook run -f api.json
hook import postman-env dev.postman_environment.json -o dev.json
hook import bruno-env environments/dev.json -o dev.json
hook git stage --all && hook git commit -m "Add user endpoints"