CLI Reference

galois-edge is the Go supervisor binary that controls the lifecycle of the lab daemon. It supervises the Python instrument engine, manages networking, and registers with the cloud. Every subcommand is listed below.

Top-level synopsis

galois-edge [command]

Available Commands:
  start        Start the galois-edge daemon
  status       Query the daemon health and instrument summary
  setup        Register this edge with the cloud backend and write config
  configure    Get, set, or list configuration values
  install      Install galois-edge as a system service
  uninstall    Remove the galois-edge system service
  doctor       Run diagnostic checks on the system
  claude       Manage Claude Code knowledge ingestion
  version      Print version information
  help         Help about any command

`galois-edge start`

Starts the daemon: loads config, spawns the Python engine, joins the tailnet (if configured), creates TCP proxies, and registers with the cloud.

Flag	Default	Description
`--config <path>`	auto-discover	Path to `config.env`. Overrides system/user search order.
`--log-level <level>`	from config	One of `debug`, `info`, `warn`, `error`.

Startup steps, in order:

Resolve and load configuration.
Apply CLI flag overrides.
Validate config (Validate() on the Config struct).
Initialize structured logging.
Locate the Python engine binary (PYTHON_BIN, then alongside the Go binary, then PATH).
Spawn the engine with config-derived environment variables.
Wait for the engine’s gRPC port to become healthy.
Perform an initial registration with the cloud (best-effort; the heartbeat loop will retry).
If a Tailscale auth key is configured, start tsnet and remember the assigned IP.
Create TCP proxies on the external gRPC and WebSocket ports (both on the tailnet and on 0.0.0.0).
Start the heartbeat loop.
Start the Claude Code ingestion control endpoint (if a backend and registration token are set).
Start the relay client (if RELAY_URL is set or derivable).

SIGINT or SIGTERM triggers graceful shutdown in reverse order: stop registration → drain proxies → stop tsnet → stop the engine.

`galois-edge status`

Probes the running daemon and prints the instrument inventory. Useful as a health check or in scripts.

Flag	Default	Description
`--config <path>`	auto-discover	Used only to read port settings.

Exits non-zero (1) if the engine’s gRPC port isn’t reachable. Sample output:

Daemon status: RUNNING
  Python gRPC: 127.0.0.1:50052
  Instruments: 3 found
    - Keithley 2400 (GPIB0::24::INSTR) [connected]
    - Keysight 34461A (USB0::0x2A8D::0x0101::MY54505555::INSTR) [connected]
    - Tektronix MSO64 (TCPIP::192.168.1.42::INSTR) [connected]

`galois-edge setup <token>`

Registers this edge with the cloud backend and writes the resulting credentials to the config file. The token is a glc_… API key from the Galois dashboard.

Flag	Default	Description
`--backend <url>`	`https://cloud.galoislabs.ai` (or `BACKEND_URL`)	Override the backend URL.
`--name <name>`	system hostname	Edge name reported to the backend.
`--config <path>`	auto-discover or user dir	Where to write the result.

setup posts a registration payload (name, hostname, grpc_port=50051, ws_port=8765, version, os_info) to POST /api/v1/edges/register with X-API-Key: <token>. On success, it persists BACKEND_URL, REGISTRATION_TOKEN, EDGE_NAME, and any returned TAILSCALE_AUTH_KEY / HEADSCALE_URL to config.env. It also ensures a per-machine install ID exists for stable cross-restart identity.

sudo galois-edge setup glc_XXXXXXXX
# Registered as "lab-pi-01" (edge_8a7b…)
# Config written to /etc/galois-edge/config.env
#
# Start the daemon:
#   galois-edge start

If the token doesn’t start with glc_, you’ll get a soft warning — the call still proceeds.

`galois-edge configure …`

Get, set, list, or initialise config values. All subcommands accept --config <path> to target a specific file.

`configure get <KEY>`

Prints the current value of a single key (defaults applied). Exits 1 on unknown keys.

galois-edge configure get GRPC_PORT
# 50051

`configure set <KEY> <VALUE>`

Validates the value, then read-modify-writes the config file. Unknown keys are rejected.

sudo galois-edge configure set HEARTBEAT_INTERVAL_SEC 60
# HEARTBEAT_INTERVAL_SEC=60
# Written to /etc/galois-edge/config.env

`configure list`

Prints every key and its current value as a table. REGISTRATION_TOKEN and TAILSCALE_AUTH_KEY are masked to the last 4 characters.

galois-edge configure list

`configure init`

Writes a fully-defaulted config file. Errors if the file already exists.

sudo galois-edge configure init
# Default config written to /etc/galois-edge/config.env

`galois-edge install`

