Using the CLI

The CLI does three things: start the local service, manage running projects, and publish component updates from the terminal. The three binary names comphub, ch and comp-hub point to the same program.

Command overview

Command	Purpose
`comphub`	Start the local service for the current project
`comphub status`	Show the master status and all running projects
`comphub stop <hash>`	Stop the specified project
`comphub stop --all`	Stop all projects
`comphub kill`	Shut down the master and every project
`comphub fix`	Clean up leftover runtime files
`comphub login`	Authorise through the browser and save credentials
`comphub upload [compDir]`	Publish a new version of an already published component
`comphub install <component[@version]>`	Download a published public component into the current directory

Starting the service

bash

comphub

Flags:

Flag	Short	Default	Description
`--port`	`-p`	5478	Service port
`--dir`	`-d`	`./`	Component root directory
`--log-level`	`-l`	`error`	`debug` / `info` / `warn` / `error`
`--version`	`-v`	—	Show the version
`--help`	`-h`	—	Show help

bash

comphub -p 8080
comphub -d ./src
comphub -l debug

The port flag only applies while the master is not running

If a service is already running, the CLI reuses the existing port and notes that -p was ignored. Run comphub kill first to switch ports.

After starting, the terminal prints:

Version  0.44.11
Project  D:\project\my-app
Hash     94525912
Port     5478
URL      http://localhost:5478/94525912/main/

Hash identifies the current directory and is what the stop command needs. Press Ctrl+C to end the log output for the current project, which also unregisters it automatically.

Configuration file

Create .comphub.json or .comphub.js in the project root:

json

{
  "dir": "./src",
  "allowDebug": false
}

Key	Type	Default	Description
`dir`	string	`./`	Component root directory; uploads and downloads can only touch this directory and its subdirectories
`allowDebug`	boolean	false	Whether debug mode is allowed
`proxy`	object	—	Proxy rules in the same format as http-proxy-middleware

.comphub.js exports according to the project's module system:

// CommonJS
module.exports = { dir: "./src" };

// ESM (package.json has "type": "module")
export default { dir: "./src" };

Load order: .comphub.json → .comphub.js → defaults. Precedence: command-line flags > configuration file > defaults.

Proxy rules

Component demos run inside an iframe and can only reach the local service. When you need to call an intranet backend or an API without CORS headers, forward through proxy:

json

{
  "proxy": {
    "/api": {
      "target": "http://10.0.0.5:8080",
      "changeOrigin": true,
      "pathRewrite": { "^/api": "" }
    }
  }
}

Request it from the demo like this:

fetch("/__proxy__/api/users");

Rule details:

Keys match the path after /__proxy__ and support prefixes or regular expressions.
Values are passed to http-proxy-middleware as-is; target is required.
pathRewrite applies after the /__proxy__ prefix is stripped.
When no rule matches, the response is 404 {"message":"Proxy not found"}.
Rules only apply to the project that declares them.

Inspecting and stopping

bash

comphub status          # Show the master and the project list
comphub stop 94525912   # Stop the specified project
comphub stop --all      # Stop every project
comphub kill            # Shut down the master and all projects
comphub fix             # Clean up leftover runtime files

status lists each project's hash, path and URL. fix is for the case where an abnormal exit left files behind and startup now fails.

Logging in

bash

comphub login

The CLI requests one authorisation and opens a browser page; once you confirm on that page, the credentials are saved to ~/.comphub/credentials.json. You only need to log in once per machine.

bash

comphub login --no-browser   # Only print the authorisation URL

The authorisation session is one-off: a pending session expires after 2 minutes, while the CLI waits up to 5 minutes. Run comphub login again when the credentials expire.

Publishing a new version

comphub upload only works for components that have already been published. The first publish goes through Upload & Publish.

bash

cd src/components/MyComponent
comphub upload -m "Fix tooltip positioning"

Flag	Short	Description
`--message`	`-m`	Release note, required
`--dry-run`	—	Validate and print only, without submitting
`--dir`	`-d`	Resource directory, same meaning as the start flag

When it runs, the CLI will:

Locate the project the component belongs to.
Make sure that project has a local service running (starting one if needed).
Submit the component directory; the server validates it, pre-compiles dependencies and uploads.

A submit may take several minutes; the CLI allows a 10-minute timeout.

The version must be greater than the online one

If version in the local comp.json is not greater than the online version, the CLI refuses outright. Bump the version after changing code, then upload. To change only the description or preview configuration, use the update page.

Installing a component

comphub install downloads the source zip of a published public component and extracts it into the current directory.

bash

comphub install ThemeSwitch
comphub install ThemeSwitch@1.0.0
comphub install ThemeSwitch --force

Argument	Short	Description
`<component>`	—	Component name; must be a published public component
`@version`	—	Optional; omit to install the latest version
`--force`	`-f`	Replace `./<component>/` if it already exists
`--remote`	—	Remote service address, same meaning as for other commands

When it runs, the CLI will:

Look up the component by exact name among published public components.
Download the source zip (small packages stream directly; large ones go through a signed OSS URL).
Extract it into ./<component>/, stripping the component_version/ folder inside the zip.

No login or local service is needed. Dependencies are not installed — follow the component's README.

ThemeSwitch/
├── index.vue        # index.jsx / index.tsx for React
├── comp.json
├── README.md
└── demo/

--force replaces the directory

The existing directory is deleted only after the new package has been extracted, but if the final replacement fails it cannot be recovered. Commit local changes first.

Common errors:

Component not found: only published public components can be installed; the CLI lists close names when it has suggestions.
Version not found: the CLI prints the currently published version.
Target already exists: add --force to replace it.

Running several projects in parallel

Different projects can run at the same time, each on its own port:

bash

# Terminal 1
cd /path/to/project-a && comphub

# Terminal 2
cd /path/to/project-b && comphub

comphub status

FAQ

Startup says an upgrade is required

Run npm install comp-hub@latest -g as prompted and start again.

Upload reports a version error

The local version is not greater than the online one. Raise version in comp.json, or submit metadata through the update page instead.

The submit times out / the result cannot be confirmed

Do not retry blindly. Check on the platform whether the latest version has been updated, then decide whether to resend.

The browser cannot open anything after start

Make sure you are visiting the full URL printed by the terminal (including /{hash}/main/), not the bare port.

Next steps

First publish: Upload & Publish
Develop components in the browser: Using Studio

Using the CLI ​

Command overview ​

Starting the service ​

Configuration file ​

Proxy rules ​

Inspecting and stopping ​

Logging in ​

Publishing a new version ​

Installing a component ​

Running several projects in parallel ​

FAQ ​

Next steps ​

Using the CLI

Command overview

Starting the service

Configuration file

Proxy rules

Inspecting and stopping

Logging in

Publishing a new version

Installing a component

Running several projects in parallel

FAQ

Next steps