CLI Reference¶
Installation¶
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 token¶
Creates the project's gitlab-deploy-token in GitLab if it has none. Never deletes or duplicates tokens. GitLab exposes this token to later CI jobs as CI_DEPLOY_USER/CI_DEPLOY_PASSWORD, which hive init and hive deploy use.
hive init¶
Registers the repository in this cluster's ArgoCD with the project's deploy token taken from CI_DEPLOY_USER/CI_DEPLOY_PASSWORD. Re-running updates the stored credentials. Fails if those variables are empty — run hive token first.
Arguments:
| Argument | Description |
|---|---|
remote_url |
Git remote URL of the repository |
Example:
Note
Both commands run automatically in the generated CI pipeline: the token stage, then init. To run hive init by hand, export CI_DEPLOY_USER/CI_DEPLOY_PASSWORD of the project's gitlab-deploy-token.
hive build¶
Builds a container from source code using Cloud Native Buildpacks. Automatically detects the language (Go, Python, Java, .NET, Node.js, etc.).
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.
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:
- Pulls the built image
- Starts the container (
docker run) - Waits for HTTP 2xx on the health endpoint (polls every 2 seconds)
- If response — pass. If timeout or container crashed — fail + container logs
- 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.
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_PIPELINE_ID |
Image tag (pipeline ID; latest if unset) |
hive list¶
Shows all discovered services in the repository.
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.
Flags:
| Flag | Short | Description |
|---|---|---|
--global |
-g |
Generate pipeline for all discovered services |
--environment |
-E |
Environment name from Environments (staging, production, envik) |
Examples:
# Generate for all services (stdout)
hive ci --global
# With environment binding — init and deploy jobs get its variables
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, HIVE_ENVIRONMENT) directly into the generated pipeline. An unknown name is an error. 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.