iolave · iolave · Aug 11, 2025 · Aug 11, 2025 · Aug 11, 2025 · Aug 11, 2025
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -30,10 +30,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install docs dependencies
-        run: make install-docs-dependencies
       - name: Generate docs
-        run: make generate-docs
+        run: make docs
       - name: Setup Pages
         id: pages
         uses: actions/configure-pages@v5

diff --git a/.testcoverage.yml b/.testcoverage.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+<!-- ################# 
+     # PVE API Wrapper
+     ################# -->
+### PVE API wrapper
+
+#### Fixed
+- PVE original passthrough handler now properly includes the request query params (resolves [#4](https://github.com/iolave/go-proxmox/issues/4)).
+
+<!-- ################ 
+     # PVE API client
+     ################ -->
+### PVE API client
+
+#### Added
+- Added the `api` package that contains raw proxmox api implementations for:
+    - `/api2/json/access`
+    - `/api2/json/cluster`
+
+#### Changed
+- Renamed `pve.PVE` to `pve.Client`.
+- Moved the `GetVersion` method from `pkg/pve` to `pkg/pve/core`.
 
 ## [v0.7.1]
 ### PVE API client

diff --git a/Makefile b/Makefile
@@ -1,13 +1,5 @@
 GOBIN ?= $$(go env GOPATH)/bin
 
-.PHONY: install-docs-dependencies
-install-docs-dependencies:
-	./scripts/install-docs-deps.sh
-
-.phony: install-dependencies
-install-dependencies: install-docs-dependencies
-	go mod tidy
-
 .PHONY: test
 test:
 	go test -v ./...
@@ -16,16 +8,16 @@ test:
 coverage:
 	./scripts/coverage.sh
 
-.PHONY: generate-docs
-generate-docs: install-docs-dependencies
-	bash ./scripts/generate-docs.sh
+.PHONY: docs
+docs:
+	./scripts/generate-docs.sh
 
 .PHONY: preview-docs
-preview-docs: install-docs-dependencies generate-docs
-	bash ./scripts/preview-docs.sh
+preview-docs: 
+	./scripts/generate-docs.sh -p
 
 .PHONY: build
-build: install-dependencies
+build: 
 	$(eval $@GOOS = linux)
 	$(eval $@GOARCH = amd64)
 	CGO_ENABLED=0 GOOS=$($@GOOS) GOARCH=$($@GOARCH) go build -ldflags="-extldflags=-static" -o "bin/pve-api-wrapper-$($@GOOS)-$($@GOARCH)" ./cmd/pve_api_wrapper/pve_api_wrapper.go

diff --git a/README.md b/README.md
@@ -3,13 +3,73 @@
 > [!WARNING]
 > All versions released prior to `v1.0.0` are to be considered [breaking changes](https://semver.org/#how-do-i-know-when-to-release-100)
 
-go-proxmox is a set of tools I built in order to manage proxmox instances remotely without too much effort.
+A fully-featured set of tools for Proxmox Virtual Environment.
+This repository provides three layers:
 
-## Tools
-- Proxmox go client: To see a list of all implemented api endpoints and more information, click [here].
-- Proxmox cli (not available yet): Proxmox remote management tool.
-- Proxmox [api wrapper]: Proxmox api wrapper that adds missing features to proxmox default one.
+- Low-level 1:1 API implementation: minimal abstractions, closely matching the upstream Proxmox REST API. To see a list of all implemented api endpoints and more information, click [here].
+- [API Wrapper] (binary): exposes additional features and allows original api calls to be passed through.
+- High-level, ergonomic client – a set of well-documented Go interfaces that smooths over quirks of the raw API and integrates extensions provided by the wrapper.
 
 [here]: https://go-proxmox.iolave.com/go-client/
-[api wrapper]: https://go-proxmox.iolave.com/api-wrapper/
-[telmate/terraform-provider-proxmox]: https://github.com/Telmate/terraform-provider-proxmox
+[API Wrapper]: https://go-proxmox.iolave.com/api-wrapper/
+
+## Features
+### 1:1 Proxmox API Implementation
+- Direct mapping of Proxmox endpoints, parameters, and responses.
+- As close to upstream behavior as possible.
+- Useful for users who need full control or raw input/output.
+- Unclear or inconsistent API behaviors are intentionally preserved (mirrors the original).
+
+### API Wrapper
+Small binary that exposes:
+
+- Original API.
+- Custom API with missing functionality from the native one.
+
+It is designed to be deployed on a Proxmox node.
+
+### High-level Client
+- Human-friendly Go API.
+- Strong typing and validation where the raw API is ambiguous.
+- Includes wrapper-only features
+
+## Project Structure
+```text
+.
+├── pkg/                  # Packages that can be imported by other projects
+│   │
+│   ├── api/              # Proxmox API 1:1 implementation
+│   ├── helpers/          # General purpose helpers
+│   └── pve/              # High-level Proxmox API client
+│
+├── cmd/                  # Command line tools
+│   │
+│   ├── pve-api-wrapper/  # Proxmox API wrapper
+│   └── gomarkdoc/        # Documentation generator
+│
+├── internal/             # API Wrapper internals
+├── scripts/              # Shell scripts, mostly for development and Makefile
+├── docs/                 # MKDocs documentation
+├── README.md             # This file
+├── Makefile              # Makefile for building, testing and documentation generation
+├── LICENSE               # License
+├── go.mod                # Go module definition
+├── go.sum                # Go module checksums
+└── mkdocs.yml            # MKDocs configuration
+```
+
+## Documentation
+- The go client documentation is available [here].
+- The API wrapper documentation is available [here](https://go-proxmox.iolave.com/api-wrapper/).
+
+## Contributing
+Contributions are welcome! 
+
+Please:
+
+- Open an issue before large changes.
+- Keep PRs focused and well‑scoped.
+- Include relevant tests.
+
+[here]: https://go-proxmox.iolave.com/go-client/
+[API Wrapper]: https://go-proxmox.iolave.com/api-wrapper/
diff --git a/cmd/gomarkdoc/main.go b/cmd/gomarkdoc/main.go
@@ -13,10 +13,9 @@ import (
 
 func main() {
 	packages := []string{
+		"api",
 		"pve",
 		"helpers",
-		"cloudflare",
-		"errors",
 	}
 
 	for i := 0; i < len(packages); i++ {

diff --git a/cmd/pve_api_wrapper/pve_api_wrapper.go b/cmd/pve_api_wrapper/pve_api_wrapper.go
@@ -7,7 +7,7 @@ import (
 
 	"github.com/alexflint/go-arg"
 	_ "github.com/iolave/go-proxmox/docs/api-wrapper"
-	"github.com/iolave/go-proxmox/internal/server"
+	"github.com/iolave/go-proxmox/internal/api_wrapper/server"
 )
 
 // @title			Proxmox API Wrapper

diff --git a/docs/api-wrapper/index.md b/docs/api-wrapper/index.md
@@ -10,10 +10,10 @@ The pve api wrapper is an http server ment to be installed on the proxmox host s
 
 ## Installation
 ### Latest release
-The installation script installs the `pve-api-wrapper` binary into `/usr/local/bin`.
+The installation script installs the latest `pve-api-wrapper` binary into `/usr/local/bin`.
 
 ```bash
-curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/tags/latest/scripts/install.sh | bash
+curl https://raw.githubusercontent.com/iolave/go-proxmox/refs/tags/latest/scripts/install-paw.sh | bash
 ```
 
 _Inspect the installation script code [here]._
@@ -51,7 +51,7 @@ pve-api-wrapper [--version] [--pve-host PVE-HOST] [--pve-port PVE-PORT] [--host
 sudo pve-api-wrapper service install
 ```
 
-[here]: https://github.com/iolave/go-proxmox/blob/latest/scripts/install.sh
+[here]: https://github.com/iolave/go-proxmox/blob/latest/scripts/install-paw.sh
 [reference]: https://go-proxmox.iolave.com/api-wrapper/reference/
 <!--
     TODO: host the shell script within the docs https://github.com/squidfunk/mkdocs-material/discussions/3458