CLI

The integration-cli ships with @ci-hub/integration-sdk and provides commands for developing, testing, and submitting your integration. See Installation for setup instructions.

The CLI is not installed as a global binary. Run it through your package manager (npx, pnpm exec, yarn, or bunx), or use the npm scripts included in the scaffolded project (for example, npm run dev).

Quick Start

npm install @ci-hub/integration-sdk
npx integration-cli auth login
npx integration-cli config --init
npx integration-cli dev

pnpm add @ci-hub/integration-sdk
pnpm exec integration-cli auth login
pnpm exec integration-cli config --init
pnpm exec integration-cli dev

yarn add @ci-hub/integration-sdk
yarn integration-cli auth login
yarn integration-cli config --init
yarn integration-cli dev

bun add @ci-hub/integration-sdk
bunx integration-cli auth login
bunx integration-cli config --init
bunx integration-cli dev

Commands

`integration-cli dev`

Start the local development server with the test UI.

npx integration-cli dev [--open]

pnpm exec integration-cli dev [--open]

yarn integration-cli dev [--open]

bunx integration-cli dev [--open]

Flag	Description
`--open`	Open the browser automatically on start

The server runs at http://localhost:8080 and watches your project for changes to .ts, .js, .json, and .ect files. When a change is detected the server restarts automatically.

Interactive shortcuts (while the server is running):

Key	Action
`r`	Restart server
`u`	Show server URL
`o`	Open in browser
`c`	Clear console
`q`	Quit
`h`	Show help

`integration-cli auth`

Manage authentication with CI HUB.

These commands handle developer authentication — your personal CI HUB account used for submitting integrations. This is separate from the auth handlers (login, checkToken, refreshToken) that your integration implements for end-user login. See Login Flow for integration auth.

npx integration-cli auth login

pnpm exec integration-cli auth login

yarn integration-cli auth login

bunx integration-cli auth login

Opens the browser for CI HUB login. The CLI waits up to 5 minutes for you to complete the sign-in flow, then stores the credentials locally.

`auth check`

npx integration-cli auth check

pnpm exec integration-cli auth check

yarn integration-cli auth check

bunx integration-cli auth check

Verifies that the stored token is still valid. If the token has expired, it is refreshed automatically. If the refresh also fails, the token is cleared and you will need to log in again.

`auth logout`

npx integration-cli auth logout

pnpm exec integration-cli auth logout

yarn integration-cli auth logout

bunx integration-cli auth logout

Clears all stored credentials from the local machine.

`integration-cli config`

Create or validate the project configuration file. See Project Structure for where the config file sits in the scaffold.

npx integration-cli config [--init] [--check] [--name <filename>]

pnpm exec integration-cli config [--init] [--check] [--name <filename>]

yarn integration-cli config [--init] [--check] [--name <filename>]

bunx integration-cli config [--init] [--check] [--name <filename>]

Flag	Description
`--init`	Scaffold a starter config file with commented-out defaults
`--check`	Validate the existing config file against the schema
`--name <filename>`	Filename to use with `--init` (`cihub.config.jsonc` or `cihub.config.json`)

Running integration-cli config --init without --name prompts you to pick a filename interactively.
Running integration-cli config --check reports whether the config is valid or lists the validation errors.

`integration-cli submit`

Bundle and submit the integration to CI HUB for review.

npx integration-cli submit [--dry]

pnpm exec integration-cli submit [--dry]

yarn integration-cli submit [--dry]

bunx integration-cli submit [--dry]

Flag	Description
`--dry`	List all files and warnings without actually submitting

The command resolves the bundle from your config (source files, templates, assets, and direct-access helpers), checks for violations, and uploads everything to CI HUB. You must be logged in before submitting.

Bundle violations are reported when a file is reachable from your entry file but is not matched by your include patterns or is explicitly excluded. Adjust declaration.include / declaration.exclude in your config and try again.

The maximum bundle size is 50 MB.

Configuration File

The CLI looks for cihub.config.jsonc or cihub.config.json in the project root. All fields are optional and fall back to the defaults shown below. Run integration-cli config --init to generate a starter file (see Quick Start for your package manager).

`declaration`

Controls how the integration's TypeScript source is discovered.

Field	Default	Description
`entryFile`	`./src/index.ts`	Path to the entry file that exports the integration's public API
`config`	`./src/config.json`	Path to the integration's runtime JSON config
`include`	`["src/*/"]`	Glob patterns for files to include
`exclude`	`[]`	Glob patterns for files to exclude
`respectTsconfigInclude`	`true`	Merge patterns from `tsconfig.json` `include`
`respectTsconfigExclude`	`true`	Merge patterns from `tsconfig.json` `exclude`
`respectGitignore`	`true`	Treat `.gitignore` entries as additional excludes

`templates`

Controls how ECT template files are discovered.

Field	Default	Description
`include`	`["src/*/.ect"]`	Glob patterns for template files to include
`exclude`	`[]`	Glob patterns for template files to exclude
`respectTsconfigExclude`	`true`	Merge patterns from `tsconfig.json` `exclude`
`respectGitignore`	`true`	Treat `.gitignore` entries as additional excludes

`assets`

Paths to the same logo and glyph images you pass to defineIntegration. The CLI reads them from disk so they can be included in the submission bundle.

Field	Default	Description
`logo`	`./src/logo.png`	Full-size logo (600×134) shown in listings and detail views — see Integration Info → logo
`glyph`	`./src/glyph.png`	Compact icon (80×80) used in menus and inline references — see Integration Info → glyph

`directAccessHelper`

Paths to optional helper modules that let consumer applications call your integration's API directly, bypassing the standard handler flow.

Field	Default	Description
`javascriptPath`	`./src/dah.ts`	TypeScript helper — used by all CI HUB plugins
`pythonPath`	`./src/dah.py`	Python helper — used by CI HUB Drive

See Direct Access Helper for how to write and build the helper module.

`integration`

Metadata included in the submission bundle. These fields map to the Integration Info object that CI HUB stores for your integration.

Field	Default	Description
`id`	`my-integration`	Must match the `name` you pass to `defineIntegration` (lowercase, hyphenated)
`version`	`1.0.0`	The version you are submitting — increment this for each new submission
`message`	`""`	Optional message for the review team

Authentication Flow

The CLI uses browser-based OAuth for authentication. When you run integration-cli auth login, a browser window opens where you sign in with your CI HUB account. Once the sign-in is complete, the CLI receives the tokens and stores them in an encrypted local file (cihub.enc). Tokens are refreshed automatically when they expire. Run integration-cli auth logout to clear stored credentials at any time.

On this page