proxcli 0.1.0__tar.gz

proxcli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+        with:
+          enable-cache: true
+
+      - run: uv sync
+      - run: uv run ruff check .
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+        with:
+          enable-cache: true
+
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest --cov=proxmox.client --cov=proxmox.config --cov=proxmox.output --cov-report=xml
+
+  build:
+    runs-on: ubuntu-24.04
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - uses: astral-sh/setup-uv@d4a5f06b29e0840685266df17132b0834efba237 # v5.2.2
+        with:
+          enable-cache: true
+
+      - run: uv sync
+      - run: uv build
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.0
+        with:
+          name: dist
+          path: dist/

proxcli-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE / Editor
+*.swp
+*.swo
+*~
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# Rust cache
+.ruff_cache/

proxcli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

proxcli-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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]
+
+## [0.1.0] - 2026-06-20
+
+### Added
+- Initial release.
+- `proxmox auth login|status|clear` — credential management (password + API token).
+- `proxmox vm` subcommand: `list`, `show`, `create`, `start`, `stop`, `reboot`, `suspend`, `resume`, `delete`.
+- `proxmox container` subcommand: `list`, `show`, `create`, `start`, `stop`, `delete`.
+- `proxmox node` subcommand: `list`, `show`, `status`.
+- `proxmox storage` subcommand: `list`, `show`, `content`.
+- `proxmox cluster` subcommand: `status`.
+- `proxmox task` subcommand: `list`, `show`.
+- Output formats: `json` (default), `table` (rich), `yaml`.
+- Global flags: `--dry-run`, `--insecure`, `--timeout`, `--verbose`, `--output`, `--password-stdin`.
+- `PROXMOX_PASSWORD` environment variable support.
+- Credential persistence in XDG config (`~/.config/proxmox-cli/credentials.json`, `0600`).
+- Retry with exponential backoff on 5xx responses.
+- CSRF ticket auto-refresh on 401.
+- AI-agent-friendly: default JSON output, strict exit codes, `--dry-run` mode.
+
+[0.1.0]: https://github.com/xezpeleta/proxmox-cli/releases/tag/v0.1.0

