Build and operate projects with the BlinkHost CLI

Install

BlinkHost CLI 2.1 requires Node.js 22.12 or newer on Linux, macOS or Windows.

npm install --global @blinkhost/cli@2.1.0
blinkhost --version

The BlinkHost CLI v2.1.0 release includes the package archive, CycloneDX SBOM, checksums and Sigstore verification bundle. The npm package is published by BlinkHost's GitHub release workflow using Trusted Publishing and includes build provenance.

Check your setup safely

blinkhost quickstart
blinkhost quickstart --json

Quickstart checks Node.js, Git, your operating-system credential service, the selected directory and any existing blinkhost.yaml. It is local and read-only: it does not sign in, upload source, create resources, deploy or incur usage.

Use the version-matched reference without leaving your terminal:

blinkhost docs
blinkhost docs automation
blinkhost docs --search credential
blinkhost help create
blinkhost create --help --json

The bundled reference works offline and is updated with each CLI release. Follow its links when you need longer service guides or current plan information.

Connect an account

Run blinkhost auth login. The CLI opens a BlinkHost page where you approve the device; your password is never entered in the terminal. Rotating refresh credentials are held only by macOS Keychain, Windows Password Vault or Linux Secret Service. The CLI does not fall back to a plaintext credential file.

Use blinkhost auth sessions to review connected devices, blinkhost auth revoke SESSION_ID to remove one, or blinkhost auth logout to disconnect the active profile. Named profiles keep personal and work accounts separate. Headless automation should use a registered GitHub OIDC workload or a short-lived runtime access token.

Create or adopt a project

blinkhost create study-circle --template astro --module search:rust --database PRIMARY_DB
cd study-circle
blinkhost validate
blinkhost projects link PROJECT_ID
blinkhost dev

Supported frontends are Astro, HTML, React, Solid, Svelte and Vue. Backend modules may use Go, Python or Rust. If you choose --no-install, the result includes the exact dependency and test steps to run next.

For an existing repository, inspect the proposed manifest before writing it:

blinkhost init apps/storefront --dry-run --json
blinkhost init apps/storefront
blinkhost validate apps/storefront

init writes only blinkhost.yaml, refuses an existing manifest unless --force is explicit, and never rewrites application source. It detects supported frontend metadata but does not guess backend services. One manifest represents one deployable application. Select a nested application directory directly, or use a build-context root containing the app and its shared workspace packages; use separate BlinkHost projects for independently deployable monorepo applications.

Work with remote resources

Projects, repositories, source connections, previews, builds, deployments, modules, databases, bindings, assets, organizations, templates, approvals, agency handoffs, policies and workloads have matching command groups. Use blinkhost help COMMAND before an operation. List and get are read-only; create, update, delete and action call the active workspace. Destructive operations require --confirm with the exact resource ID.

Local quickstart, create, init, validate, manifest, doctor, test and dev do not create BlinkHost resources. Remote previews, builds, deployments, databases, assets and modules can use plan capacity. Workspace roles, limits, verified-artifact checks, protected-environment approvals and audit records remain enforced by BlinkHost.

Protect secrets and diagnostics

Secret values are accepted only through standard input, never as command arguments:

set +x
printf '%s' "$API_TOKEN" | blinkhost secrets set API_TOKEN --project PROJECT_ID --environment production

Application logs can contain sensitive data written by application code. Review log output before sharing it. blinkhost support bundle creates a local mode-0600 diagnostic file that excludes credentials, source code, filenames and repository URLs; review it before sending it to support.

Automate predictably

Use --json --non-interactive for scripts and coding agents. JSON mode writes exactly one response object to stdout on success or failure; subprocess diagnostics use stderr. Exit codes and envelope fields remain stable within the v2 major line, while service data may add fields.

Remote mutations receive a request ID and an idempotency key. A new invocation receives a new key, so after a timeout use list, get, status or GROUP wait ID to reconcile the operation before retrying. --non-interactive prevents account authorization and preview commands from opening a browser.

Verify a release

After downloading the four release assets, verify their checksums and signed evidence:

sha256sum --check SHA256SUMS
cosign verify-blob \
  --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/blinkhost-ltd/blinkhost-cli/.github/workflows/release.yml@refs/tags/v2.1.0" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

Pin or roll back explicitly with npm install --global @blinkhost/cli@VERSION. Update checks report releases but never install them automatically.

Exit codes

Code	Meaning
0	Success
2	Invalid command or option
3	Project or input validation failed
4	Local filesystem or executable failure
5	Unexpected CLI failure
6	Authentication or permission failure
7	Network or timeout failure
8	Remote service failure
9	State conflict or approval required