Starhive CLI

Verified against code

This page previously labeled starhive app deploy and starhive app promote as "(coming soon)." Confirmed against AppController.kt (POST /app for deploy, POST /app/{id}/version/ {versionId}/promote for promote) and BundleController.kt (upload-url → PUT → finalize) — both are real, fully implemented endpoints backed by working AppRegistryService.deploy()/promote() logic. The "(coming soon)" label was stale; both commands are shipped today. (The CLI binary itself and the @starhive/bridge SDK aren't in this monorepo, so the client side of this — flags, REPL behavior — couldn't be independently verified, only the backend it calls.)

The Starhive CLI is an interactive terminal for working with Starhive and chatting with Nova — a REPL with slash commands, live menus, conversation history, and streaming responses.

Installation

curl:

curl -fsSL https://cli.starhive.com/install.sh -o starhive-install.sh
bash starhive-install.sh

npm (requires Node.js 18+):

npm install -g @starhive/cli

First launch

On first launch, the CLI creates .starhive/config.json (mode 0600) with production API URLs and an empty token — inside a git repo, .starhive/ is added to the nearest .gitignore automatically. Set your Personal Access Token with /access.

Interactive REPL

Running starhive with no arguments opens the REPL:

Command	Action
/access	Save your PAT
/nova	Open a chat with Nova
/app	Manage your marketplace apps
/clear	Clear the screen
/help	Show help
/exit	Quit

Type / at any prompt for a live, filterable command menu (↑/↓ to navigate, Tab to autocomplete, Esc to dismiss). Bare commands also work — typing nova does the same as /nova.

Chatting with Nova

starhive> /nova
[nova chat — type / to see commands, /exit to leave, /new for a fresh conversation]

nova> Do I have any incidents today?
✦ new conversation
…streamed reply…

nova> last week?
↳ continuing
…streamed reply…

nova> /exit
starhive>

Command	Action
/new	Start a fresh conversation (discards the current one)
/resume	Resume a previous conversation
/help	Chat-specific help
/exit	Return to the main prompt

Managing apps

Command	Action
/list	List your apps — name, status, app key
/deploy	Deploy ./build using ./manifest.yaml (asks for confirmation)
/promote	Publish the manifest's version to customers (asks for confirmation)
/help	App-mode help
/exit	Return to the main prompt

/deploy and /promote prompt for confirmation since promote changes the version every customer installs; /list runs immediately. Scaffolding a new app is command-line only — there's no /create in app mode (it needs a name argument); use starhive app create <name> in the shell. See Building Apps on Starhive for the full flow.

Top-level app commands

starhive app create <name>

Scaffolds a new app from the template (Vite + React, @starhive/ui vendored).

Arg / flag	Default	Description
<name>	—	App display name (also the default folder + package name)
--key <appKey>	com.example.<slug>	Manifest app key (dot notation)
--dir <path>	./<slug>	Target directory

starhive app create "Time Reporting" --key com.acme.timereporting

starhive app deploy

Registers/versions-up the app from its manifest and uploads the built static UI bundle. The first deploy creates the app in the DEPLOYED state — visible only to the developer, not installable by customers until registered in the web console (see Building Apps on Starhive §11).

Flag	Default	Description
--dir <path>	./build	Directory to zip (index.html at the archive root)
--manifest <path>	./manifest.yaml	Manifest file, sent verbatim
--build	—	Run npm run build before zipping
--api <url>	config appPlatformUrl	Override the API base URL

Four steps, all under ${appPlatformUrl}/external/v1/app-platform/:

1. POST /app — publish the manifest → { id, appId, version }
2. POST /app/{appId}/version/{versionId}/bundle/upload-url — a presigned S3 PUT URL
3. PUT <presigned URL> — upload the bundle ZIP (no auth header, direct to S3)
4. POST /app/{appId}/version/{versionId}/bundle/finalize — mark it ready → { bundleLocation, bundleStatus, serveUrl }

starhive app deploy --build --dir ./build --manifest ./manifest.yaml

starhive app promote

Publishes a deployed version to customers. Developers always get the latest deployed build; customers get the promoted one.

Flag	Default	Description
--manifest <path>	./manifest.yaml	Used to resolve the app
--api <url>	config appPlatformUrl	Override the API base URL

starhive app deploy            # ship a new build (devs see it immediately)
# …test it as the developer…
starhive app promote           # roll it out to customers

Key bindings

Key	Effect
/ + typing	Open the live command menu
↑ / ↓	Navigate the menu
Tab	Autocomplete
Enter	Submit / execute
Esc	Dismiss menu, clear input, or exit Nova chat
Ctrl+C (during a stream)	Cancel the response
Ctrl+C (at nova>)	Return to the main prompt
Ctrl+C (at starhive>)	Quit