hiverge-cli 0.4.0

Universal Command Line Interface for Hive agent.

Hive-CLI

Hive-CLI is a command-line interface for managing and deploying the Hive agent and experiments on Kubernetes and other platforms.

     ███          █████   █████  ███
    ░░░███       ░░███   ░░███  ░░░
      ░░░███      ░███    ░███  ████  █████ █████  ██████
        ░░░███    ░███████████ ░░███ ░░███ ░░███  ███░░███
         ███░     ░███░░░░░███  ░███  ░███  ░███ ░███████
       ███░       ░███    ░███  ░███  ░░███ ███  ░███░░░
     ███░         █████   █████ █████  ░░█████   ░░██████
    ░░░          ░░░░░   ░░░░░ ░░░░░    ░░░░░     ░░░░░░

Installation

Pre-requisites

• Python 3.8 or higher
• docker for image building.
• gcloud CLI via brew install gcloud for authentication.

Notes:

• Make sure to enable the ✅ Use containerd for pulling and storing images option in Docker Desktop settings, which is required for multi-arch image support.

Install via pip

pip install hiverge-cli

Install from source

source start.sh

Shell Completion

Hive CLI supports shell tab completion for commands, experiment names, sandbox names, and file paths. After installing the CLI, enable completion for your shell:

Bash

Add the following to your ~/.bashrc:

eval "$(register-python-argcomplete hive)"

Then reload your shell configuration:

source ~/.bashrc

Zsh

Add the following to your ~/.zshrc:

autoload -U bashcompinit
bashcompinit
eval "$(register-python-argcomplete hive)"

Then reload your shell configuration:

source ~/.zshrc

Verify

Test that completion is working:

hive delete exp<TAB>   # Should list available experiments
hive log <TAB>         # Should list available sandbox pods

Features

• Command and subcommand completion for all hive commands
• Dynamic completion of experiment names for delete and show sandboxes --experiment
• Dynamic completion of sandbox pod names for log command
• File path completion for -f/--config flags

Note: Completion requires access to your Kubernetes cluster to fetch experiment and sandbox names. If the cluster is unavailable, completion will still work for static options but won't show dynamic resources.

How to run

Note: Hive-CLI reads the configuration from a yaml file, by default it will look for the ~/.hive/hive.yaml. You can also specify a different configuration file using the -f option. Refer to the hive.yaml for examples.

Below we assume that you have a ~/.hive/hive.yaml file.

Verify the version

hive version

Edit the experiment

Edit command will open the configuration file in your default editor (e.g., vim, nano, etc.) for you to modify the experiment configuration. You can also specify a different editor using the EDITOR environment variable, by default it will use vim.

hive edit config

Create an experiment

hive create exp my-experiment

Note: This will build a Docker image for the experiment and push it to the container registry which may take some time, based on the Dockerfile and network speed. You can enable the Debug mode in the configuration file to see more detailed logs.

List experiments

hive show exps

Visit Dashboard

hive dashboard

Show logs

Sandboxes are the isolated environments where experiments run in parallel. You can list all the sandboxes and view their logs.

hive show sands
hive log <sandbox-name>

Delete an experiment

hive delete exp my-experiment

More

See hive -h for more details.

Development

Debugging

Change the log_level in the configuration file to DEBUG to see more detailed logs.

Troubleshooting

See the Troubleshooting Guide for common issues and solutions.