Installation
hclapi is distributed as a single, statically compiled binary with zero runtime dependencies.
Quick install
Linux and macOS
Download and install the latest binary matching your operating system and CPU architecture into /usr/local/bin:
curl -fsSL https://raw.githubusercontent.com/ju4n97/hclapi/main/scripts/install.sh | bash
Windows (PowerShell)
Download and install the latest binary for Windows:
irm https://raw.githubusercontent.com/ju4n97/hclapi/main/scripts/install.ps1 | iex
Linux package managers
Direct package installations include the hclapi binary in /usr/bin and system man pages in /usr/share/man/man1/hclapi.1.
Debian / Ubuntu (.deb)
Download the .deb package from the releases page and install via dpkg:
# Example for x86_64 / amd64
curl -fsSLO https://github.com/ju4n97/hclapi/releases/latest/download/hclapi_0.1.0_linux_amd64.deb
sudo dpkg -i hclapi_0.1.0_linux_amd64.deb
Fedora / RHEL / Rocky Linux (.rpm)
Download the .rpm package from the releases page and install via rpm:
# Example for x86_64 / amd64
curl -fsSLO https://github.com/ju4n97/hclapi/releases/latest/download/hclapi_0.1.0_linux_amd64.rpm
sudo rpm -i hclapi_0.1.0_linux_amd64.rpm
Arch Linux (.pkg.tar.zst)
Download the native Arch package from the releases page and install via pacman:
# Example for x86_64 / amd64
curl -fsSLO https://github.com/ju4n97/hclapi/releases/latest/download/hclapi_0.1.0_linux_amd64.pkg.tar.zst
sudo pacman -U hclapi_0.1.0_linux_amd64.pkg.tar.zst
Alpine Linux (.apk)
curl -fsSLO https://github.com/ju4n97/hclapi/releases/latest/download/hclapi_0.1.0_linux_amd64.apk
apk add --allow-untrusted hclapi_0.1.0_linux_amd64.apk
Precompiled binaries
Download a precompiled archive directly from the GitHub releases page:
Manual installation (Linux and macOS)
# 1. Detect platform
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')"
# 2. Download and extract latest release
RELEASE_URL="https://github.com/ju4n97/hclapi/releases/latest/download/hclapi_${OS}_${ARCH}.tar.gz"
curl -fsSL "$RELEASE_URL" | tar -xz
# 3. Move binary to your system PATH
sudo install -m 0755 hclapi /usr/local/bin/hclapi
Container (Docker and Podman)
hclapi is published as a minimal, distroless multi-architecture OCI image on GitHub Container Registry (supporting linux/amd64 and linux/arm64).
Pull the image
# Docker
docker pull ghcr.io/ju4n97/hclapi:latest
# Podman
podman pull ghcr.io/ju4n97/hclapi:latest
Start the HTTP server
Mount your local directory containing .hcl manifests into the container and bind port 8080:
# Docker
docker run --rm -p 8080:8080 -v "$(pwd):/app:ro" ghcr.io/ju4n97/hclapi:latest serve -c /app
# Podman (includes :z for SELinux volume relabeling)
podman run --rm -p 8080:8080 -v "$(pwd):/app:ro,z" ghcr.io/ju4n97/hclapi:latest serve -c /app
Export OpenAPI specification
Generate an OpenAPI 3.1 JSON specification to stdout:
docker run --rm -v "$(pwd):/app:ro" ghcr.io/ju4n97/hclapi:latest openapi -c /app --pretty
Docker Compose
Run hclapi alongside PostgreSQL and Valkey in a local development environment:
docker-compose.yaml
services:
hclapi:
image: ghcr.io/ju4n97/hclapi:latest
ports:
- "8080:8080"
volumes:
- .:/app:ro
command: ["serve", "-c", "/app", "--host", "0.0.0.0", "--port", "8080"]
environment:
- DATABASE_URL=postgres://postgres:postgres@postgres:5432/hclapi_db?sslmode=disable
- REDIS_URL=redis://valkey:6379/0
depends_on:
postgres:
condition: service_healthy
valkey:
condition: service_started
postgres:
image: postgres:18-alpine
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=hclapi_db
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
valkey:
image: valkey/valkey:9.1.2-alpine
ports:
- "6379:6379"
volumes:
pgdata:
Start the services:
Build from source
Using Go install
Requires Go 1.27+ installed:
go install github.com/ju4n97/hclapi/cmd/hclapi@latest
(Ensure $GOPATH/bin or $HOME/go/bin is in your system $PATH).
Building locally from git
Requires Task installed:
git clone https://github.com/ju4n97/hclapi.git
cd hclapi
task build
# Binary is generated at bin/hclapi
Verification
Check that hclapi is installed:
Display CLI usage instructions:
Verify artifact integrity (optional)
All release assets include SHA-256 digests in checksums.txt:
# Download checksum file
curl -fsSLO https://github.com/ju4n97/hclapi/releases/latest/download/checksums.txt
# Verify checksums
sha256sum --ignore-missing --check checksums.txt
# (On macOS: shasum -a 256 --ignore-missing -c checksums.txt)
Shell autocompletion
hclapi supports dynamic command completion for subcommands and flags.
Bash
Add dynamic completion to your ~/.bashrc:
echo 'complete -o default -C hclapi hclapi' >> ~/.bashrc
source ~/.bashrc
Zsh
Add the following to your ~/.zshrc:
autoload -Uz +X compinit && compinit
autoload -Uz +X bashcompinit && bashcompinit
complete -o default -C hclapi hclapi
Fish
Add the following to ~/.config/fish/completions/hclapi.fish:
complete -c hclapi -f -a '(hclapi --generate-shell-completion (commandline -cop))'
Man pages
Manual pages provide complete offline reference documentation directly in your terminal.
Info
Linux package installations like .deb, .rpm, and .pkg.tar.zst install man pages automatically.
Manual installation (Linux and macOS)
If you installed hclapi via precompiled binary or go install, you can install the man page manually:
# 1. Create the system man directory
sudo mkdir -p /usr/local/share/man/man1
# 2. Download the manual page
sudo curl -fsSL https://raw.githubusercontent.com/ju4n97/hclapi/main/man/hclapi.1 \
-o /usr/local/share/man/man1/hclapi.1
# 3. Update the system man database (optional)
sudo mandb 2>/dev/null || true
View manual