CLI tool that leverages container technology to manage packages.
Project description
hbox
hbox is a Command Line Interface (CLI) that leverages container technology to manage packages.
Features
hbox offers the following features:
- Container Isolation: hbox uses containers to isolate packages, allowing multiple versions of a package to coexist without conflict.
- Robust Configuration Options: hbox enables high customization through configuration files. You can define package aliases and setup automatic volume mounts via
config.json
. - Support for Pipes: hbox supports the use of pipes in
hbox run
, which allows you to chain commands efficiently. - Convenient Shims: hbox creates
shims
(alias shortcuts) for all installed packages, simplifying command entry fromhbox run <package alias> <commands>
to<package alias> <commands>
.
Commands
$ hbox
usage: hbox [-h] {info,version,list,add,install,remove,uninstall,run,use,set} ...
CLI tool that leverages container technology to manage packages.
positional arguments:
{info,version,list,add,install,remove,uninstall,run,use,set}
Available commands
info Print debug information.
version Show current hbox version.
list List all installed packages and their versions.
add (install) Add a specific version of a package
remove (uninstall) Remove a package.
run Run the package.
use (set) Set current version of a package.
options:
-h, --help show this help message and exit
Installation
You can install hbox via pip
or your preferred package manager.
To install hbox via pip
, run the following command:
pip install hbox
Setup
Shims and Shell Configuration
hbox utilizes shims and a configuration file to effectively manage your installed packages. For the successful addition of $HBOX_DIR/shims
at the correct priority level to your path, these lines of code should be added to your .bashrc
or .zshrc
file:
export HBOX_DIR="$HOME/.hbox"
export PATH="$HBOX_DIR/shims":$PATH
Configuration via config.json
The configuration of packages in hbox is managed by the $HBOX_DIR/config.json
file. This file, which is created automatically upon adding a package, contains information such as package aliases pointing to multiple registries and volume mounts:
{
"debug": false,
"packages": {
"curl": {
"image": "docker.io/curlimages/curl"
},
"aws": {
"image": "docker.io/amazon/aws-cli",
"volumes": [
{
"source": "~/.aws",
"target": "/root/.aws"
}
]
},
"lambda_python": {
"image": "public.ecr.aws/lambda/python"
},
"jq": {
"image": "ghcr.io/jqlang/jq"
},
"terraform": {
"image": "docker.io/hashicorp/terraform"
},
"fga": {
"image": "docker.io/openfga/cli"
}
}
}
You can use the config.json
to also override the registry of any container image. By default, we pull from docker.io
.
Package Version Management via versions.json
hbox also creates and maintains a $HBOX_DIR/versions.json
file that keeps track of the current version of each package. This file is under the management of hbox itself and shouldn't be manually edited:
{
"packages": [
{
"name": "aws",
"versions": [
"latest"
],
"current": "latest"
},
{
"name": "jq",
"versions": [
"latest",
"1.7rc2"
],
"current": "1.7rc2"
},
{
"name": "node",
"versions": [
"latest",
"14",
"15"
],
"current": "15"
}
]
}
Usage
Below are some examples demonstrating how you can use hbox
:
> hbox version
0.1.1
> hbox list
> hbox add jq
latest: Pulling from jqlang/jq
...
Added 'jq' version latest.
> hbox list jq
- jq:
- latest ✔
> jq --version
jq-1.7.1
> hbox add node latest
latest: Pulling from library/node
...
Added 'node' version latest.
> hbox list
- jq:
- latest ✔
- node:
- latest ✔
> hbox list node
- node:
- latest ✔
> node --version
v22.0.0
> hbox add node 14 --set-default
'node' version 14 set as default.
14: Pulling from library/node
...
Added 'node' version 14.
> hbox list node
- node:
- 14 ✔
- latest
> node --version
v14.21.3
> hbox use node latest
'node' set to version latest
> node --version
v22.0.0
> hbox list node
- node:
- 14
- latest ✔
These examples should provide a quick start guide for you to understand the basic operations that you can perform with hbox.
To do
- Support
podman
- Support private registries and mirrors
- maybe via registry mapping in
config.json
?
- maybe via registry mapping in
- Support local overrides for package versions
- use merged version to allow partial overrides?
- Organize an index of packages outside this source repo
- maybe another repo
hbox-py-index
?
- maybe another repo
- Add auto update
- Add option to keep containers instead of using
--rm
- maybe adding custom tags to them to identify them easily?
- Add GitHub Actions to build and publish to PyPI
- Add unit and integration tests
- it should run on Linux and Windows
- Double check if registered packages are available locally before using them
- Add warn when a shim will conflict with an existing command
- Add
hbox config
to support allconfig.json
options - [Experimental] Identify paths in
hbox run
to map them via container volumes automatically - Separate
packages.json
fromconfig.json
- Allow use to override
packages.json
retrieved from centralized index/repo
- Allow use to override
- Add
hbox update
to update index - Add
hbox register
to register a package, even with custom image - Add option to remove images when removing packages
- Add support to colors in
hbox run
output when possible (*nix only?)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.