proxcli-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: proxcli
+Version: 0.1.0
+Summary: A CLI tool to interact with Proxmox VE nodes and clusters via the REST API
+Author-email: Xabi Ezpeleta <xezpeleta@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Description-Content-Type: text/markdown
+
+# proxmox
+
+A CLI tool to interact with [Proxmox VE](https://www.proxmox.com/) nodes and clusters via the REST API.
+
+Designed to be easy for humans (table output, ergonomic flags) and AI agents (structured JSON, strict exit codes, `--dry-run`). Provides a higher-level abstraction over the raw Proxmox API.
+
+## Installation
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# From PyPI
+uv tool install proxmox
+
+# From Git
+uv tool install git+https://github.com/xezpeleta/proxmox-cli.git
+
+# From local checkout
+uv tool install .
+```
+
+## Quickstart
+
+```bash
+# Authenticate (password-based)
+proxmox auth login --url https://192.168.1.10:8006 --username root@pam --password your_password
+
+# Or with an API token
+proxmox auth login --url https://192.168.1.10:8006 --username root@pam --api-token 'root@pam!my-token=deadbeef...'
+
+# Check auth status
+proxmox auth status
+
+# List VMs
+proxmox vm list
+
+# Show a specific VM
+proxmox vm show 100
+
+# Create a VM
+proxmox vm create --node pve01 --vmid 110 --memory 2048 --cores 2 --name webserver
+
+# Start / stop / reboot
+proxmox vm start 110
+proxmox vm stop 110
+proxmox vm reboot 110
+
+# Delete (with purge)
+proxmox vm delete 110 --purge
+```
+
+## Authentication
+
+Credentials are stored in `~/.config/proxmox-cli/credentials.json` with restrictive permissions (`0600`).
+
+### Auth methods
+
+| Method | Command |
+|---|---|
+| Password | `proxmox auth login --url ... --username ... --password ...` |
+| Password (stdin) | `echo "$PASS" \| proxmox auth login --url ... --username ... --password-stdin` |
+| API token | `proxmox auth login --url ... --username ... --api-token 'user!tokenid=secret'` |
+
+### Override credentials per command
+
+```bash
+proxmox --url https://other-pve:8006 --username admin@pam --password pass123 vm list
+```
+
+### Environment variable
+
+```bash
+export PROXMOX_PASSWORD=mysecret
+proxmox vm list --username root@pam --url https://pve:8006
+```
+
+### Self-signed certificates
+
+```bash
+proxmox --insecure vm list
+```
+
+## Command Reference
+
+### Global flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--url` | (config file) | Proxmox API URL |
+| `--username` | (config file) | Username |
+| `--password` | — | Password |
+| `--password-stdin` | — | Read password from stdin |
+| `--api-token` | — | API token (`user!tokenid=secret`) |
+| `--output` | `json` | Output format: `json`, `table`, `yaml` |
+| `--dry-run` | off | Print the API request without executing |
+| `--insecure` | off | Skip TLS verification |
+| `--timeout` | `30` | Request timeout in seconds |
+| `--verbose` | off | Debug output to stderr |
+| `--version` | — | Show version |
+
+### Auth
+
+```bash
+proxmox auth login   # Save credentials
+proxmox auth status  # Show current auth context
+proxmox auth clear   # Remove saved credentials
+```
+
+### VM (QEMU)
+
+```bash
+proxmox vm list [--node <node>]
+proxmox vm show <vmid> [--node <node>]
+proxmox vm create --node <node> --vmid <id> --memory <mb> [--cores <n>] [--name <name>] [--storage <name>] [--net <config>]
+proxmox vm start <vmid> [--node <node>]
+proxmox vm stop <vmid> [--node <node>]
+proxmox vm reboot <vmid> [--node <node>]
+proxmox vm suspend <vmid> [--node <node>]
+proxmox vm resume <vmid> [--node <node>]
+proxmox vm delete <vmid> [--node <node>] [--force] [--purge]
+```
+
+### Container (LXC)
+
+```bash
+proxmox container list [--node <node>]
+proxmox container show <vmid> [--node <node>]
+proxmox container create --node <node> --vmid <id> --ostemplate <tmpl> [--memory <mb>] [--cores <n>] [--storage <name>]
+proxmox container start <vmid> [--node <node>]
+proxmox container stop <vmid> [--node <node>]
+proxmox container delete <vmid> [--node <node>] [--force] [--purge]
+```
+
+### Node
+
+```bash
+proxmox node list
+proxmox node show <node>
+proxmox node status [<node>]
+```
+
+### Storage
+
+```bash
+proxmox storage list [--node <node>]
+proxmox storage show <storage>
+proxmox storage content <storage> [--node <node>]
+```
+
+### Cluster
+
+```bash
+proxmox cluster status
+```
+
+### Task
+
+```bash
+proxmox task list [--node <node>]
+proxmox task show <upid>
+```
+
+## Output Formats
+
+### JSON (default)
+
+```json
+[
+  {
+    "vmid": 100,
+    "name": "webserver",
+    "status": "running",
+    "cpu": 0.05,
+    "mem": 2048
+  }
+]
+```
+
+### Table
+
+```
+┌──────┬───────────┬─────────┬───────┬──────┐
+│ vmid │ name      │ status  │ cpu   │ mem  │
+├──────┼───────────┼─────────┼───────┼──────┤
+│ 100  │ webserver │ running │ 0.05  │ 2048 │
+└──────┴───────────┴─────────┴───────┴──────┘
+```
+
+### YAML
+
+```yaml
+- vmid: 100
+  name: webserver
+  status: running
+  cpu: 0.05
+  mem: 2048
+```
+
+## AI Agent Usage
+
+Every command emits valid JSON by default (stdout) and diagnostic messages on stderr. Exit codes follow Unix conventions.
+
+```bash
+# Dry-run to preview the API call
+proxmox --dry-run vm create --node pve01 --vmid 110 --memory 1024
+
+# Machine-parseable JSON output
+proxmox --output json vm list | jq '.[] | {vmid, status}'
+
+# Check exit code
+proxmox vm show 999 || echo "VM not found"
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/xezpeleta/proxmox-cli.git
+cd proxmox-cli
+
+# Install dev dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=proxmox --cov-report=term-missing
+
+# Lint
+uv run ruff check .
+
+# Build
+uv build
+```
+
+## License
+
+MIT