CLI Reference

Every command, every flag, and what each one does. Most commands show an interactive TUI when attached to a terminal and plain output otherwise.

The hubbound command

Running hubbound with no arguments opens the interactive TUI when attached to a terminal. In a non-interactive shell it prints the help and exits.

The CLI talks to the local daemon (hubboundd) over HTTP for analytics and device credentials, and to the HubBound cloud for distributions, auth and updates.

$ hubbound

# opens the interactive TUI (TTY only)

Global flags

--debug	Set log level to debug. Persistent flag — works on every command. Logs are written to the HubBound log directory and mirrored to stderr.
--help, -h	Show help for any command or subcommand.

Distributions

hubbound sync

Sync your distributions and materialize their files locally.

Usage

$ hubbound sync

Flags

--no-tui

Plain text output without the interactive TUI progress.

Notes

Phase 1 fetches your distributions into state/artifact_installs.json and state/kit_installs.json.
Phase 2 downloads every artifact's files into state/artifacts and wires them into your tools.

hubbound install

Install a kit or artifact and sync it locally.

Usage

$ hubbound install <artifact|kit> <author/name[@version]>

Flags

--no-tui

Plain text output without the interactive TUI progress.

Examples

$ hubbound install artifact jane-a1b2c3/my-hook

$ hubbound install kit jane-a1b2c3/ai-tools-bundle@1.2.0

Pin an exact version with @version.

hubbound uninstall

Uninstall a kit or artifact from your account and local tools.

Usage

$ hubbound uninstall <artifact|kit> <author/name>

Flags

--local-only	Skip the remote distribution delete and only clean local state.
--no-tui	Plain text output without the interactive TUI progress.

Examples

$ hubbound uninstall artifact jane-a1b2c3/my-hook

$ hubbound uninstall kit jane-a1b2c3/ai-tools-bundle --local-only

hubbound upgrade

Upgrade a kit/artifact (or everything) to its latest version.

Usage

$ hubbound upgrade <kit|artifact> <author/name>

$ hubbound upgrade all

Flags

--no-tui

Plain text output without the interactive TUI progress.

Examples

$ hubbound upgrade artifact jane-a1b2c3/my-hook

$ hubbound upgrade all

Upgrade every installed kit and artifact.

Account & device

hubbound auth login

Authenticate via Device Code Flow.

Usage

$ hubbound auth login

Flags

--json	Output JSON (also forces non-interactive output).
--no-tui	Plain text output without the TUI.

Notes

With a TTY it shows an interactive login screen; otherwise it prints the verification URL and user code.
The user code is copied to your clipboard automatically when possible.
After authorization, the device is enrolled for analytics (DPoP credentials).

hubbound auth status

Show authentication status.

Usage

$ hubbound auth status

Flags

--json

Output JSON.

Examples

$ hubbound auth status

✓ Logged in (device <id>, token expires <ts>)

hubbound auth logout

Clear authentication credentials.

Usage

$ hubbound auth logout

Notes

Revokes the device server-side. If the server can't be reached, local credentials are still cleared and a warning is shown.

hubbound device status

Show analytics device credential status.

Usage

$ hubbound device status

Flags

--json

Output JSON.

Notes

Queries the local daemon — it must be running.
Reports enrollment state, device ID, token expiry and credential path.

Daemon

hubbound daemon status

Show daemon service status.

Usage

$ hubbound daemon status

hubbound daemon health

Check daemon health over HTTP.

Usage

$ hubbound daemon health

Examples

$ hubbound daemon health

Daemon is healthy at http://127.0.0.1:<port>

hubbound daemon install

Install the daemon as an OS service (requires administrator privileges).

Usage

$ sudo hubbound daemon install

Notes

Registers hubboundd as a system service (launchd / systemd / Windows Service).

hubbound daemon start

Start the daemon service (requires administrator privileges).

Usage

$ sudo hubbound daemon start

hubbound daemon stop

Stop the daemon service (requires administrator privileges).

Usage

$ sudo hubbound daemon stop

hubbound daemon restart

Restart the daemon service (requires administrator privileges).

Usage

$ sudo hubbound daemon restart

hubbound daemon uninstall

Uninstall the daemon service (requires administrator privileges).

Usage

$ sudo hubbound daemon uninstall

Analytics

hubbound analytics doctor

Diagnose the analytics sync backlog (passive, read-only).

Usage

$ hubbound analytics doctor

Flags

--output <tui|json>

Presentation format. Default "tui" — an interactive screen with Overall + per-table tabs.

Notes

Fetches a read-only snapshot from the local daemon: watermarks, pending rows and upload queue. Does not run check or export.

hubbound analytics push

Force an analytics check and export/upload cycle.

Usage

$ hubbound analytics push

Flags

--force	Ignore NextCheckAt backoff on outstanding uploads.
--wait-timeout <duration>	How long to wait for cloud confirmation (0 disables the wait). Default 2m.
--json	Print the JSON result.
--no-tui	Plain text output without the TUI.

Examples

$ hubbound analytics push --force

$ hubbound analytics push --wait-timeout 0 --json

Updates

hubbound update

Check for a signed update and optionally apply it.

Usage

$ hubbound update

Flags

--force	Check even when automatic updates are disabled.
--yes	Apply a staged update without prompting.
--helper <path>	hubbound-helper executable path (defaults to HUBBOUND_HELPER or PATH lookup).
--no-tui	Plain text output without the TUI.

Notes

Checks, downloads and verifies the latest signed update. When one is staged, asks whether to apply it now (elevated helper) or later.
Applying changes the whole suite bundle — hubbound, hubboundd, agent and helper stay on the same version.

hubbound update status

Print update status.

Usage

$ hubbound update status

Flags

--json	Print JSON.
--no-tui	Plain text output without colors.

Notes

Shows channel, current/available/pending versions, last check time and last error.

hubbound update check

Check, download, and verify the latest signed update.

Usage

$ hubbound update check

Flags

--force	Check even when automatic updates are disabled.
--json	Print JSON.
--no-tui	Plain text output without the TUI.

hubbound update apply

Ask hubbound-helper to apply the staged signed update.

Usage

$ hubbound update apply --force

Flags

--force	Required safety acknowledgement — the command refuses to run without it.
--helper <path>	hubbound-helper executable path.
--no-tui	Plain text output without the TUI.

Notes

Requires a staged update (run hubbound update check first) and elevated privileges — it will ask for sudo / UAC again by design.

Troubleshooting

hubbound doctor

Diagnose Hubbound tool integrations.

Usage

$ hubbound doctor

$ hubbound doctor diagnose

Flags

--output <tui\|json>	Presentation format. Default "tui".
--verbose	Show diagnostic logs on stderr.

Notes

doctor and doctor diagnose are equivalent — read-only, they don't change any files.

hubbound doctor repair

Repair missing Hubbound-owned assets.

Usage

$ hubbound doctor repair

Flags

--output <tui\|json>	Presentation format. Default "tui".
--verbose	Show diagnostic logs on stderr.

Notes

Rewrites Hubbound-owned configuration for supported providers (e.g. Claude Code, git-ai).

hubbound version

Print the installed version.

Usage

$ hubbound version

Examples

$ hubbound version

hubbound v1.0.0