CLI Reference

Installation

pipx install git+ssh://git@lab.xmonetize.net/infrastructure/hive/hive-api.git

Requires Python 3.12+. Works on Linux, macOS, Windows.

No pipx?

Install it: apt install pipx (Debian/Ubuntu), brew install pipx (macOS), or pip install pipx.

In CI

CI pipelines use the Docker image lab.xmonetize.net:5050/infrastructure/hive/hive-api/cli:latest which has hive pre-installed. No manual installation needed.

DevContainer

hive-cli is installed automatically from source when using the Hive DevContainer.

---

hive init

Registers a repository in Hive: creates a deploy token in GitLab and adds the repo to ArgoCD.

hive init <remote_url>

Arguments:

Argument	Description
remote_url	Git remote URL of the repository

Example:

hive init git@lab.xmonetize.net:infrastructure/hive/my-service.git

Note

Typically hive init is called once when creating a project. After that, CI handles everything automatically.

---

hive build

Builds a container from source code using Cloud Native Buildpacks. Automatically detects the language (Go, Python, Java, .NET, Node.js, etc.).

hive build [OPTIONS]

Flags:

Flag	Short	Default	Description
--all	-a	—	Build all discovered services
--service	-s	—	Build a specific service by name
--builder	-b	paketobuildpacks/builder-jammy-base	Buildpack builder image
--path	-p	.	Path to source code
--build-arg	—	—	Build argument KEY=VALUE or KEY (from env). Can be repeated

Examples:

# Build the current service
hive build

# Build all services in the repository
hive build --all

# Build a specific service
hive build --service auth-service

Docker daemon

hive build requires a Docker daemon. In CI, Docker-in-Docker (dind) is used.

Builder selection

Set builder: docker in .hive.yml to use Dockerfile instead of Buildpacks. Default is paketo (Cloud Native Buildpacks). A Dockerfile must exist in the service directory when using builder: docker.

Build arguments

Build args can be set in .hive.yml or via --build-arg CLI flag. Values support dynamic env resolution:

buildArgs:
  NODE_ENV: production         # Static value
  GITHUB_TOKEN: ${GITHUB_TOKEN} # From environment variable
  CI_COMMIT_SHA:                # Entire value from env (like docker --build-arg KEY)

CLI --build-arg overrides .hive.yml values. For Docker builds, args are passed as --build-arg. For Buildpacks, they are passed as --env.

---

hive test

Runs the built container and checks that the health endpoint responds. Generates a JUnit XML report.

hive test [OPTIONS]

Flags:

Flag	Short	Default	Description
--all	-a	—	Test all services
--service	-s	—	Test a specific service
--timeout	-t	30	Health check timeout in seconds
--report	-r	hive-test-report.xml	Path for JUnit report

What it does:

1. Pulls the built image
2. Starts the container (docker run)
3. Waits for HTTP 2xx on the health endpoint (polls every 2 seconds)
4. If response — pass. If timeout or container crashed — fail + container logs
5. Stops and removes the container

Example:

# Test the current service
hive test

# Test with increased timeout
hive test --timeout 60

# Test all services
hive test --all

---

hive deploy

Deploys a service to the platform via Hive API → ArgoCD → Knative.

hive deploy [OPTIONS]

Flags:

Flag	Short	Default	Description
--all	-a	—	Deploy all services
--service	-s	—	Deploy a specific service
--env	-e	—	Environment variable KEY=VALUE (can be repeated)
--bootstrap	—	—	Deploy directly to ArgoCD, bypassing Hive API
--timeout	-t	300	Deploy timeout in seconds

Bootstrap mode

The --bootstrap flag is used to deploy Hive API itself (or when the API is unavailable). It creates an ArgoCD Application directly via the ArgoCD API, without calling Hive API. Requires ARGOCD_URL and ARGOCD_TOKEN variables.

Examples:

# Deploy the current service
hive deploy

# Deploy with environment variables
hive deploy --env DATABASE_URL=postgres://prod/db --env LOG_LEVEL=warn

# Deploy all services
hive deploy --all

# First deploy (certificate provisioning may take longer)
hive deploy --timeout 600

CI environment variables:

Variable	Description
HIVE_API_URL	Hive API URL
HIVE_API_TOKEN	Bearer token for authentication
CI_REGISTRY_IMAGE	Image address in registry
CI_COMMIT_SHORT_SHA	Image tag (commit SHA)

---

hive list

Shows all discovered services in the repository.

hive list

Example output:

Discovered services:
  helloworld-go       (port: 8080, path: helloworld-go)
  helloworld-python   (port: 8080, path: helloworld-python)
  helloworld-dotnet   (port: 8080, path: helloworld-dotnet)

---

hive ci

Generates a .gitlab-ci.yml pipeline from discovered .hive.yml files. Outputs YAML to stdout.

hive ci [OPTIONS]

Flags:

Flag	Short	Description
--global	-g	Generate pipeline for all discovered services
--environment	-E	GitLab environment name (e.g., staging, production)

Examples:

# Generate for all services (stdout)
hive ci --global

# With environment binding — deploy jobs get environment
hive ci --global --environment staging

# Save to file
hive ci --global -E production > child-pipeline.yml

Environment config

When --environment is set, Hive reads cli/environments.yaml and injects environment-specific variables (HIVE_API_URL, HIVE_DOMAIN) directly into the generated pipeline. This is the source of truth for per-environment configuration — no need for GitLab environment-scoped variables (which don't propagate to child pipelines). Without the flag, a hardcoded staging URL is used (backward compatible).

More about CI in the CI/CD Integration section.