Full CLI reference

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 manage

Manage installed kits and artifacts interactively.

Usage

$ hubbound manage

Flags

--output <tui|json> Presentation format. Default "tui" — interactive screen with provider tabs, kit/artifact filters, search and status filters.

Examples

$ hubbound manage --output json

Notes

  • Refreshes your authenticated distributions first — metadata only, it never downloads artifact bundles.
  • If the refresh fails, it falls back to the local cache and tells you so.
  • Also shows the current login, org/team enforcement and update availability.
  • Replaces the deprecated `hubbound status` command.

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 init

Create a hubbound.json manifest in the current directory.

Usage

$ hubbound init

Examples

$ hubbound init

Writes hubbound.json with name set to the directory basename.

Notes

  • Fails if hubbound.json already exists in the current directory.
  • After init, bare hubbound install and local-scope install/upgrade use this file.

Related

HubBound file guide

hubbound deploy

Validate and publish a local artifact or kit release.

Usage

$ hubbound deploy [deployment...]

Flags

--path <dir> Exact package directory containing hubbound.json. Default: .; deploy does not walk up to find a parent manifest.
--allow-dirty Allow a dirty Git worktree and mark source.dirty=true.
--dry-run Run local manifest, Git and file preflight without creating a remote release or uploading anything.
--wait-timeout <duration> Maximum wait for public-registry publication when a watcher is configured. Default: 5m.
--yes Accepted for deployment confirmation compatibility; the current deploy flow has no interactive confirmation prompt.
--json Print only the deployment result as JSON.

Examples

$ hubbound deploy --path . --dry-run --json

Validate the full local snapshot without remote mutation.

$ hubbound deploy auditor --path .

$ hubbound deploy security-kit --path . --allow-dirty

A kit selection also prepares its local artifact members.

Notes

  • Reads deployments from hubbound.json; dependency pins under dependencies are never published by deploy.
  • Preflight requires a Git worktree, an HTTPS remote.origin.url without embedded credentials and a 40- or 64-character hexadecimal HEAD SHA. Query and fragment are removed from the normalized repository URL; a dirty worktree requires --allow-dirty.
  • Artifact files are snapshotted and hashed before the first remote mutation. The client uploads only backend-requested digests through presigned PUT URLs, without Authorization or DPoP headers, then commits the release.
  • The local limits are 250 files, 2 MiB per file and 10 MiB total logical size. Files must be safe UTF-8 text; .git, hubbound.json, .env, credentials/certificates, binaries and archives are rejected.
  • A real deploy needs hubbound auth login and an available authenticated release backend. --dry-run is local-only. A committed public release and an active public-registry projection are separate states; the current checkout does not wire the public watcher.

Related

HubBound file guide Deploy step by step

hubbound install

Install a kit or artifact — or every pin in hubbound.json when run with no arguments.

Usage

$ hubbound install

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

Flags

--no-tui Plain text output without the interactive TUI progress.
--scope <local|global> Install scope. Default: local if a hubbound.json is found by walking up from cwd, otherwise global.
--tool <list> Comma-separated tools: cursor, antigravity, claudecode, codexcli, copilot. Default: all.
--profile <name> Pin into a named global profile (and install when that profile is active). Global only — incompatible with --scope local.

Examples

$ hubbound install

Bulk-install every artifact/kit pinned in the nearest hubbound.json.

$ 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 install artifact jane-a1b2c3/my-hook --profile work

Pin into profile work; install immediately if work is active.

Notes

  • If hubbound.json exists above cwd, default scope is local and successful installs record the resolved version in that file.
  • Bare hubbound install requires a hubbound.json (run hubbound init first); otherwise it errors.
  • With --profile on an inactive profile: pin is saved, then the TUI offers a switch (or prints a hint with --no-tui).

Related

HubBound file Profiles

hubbound uninstall

Remove a kit or artifact from local tools.

Usage

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

Flags

--remote Retract the direct remote distribution before local cleanup.
--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 --remote

Notes

  • Uninstall removes provider configuration, cached files, and local install state.
  • The remote distribution is preserved by default. Pass --remote to retract it before cleaning up this machine.
  • --local-only is deprecated — uninstall is local by default, omit the flag.

hubbound retract

Remove your direct remote distribution of a kit or artifact.

Usage

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

Flags

--no-tui Plain text output without the interactive TUI progress.

Examples

$ hubbound retract artifact jane-a1b2c3/my-hook

$ hubbound retract kit jane-a1b2c3/ai-tools-bundle

Notes

  • Retract removes only the authenticated user's direct remote distribution.
  • It does not uninstall the entity or remove local files and provider configuration.
  • Use hubbound uninstall separately to clean up this machine.

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.
--scope <local|global> Upgrade scope. Default: local if a hubbound.json is found by walking up from cwd, otherwise global.
--tool <list> Comma-separated tools: cursor, antigravity, claudecode, codexcli, copilot. Default: all.

Examples

$ hubbound upgrade artifact jane-a1b2c3/my-hook

$ hubbound upgrade all

Upgrade every installed kit and artifact.

Notes

  • In local scope with a hubbound.json present, upgrade refreshes pins in that file after a successful upgrade.

Related

HubBound file

hubbound list

List kits and artifacts installed locally.

Usage

$ hubbound list

Flags

--json Print JSON output.

Examples

$ hubbound list

Prints a table with TAG, TYPE, VERSION, PIN and VIA columns.

$ hubbound list --json

Notes

  • Reads the local installs state (state/artifact_installs.json and state/kit_installs.json): version, pin mode and origin.
  • Read-only: no network access and no login required.

hubbound status

Show installed kits/artifacts and their per-provider status (deprecated — use hubbound manage instead).

Usage

$ hubbound status

Flags

--output <tui|json> Presentation format. Default "tui" — interactive screen with provider tabs, kit/artifact filters, search and status filters.

Examples

$ hubbound status --output json

Profiles

hubbound profile create

Create a named global install profile.

Usage

$ hubbound profile create <name>

Flags

--no-tui Skip interactive prompts (e.g. absorb confirmation).

Examples

$ hubbound profile create work

Notes

  • Writes profiles/<name>/hubbound.json under the HubBound config directory.
  • The first profile becomes active automatically.
  • If unprofiled global optional installs already exist, the TUI can absorb them into this profile.

Related

Profiles guide

hubbound profile switch

Switch the active global install profile.

Usage

$ hubbound profile switch <name>

Flags

--no-tui Plain text output without the interactive TUI progress.

Examples

$ hubbound profile switch personal

Notes

  • Unapplies optional installs owned by the previous profile; never touches enforced or unmarked files.
  • For each pin with version latest, checks for updates before applying.
  • Writes the new name to profiles/active.

Related

Profiles guide

hubbound profile list

List install profiles and which one is active.

Usage

$ hubbound profile list

Examples

$ hubbound profile list

Notes

  • Scans profiles/*/hubbound.json and reports artifact/kit counts per profile.

Related

Profiles guide

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

  • --output and --verbose are persistent flags — they apply to doctor, doctor diagnose and doctor repair.
  • 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

  • --output and --verbose are inherited from the doctor parent command.
  • 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

hubbound docs

Open the CLI documentation in your browser.

Usage

$ hubbound docs

Notes

  • Opens an interactive TUI with links to the full CLI reference and documentation site.