Operations

Irigate’s command-line operations are designed for local validation, selected tool discovery, direct tool calls, process inspection, qualification, serving, systemd management, reload, and shutdown.

Serve

Start the broker in the foreground:

irigate --config profiles/mvp.yaml --require-qualified-sharing

The broker listens at the configured loopback address and starts upstreams only when selected.

Discover tools

List namespaced tools available from a profile:

irigate tools --config profiles/mvp.yaml

This is runtime discovery, not static validation. It initializes every configured upstream, may download packages, may use the network, may require referenced environment variables, prints one <upstream>__<tool> name per line, then closes discovery workers.

Call one tool

Invoke one namespaced tool without opening the HTTP listener:

irigate call --config profiles/mvp.yaml \
  code-review-graph__build_or_update_graph_tool \
  --arguments '{"repo_root":"/path/to/project","full_rebuild":false}'

--arguments accepts one JSON object and defaults to {}. The upstream starts only for this call and closes before the command exits. Credentials remain broker-process environment values and must not be supplied in tool arguments.

Inspect runtime state

Read the latest runtime report:

irigate ps --config profiles/mvp.yaml
irigate ps --config profiles/mvp.yaml --json

ps reads runtime_report_path without starting upstreams or resolving their environment references. The table shows upstream/agent rows with effective mode, live instances, activity state, idle time, timeout, calls, and failures. JSON mode returns the complete schema-version-3 report.

Qualify sharing

Run qualification for a configured profile:

irigate qualify --config profiles/mvp.yaml

Sharing admission combines generic protocol checks with a reviewed upstream-specific qualifier. Use Configuration for sharing fields and Safety for the isolation boundary.

Run as a systemd user service

On a host with a running systemd user manager, install the selected profile as the fixed irigate.service unit:

irigate systemd setup --config ~/.config/irigate/config.yaml

Setup writes ~/.config/systemd/user/irigate.service and a mode-0600 ~/.config/irigate/irigate.env, then daemon-reloads, enables, and starts the unit. The unit preserves the setup interpreter path without resolving its symlinks, so uv tool installations keep their tool environment. The environment file contains only current values explicitly referenced by upstream env fields; it never prints those values or copies literal profile values.

After changing a referenced environment value, run irigate systemd sync --config ~/.config/irigate/config.yaml from a shell where every required value is set. Sync daemon-reloads and restarts an active service because a reload cannot change a running process environment. For a profile-only, connection-preserving reload, use irigate systemd reload. After upgrading from 0.5.0, run sync once to rewrite the unit; if it reports restarted=false, run systemctl --user start irigate.service.

Manage the installed service with systemd:

systemctl --user status irigate.service
journalctl --user -u irigate.service -f
systemctl --user start irigate.service
systemctl --user stop irigate.service
systemctl --user restart irigate.service
systemctl --user enable --now irigate.service
systemctl --user disable --now irigate.service

systemctl --user reload irigate.service runs the unit’s connection-preserving reload. Use restart after an Irigate upgrade or a change to host, port, or runtime paths. The fixed unit runs one selected profile; another setup or sync replaces it. Use systemctl --user stop, rather than irigate stop, for a managed service.

Reload and shutdown

Profile reloads are connection-preserving for successful active-upstream changes. Invalid reloads leave the last valid configuration active. Stop the foreground broker with Ctrl+C; shutdown drains active calls and closes child processes.

Troubleshooting links

• Use --check when you only need profile validation without upstream startup.
• If a Windows-native upstream is launched from WSL, set execution: wsl-windows; this refreshes WSL interop before each spawn and avoids stale-shell Broken pipe failures. Start or restart Irigate from an active WSL session if no live interop endpoint exists.
• Pencil editor tools require Pen Desktop to be running with a document open. That condition is returned as a tool error, not an upstream crash.
• Use Agent selection when a client exposes too many or too few tools.
• Use Safety when deciding whether an upstream can be shared.