helix explorer

​

Usage

helix explorer [INSTANCE] [OPTIONS]

​

Arguments

​

Options

​

Behavior

• The instance must be running. Otherwise the command fails and suggests helix start <instance>.
• The CLI reads the host port the instance’s container publishes, so an instance started with helix start --port works without changes to helix.toml.
• The Explorer runs as helix-<project>-<instance>.explorer, labelled with the instance’s identity (helixdb.identity) and helixdb.role=explorer. Instance names cannot contain ., so no instance’s container has that name. It is detached and removed when it stops (-d --rm), and its port is published on 127.0.0.1 only.
• The CLI only reuses, lists, or removes a container with that name when it carries both labels. Any other container under that name is left alone, and starting the Explorer fails until it is renamed.
• The container reaches the instance through the host. With Docker, HELIX_URL is http://host.docker.internal:<instance port> and the CLI adds --add-host host.docker.internal:host-gateway. With Podman, HELIX_URL is http://host.containers.internal:<instance port>, a name Podman provides itself.
• A missing image is pulled first, with the pull’s progress on the spinner. An image that is already present is not pulled again. Each CLI release pins a tested Explorer image, so upgrading the CLI moves you to a newer Explorer; pass --image to run another one.
• When the instance’s Explorer is already running, the CLI reuses it and prints its URL. It replaces it instead when it runs another image (images are compared by ID, so a re-pulled or rebuilt tag counts as another image), serves another port than an explicit --port, or reads an instance port that has since changed.
• A replacement keeps the running Explorer’s port unless --port names another. The CLI checks that port and pulls the image before it removes the running Explorer, so a busy port or a failed pull leaves the running Explorer in place.
• The CLI waits up to 30 seconds for the Explorer’s GET /healthz. If the Explorer reports that it cannot reach the instance, the CLI prints a warning and still succeeds. If the container exits first, the error shows how to run the image attached to see its output.
• The browser opens only in an interactive terminal, and never with --no-open or --json.
• helix stop and helix prune also remove the instance’s Explorer, and helix status lists a running one.
• --json prints instance, url, container, image, helixUrl (the instance URL as the container reaches it), helix (reachable or unreachable, as reported by /healthz), and reused. With --stop, it prints instance, container, and wasRunning.

​

Environment

​

Examples

# Open the Explorer for 'dev' or the only local instance
helix explorer

# Start it without opening a browser and print the URL as JSON
helix explorer dev --no-open --json

# Run a locally built Explorer image on a specific port
helix explorer dev --image helix-explorer:local --port 7000

# Stop the Explorer and keep the instance running
helix explorer dev --stop

​

Related

• helix start — start the local instance the Explorer reads.
• helix query — send one request from the terminal.
• Local workflow — run and debug a local instance.