ghqc::ghqc()

ghqc::ghqc() starts the ghqc web UI from R by launching the ghqc binary in the background, waiting for it to become available, and then opening the app in your browser.

It is the main entry point for the R package and the R-side equivalent of running ghqc ui from the terminal.

ghqc::ghqc()

What It Does

When you call ghqc::ghqc():

• any previously started ghqc background server from the current R session is stopped first
• the target project directory is resolved from here::here() and normalized to an absolute path
• a port is chosen automatically unless you supply one
• the package launches ghqc ui --no-open as a supervised background process
• once the server responds, R opens the resolved ghqc URL in your browser or IDE viewer

The function is called for its side effects and returns NULL invisibly.

Arguments

Argument	Description
directory	Project directory to serve. Defaults to here::here().
port	Port to bind the server to. If NULL, ghqc selects a random available port.
config_dir	Optional ghqc configuration directory. If omitted, ghqc uses its normal configuration discovery logic.
log_level	Logging level value, defaulting to Sys.getenv(“GHQC_LOG_LEVEL”, “TRACE”). This exists for the R logging workflow; the function still launches the server in verbose mode so logs can be filtered later with ghqc::ghqc_log().
ipv4_only	Logical flag that forces IPv4-only bind and loopback URL handling. Defaults to FALSE.

Examples

# Start using the current project root
ghqc::ghqc()

# Start on a fixed port
ghqc::ghqc(port = 8080)

# Start for a subdirectory with a custom config location
ghqc::ghqc(directory = "analysis", config_dir = "~/.config/ghqc")

# Force IPv4-only bind behavior
ghqc::ghqc(ipv4_only = TRUE)

Requirements

• the ghqc CLI binary must already be installed and available on PATH
• because the R package launches ghqc ui, the installed binary must include the ui feature
• on unix-like systems, ghqc::ghqc_install() is the intended way to install or upgrade that binary

If the binary is missing, ghqc::ghqc() fails immediately and tells you to run ghqc::ghqc_install().

Startup Behavior

• if port = NULL, the package samples a random available TCP port rather than defaulting to 3103
• on ghqc versions that support ghqc ui url, the package asks the CLI for the final UI URL before opening it
• startup waits until the local server is reachable, then opens the browser or IDE viewer
• if the server fails to come up within the timeout, the function stops with the captured server error when one is available