Registers a system service. On Linux, creates a systemd unit. On Windows, registers a Windows Service. Run as root / Administrator.

Flag	Default	Description
`--config <path>`	`${SystemConfigDir}/config.env`	Config the service will load.
`--user <name>`	`galois-edge`	Service account (Linux only).

sudo galois-edge install
# Installing galois-edge service...
#   config:  /etc/galois-edge/config.env
#   user:    galois-edge
# Service galois-edge installed successfully.
# Start the service with: galois-edge start (or systemctl start galois-edge)

`galois-edge uninstall`

Stops and removes the system service. Run as root / Administrator.

sudo galois-edge uninstall

`galois-edge doctor`

Runs thirteen diagnostic checks and prints a summary. Exits non-zero if any check fails.

Flag	Default	Description
`--config <path>`	auto-discover	Used to find `PYTHON_BIN`, `GRPC_INTERNAL_PORT`, `BACKEND_URL`, `GPIB_ENABLED`.
`--json`	`false`	Emit results as a JSON array instead of text.

Checks:

Check	Status semantics
`go_binary`	Always pass (the binary is running).
`disk_space`	Fail if < 100 MB free at the config dir; warn if disk-stat fails.
`config_file`	Pass on a non-empty readable file; warn if missing or empty; fail if unreadable.
`config_writable`	Warn if the resolved config file (or its parent directory) is not writable by the current user; pass otherwise.
`python_binary`	Warn if `PYTHON_BIN` is unset and auto-detect finds nothing; fail if the path is missing or non-executable; warn if `--version` fails.
`python_health`	Fail if the gRPC port isn’t accepting TCP connections.
`usb_permissions`	Linux: pass if the user is in `plugdev`; warn otherwise. Pass on non-Linux.
`gpib_driver`	Skipped (pass) when `GPIB_ENABLED=false`. Linux: pass if `gpib_config` is on `PATH`; fail if `GPIB_ENABLED=true` and missing; warn otherwise. Non-Linux: pass (NI-VISA path).
`network_backend`	Pass on any HTTP response; warn if `BACKEND_URL` is empty (standalone mode); fail on connection error.
`udev_rules_installed`	Linux: fail if `/etc/udev/rules.d/99-galois-edge.rules` is missing; warn if present but vendor IDs are incomplete; pass if all seven vendor IDs are present. Pass (skip) on non-Linux.
`service_unit_installed`	Linux: fail if `/etc/systemd/system/galois-edge.service` is absent; warn if present but not enabled; pass if enabled. Windows: fail if the `galois-edge` SCM service is not registered; warn if registered but not set to automatic start. macOS: always pass.
`tailnet_connected`	Pass (skip) if `TAILSCALE_AUTH_KEY` is not set. Pass if tsnet has at least one assigned IP. Warn if the key is set but tsnet has not started. Fail on any other tsnet error.
`registration_token_format`	Warn if `REGISTRATION_TOKEN` is set but does not start with `glc_`; pass otherwise. Never fails.

galois-edge doctor --json
[
  {"name":"go_binary","status":"pass","message":"Go binary is running (linux/amd64) at /usr/local/bin/galois-edge"},
  ...
]

`galois-edge claude`

Manages optional Claude Code transcript ingestion (so AI sessions on lab machines flow into the team’s knowledge base). All subcommands are no-ops on edges without a configured backend.

Subcommand	Purpose
`claude enable <folder>...`	Enable ingestion for one or more project folders.
`claude backfill`	Ingest previous chats from consented folders.
`claude disable`	Disable ingestion and remove managed hooks.
`claude status`	Show current ingestion state.
`claude hook`	Internal — invoked by Claude Code as a hook. Don’t call directly.

claude accepts a persistent --config <path> flag (matching the other commands). Notable subcommand flags:

claude enable: --yes (skip prompts), --no-backfill (don’t ingest history at enable time), --repair (re-walk anchors), --exclude-sidechains, --enable-credential-redactor, --exclude-glob <pattern> (repeatable).
claude backfill: --dry-run.
claude disable: --purge-local (also delete on-disk anchor state).

`galois-edge version`

Prints the embedded version string, git commit, and build date. The values are baked in at build time via -ldflags.

galois-edge version
# galois-edge v0.9.4
#   commit:  abc1234
#   built:   2026-03-08

Exit codes

Code	Meaning
`0`	Success
`1`	General error — config invalid, command failed, daemon unreachable, doctor failed

Environment variables

Every config key is also accepted as an environment variable of the same name. See Configuration for the full list. Two installer-specific variables apply only to install.sh:

Variable	Purpose
`GALOIS_VERSION`	Pin a specific version (default: `latest`).
`GALOIS_BASE_URL`	Override the download base URL.