Metadata-Version: 2.4
Name: vpsgui
Version: 1.2.0
Summary: Official CLI and Python SDK for the VPSGUI agent - sign in to a host, read telemetry, run commands, and drive Docker, files, security and backups.
Author-email: NotGamerPratham <contact@notgamerpratham.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/NotGamerPratham/vpsgui
Project-URL: Documentation, https://github.com/NotGamerPratham/vpsgui/tree/main/sdk/python
Project-URL: Repository, https://github.com/NotGamerPratham/vpsgui
Project-URL: Bug Tracker, https://github.com/NotGamerPratham/vpsgui/issues
Keywords: vpsgui,vps,server,infrastructure,docker,cli,linux,monitoring,telemetry,devops,sdk,api-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# vpsgui

Official CLI and Python SDK for the [VPSGUI](https://github.com/NotGamerPratham/vpsgui) agent
REST API.

## Install

```bash
pip install vpsgui
```

Requires Python 3.8+. This installs both the `vpsgui` command and the library.

## The CLI

```bash
vpsgui login vps.example.com
```

`login` asks for the agent token with echo off, checks it against the agent, and only then writes
`~/.vpsgui/config.json` with mode `0600`. Nothing is saved if the credentials do not work.

| Command | What it does |
| --- | --- |
| `vpsgui login [url]` | Save credentials for a host, after checking they work |
| `vpsgui whoami` | Show the active profile and confirm the agent still accepts it |
| `vpsgui logout` | Forget this machine's copy of the token |
| `vpsgui status` | CPU, memory, disk, and any failing checks |
| `vpsgui health` | Every health check. Exits non-zero on a red one |
| `vpsgui ps` | Docker containers |
| `vpsgui ls [path]` | List a directory on the host |
| `vpsgui exec <command>` | Run a shell command. Exits non-zero when the command does |
| `vpsgui profiles` | List saved hosts |
| `vpsgui use <profile>` | Switch the default host |

Several hosts are several profiles; `--profile` works on every command.

```bash
vpsgui login vps-2.example.com --profile staging
vpsgui exec --profile staging 'systemctl restart nginx'
```

In CI, set `VPSGUI_API_URL` and `VPSGUI_AGENT_TOKEN` instead of logging in - they take precedence
over any saved profile, so nothing touches the disk.

The npm package `vpsgui` installs a CLI by the same name that reads the same config file, so it
does not matter which one wins on your `PATH`.

## The agent token is a root password

Every endpoint except `health()` requires the agent token, and that token grants **root-equivalent
control of the host**: shell execution, package installs, and filesystem read/write. Read it from
the environment, never commit it, and only talk to the agent over HTTPS - it travels in the
`Authorization` header.

## The library

```python
import os
from vpsgui import VpsguiClient

with VpsguiClient(
    base_url="https://vps.example.com/api/v1",
    token=os.environ["VPSGUI_AGENT_TOKEN"],
) as client:
    telemetry = client.system.telemetry()
    print(f"CPU {telemetry['cpuPercent']}% across {telemetry['cpuCores']} cores")

    for container in client.docker.list_containers():
        print(container["name"], container["state"], container["image"])
```

## API

| Resource | Methods |
| :--- | :--- |
| `client.nodes` | `get()`, `list()`, `topology()`, `health()` |
| `client.system` | `telemetry()`, `processes()`, `services()`, `service_action(name, action)`, `packages()`, `install_package(name)`, `users()` |
| `client.docker` | `list_containers()`, `list_images()`, `container_action(id, action)`, `remove_image(id, force=False)` |
| `client.files` | `list(path)`, `read(path)`, `write(path, content)`, `mkdir(path)`, `delete(path, recursive=False)`, `rename(src, dst)` |
| `client.security` | `firewall_rules()`, `apply_firewall_rule(...)`, `ssh_keys()`, `audit_logs()`, `list_secrets()`, `save_secret(...)`, `delete_secret(name)`, `reveal_secret(name)` |
| `client.network` | `interfaces()`, `ip_info(ip=None)` |
| `client.storage` | `partitions()` |
| `client.backups` | `list()`, `create(source_path, label=None)`, `delete(name)`, `restore(name, destination)` |
| `client.deployments` | `list()`, `pull(path)` |
| `client.catalog` | `list()` |
| `client.automation` | `workflows()` |
| `client.queue` | `jobs()` |
| `client.databases` | `list()` |
| `client.proxy` | `rules()` |
| `client.terminal` | `exec(command)` |
| top level | `health()`, `info()`, `close()` |

## Errors

```python
from vpsgui import VpsguiClient, VpsguiError

try:
    client.system.telemetry()
except VpsguiError as e:
    # status is 0 for transport failures (timeout, DNS, connection refused).
    print(e.status, e.endpoint, e.message)
    if e.is_auth_error:
        print("Bad token, or locked out after repeated failures.")
```

## `None` values are deliberate

Fields the agent cannot determine are `None` rather than guessed. Check before formatting:

- `smartHealth` - needs `smartctl` and raw device access
- `cpuPercent` on a process - Windows `tasklist` reports none
- `city` / `region` from `ip_info()` - only when the provider reports nothing (e.g. a bogon address)
- `size` / `tables` / `keys` on a database - would need per-engine credentials
- `downloadsCount` / `rating` on a catalog item - the agent queries no registry

`read()` also returns `truncated: True` and `editable: False` for a file that exceeded the read cap.
**Do not write that content back** - it would truncate the file on disk.

## License

MIT © [NotGamerPratham](https://notgamerpratham.com)
