ibee-cli 0.4.1__tar.gz → 0.5.0__tar.gz

ibee_cli-0.5.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: ibee-cli
+Version: 0.5.0
+Summary: Official command-line interface for the IBEE Solutions cloud platform
+Author-email: IBEE Solutions <support@ibee.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://ibee.ai
+Project-URL: Documentation, https://ibee.ai/docs/api-reference
+Project-URL: Repository, https://github.com/devs-ibee/ibee-cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ibee<0.6.0,>=0.5.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# IBEE Solutions CLI
+
+Official command-line interface for the IBEE Solutions cloud platform, built on the
+[`ibee` Python SDK](https://github.com/devs-ibee/ibee-python). Each command makes one
+SDK call and prints the server's answer; the server decides prices, eligibility,
+limits and states.
+
+## Installation
+
+```bash
+pip install ibee-cli
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Create an API token in the portal under **Settings > API Tokens**, then:
+
+```bash
+export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
+export IBEE_WORKSPACE_ID="710995"
+```
+
+Both can also be passed per command with `--token` and `--workspace`.
+
+## Usage
+
+```bash
+ibee compute sites
+ibee compute plans --vm-type cloud --site-id SITE_ID
+ibee compute images --vm-type cloud --site-id SITE_ID
+
+ibee vms create web-1 --site-id SITE_ID --plan-id PLAN_ID --template-id IMAGE_ID \
+  --ssh-key-file ~/.ssh/id_ed25519.pub --wait
+ibee vms list
+ibee vms get VM_ID
+ibee vms stop VM_ID --wait
+ibee vms delete VM_ID --yes
+
+ibee ops wait OPERATION_ID
+ibee vpcs list
+ibee reserved-ips list
+ibee firewalls list
+ibee load-balancers list
+ibee block-storage list
+ibee buckets list
+ibee cdn list
+ibee secrets stores list
+ibee billing eligibility --resource-type cpu_vm
+```
+
+`ibee --help` and `ibee GROUP --help` list every command. `gpus` takes the same
+commands as `vms`. Until the server resolves VM SKUs itself, `vms/gpus create` fills
+CPU, RAM, disk and OS from the plan and the image and sends the plan's billing SKU for
+`--billing-term` (see the SDK's `held.py`).
+
+## Global options
+
+| Option | Environment variable | Meaning |
+| --- | --- | --- |
+| `--token` | `IBEE_TOKEN` (or `IBEE_API_TOKEN`) | API token |
+| `--workspace`, `-w` | `IBEE_WORKSPACE_ID` | Workspace ID |
+| `--dev` | `IBEE_ENV=dev` | Use the development environment |
+| `--base-url` | `IBEE_BASE_URL`, `IBEE_ENDPOINT` | Custom API endpoint |
+| `-o`, `--output` | `IBEE_OUTPUT` | `table`, `json`, `yaml` or `id` |
+| `--json` | | Same as `-o json` |
+| `--yes`, `-y` | `IBEE_ASSUME_YES=1` | Answer yes to every confirmation |
+
+The endpoint is chosen in this order: `--base-url`, `IBEE_BASE_URL`, `IBEE_ENDPOINT`,
+`--dev`, `IBEE_ENV`; the default is production, `https://api.ibee.ai/v1`. Without
+`-o`, each command keeps its usual format (tables for most lists, JSON for single
+resources).
+
+## Errors
+
+Every error prints the HTTP status and the server's fields as sent:
+
+```text
+Error: HTTP 402
+  code: billing_denied
+  reason: resource_limit_reached
+  message: -
+  request_id: 6f1c2e...
+  admission_context_id: adm_...
+```
+
+With `-o json` the same fields, plus the raw `body`, are printed on stderr as
+`{"error": {...}}`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Failed, cancelled or timed-out operation (`--wait`), declined confirmation, or another error |
+| 2 | Usage or configuration error (missing token or workspace, unsafe endpoint, token for the other environment); nothing was sent |
+| 3 | `--wait` reached `--timeout` while the operation was still running; resume with `ibee ops wait OPERATION_ID` |
+| 4 | Network error (no HTTP answer) |
+| 10, 11, 12, 13, 14 | HTTP 400, 401, 402, 403, 404 |
+| 15, 16, 17, 18 | HTTP 409, 422, 423, 429 |
+| 19 | HTTP 5xx |
+
+## Retries and idempotency keys
+
+The SDK retries reads on 429, 502, 503 and 504, and writes that carry an idempotency
+key on 429 and 503, never on a billing or admission answer. Write commands that take
+`--idempotency-key KEY` send it unchanged (without one the SDK sends a random key);
+after a retryable failure the CLI prints `Retry safely with: --idempotency-key KEY` so
+the command can be repeated without doing the write twice. `--wait` polls the
+operation every `--poll-interval` seconds (default 5) for up to `--timeout` seconds
+(default 1200).
+
+## Related
+
+- [Python SDK](https://github.com/devs-ibee/ibee-python): `pip install ibee`
+- [API documentation](https://ibee.ai/docs/api-reference)

ibee_cli-0.5.0/README.md

@@ -0,0 +1,117 @@
+# IBEE Solutions CLI
+
+Official command-line interface for the IBEE Solutions cloud platform, built on the
+[`ibee` Python SDK](https://github.com/devs-ibee/ibee-python). Each command makes one
+SDK call and prints the server's answer; the server decides prices, eligibility,
+limits and states.
+
+## Installation
+
+```bash
+pip install ibee-cli
+```
+
+Requires Python 3.10+.
+
+## Authentication
+
+Create an API token in the portal under **Settings > API Tokens**, then:
+
+```bash
+export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
+export IBEE_WORKSPACE_ID="710995"
+```
+
+Both can also be passed per command with `--token` and `--workspace`.
+
+## Usage
+
+```bash
+ibee compute sites
+ibee compute plans --vm-type cloud --site-id SITE_ID
+ibee compute images --vm-type cloud --site-id SITE_ID
+
+ibee vms create web-1 --site-id SITE_ID --plan-id PLAN_ID --template-id IMAGE_ID \
+  --ssh-key-file ~/.ssh/id_ed25519.pub --wait
+ibee vms list
+ibee vms get VM_ID
+ibee vms stop VM_ID --wait
+ibee vms delete VM_ID --yes
+
+ibee ops wait OPERATION_ID
+ibee vpcs list
+ibee reserved-ips list
+ibee firewalls list
+ibee load-balancers list
+ibee block-storage list
+ibee buckets list
+ibee cdn list
+ibee secrets stores list
+ibee billing eligibility --resource-type cpu_vm
+```
+
+`ibee --help` and `ibee GROUP --help` list every command. `gpus` takes the same
+commands as `vms`. Until the server resolves VM SKUs itself, `vms/gpus create` fills
+CPU, RAM, disk and OS from the plan and the image and sends the plan's billing SKU for
+`--billing-term` (see the SDK's `held.py`).
+
+## Global options
+
+| Option | Environment variable | Meaning |
+| --- | --- | --- |
+| `--token` | `IBEE_TOKEN` (or `IBEE_API_TOKEN`) | API token |
+| `--workspace`, `-w` | `IBEE_WORKSPACE_ID` | Workspace ID |
+| `--dev` | `IBEE_ENV=dev` | Use the development environment |
+| `--base-url` | `IBEE_BASE_URL`, `IBEE_ENDPOINT` | Custom API endpoint |
+| `-o`, `--output` | `IBEE_OUTPUT` | `table`, `json`, `yaml` or `id` |
+| `--json` | | Same as `-o json` |
+| `--yes`, `-y` | `IBEE_ASSUME_YES=1` | Answer yes to every confirmation |
+
+The endpoint is chosen in this order: `--base-url`, `IBEE_BASE_URL`, `IBEE_ENDPOINT`,
+`--dev`, `IBEE_ENV`; the default is production, `https://api.ibee.ai/v1`. Without
+`-o`, each command keeps its usual format (tables for most lists, JSON for single
+resources).
+
+## Errors
+
+Every error prints the HTTP status and the server's fields as sent:
+
+```text
+Error: HTTP 402
+  code: billing_denied
+  reason: resource_limit_reached
+  message: -
+  request_id: 6f1c2e...
+  admission_context_id: adm_...
+```
+
+With `-o json` the same fields, plus the raw `body`, are printed on stderr as
+`{"error": {...}}`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Failed, cancelled or timed-out operation (`--wait`), declined confirmation, or another error |
+| 2 | Usage or configuration error (missing token or workspace, unsafe endpoint, token for the other environment); nothing was sent |
+| 3 | `--wait` reached `--timeout` while the operation was still running; resume with `ibee ops wait OPERATION_ID` |
+| 4 | Network error (no HTTP answer) |
+| 10, 11, 12, 13, 14 | HTTP 400, 401, 402, 403, 404 |
+| 15, 16, 17, 18 | HTTP 409, 422, 423, 429 |
+| 19 | HTTP 5xx |
+
+## Retries and idempotency keys
+
+The SDK retries reads on 429, 502, 503 and 504, and writes that carry an idempotency
+key on 429 and 503, never on a billing or admission answer. Write commands that take
+`--idempotency-key KEY` send it unchanged (without one the SDK sends a random key);
+after a retryable failure the CLI prints `Retry safely with: --idempotency-key KEY` so
+the command can be repeated without doing the write twice. `--wait` polls the
+operation every `--poll-interval` seconds (default 5) for up to `--timeout` seconds
+(default 1200).
+
+## Related
+
+- [Python SDK](https://github.com/devs-ibee/ibee-python): `pip install ibee`
+- [API documentation](https://ibee.ai/docs/api-reference)

{ibee_cli-0.4.1 → ibee_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ibee-cli"
-version = "0.4.1"
+version = "0.5.0"
 description = "Official command-line interface for the IBEE Solutions cloud platform"
 readme = "README.md"
 license = "MIT"
@@ -18,7 +18,7 @@ classifiers = [
     "Environment :: Console",
 ]
 dependencies = [
-    "ibee>=0.4.1,<0.5.0",
+    "ibee>=0.5.0,<0.6.0",
     "httpx>=0.27",
     "typer>=0.12",
     "click>=8.1",

{ibee_cli-0.4.1 → ibee_cli-0.5.0}/src/ibee_cli/__init__.py

@@ -1,3 +1,3 @@
 """IBEE Solutions command-line interface."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"

ibee_cli-0.5.0/src/ibee_cli/commands/billing.py

@@ -0,0 +1,44 @@
+"""Billing eligibility (a diagnostic: the real request is decided by the server)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import get_client, get_settings
+from ..helpers import compact_payload, field
+from ..render import emit, handle_api_errors, to_data
+
+app = typer.Typer(help="Billing resource eligibility", no_args_is_help=True)
+
+
+@app.command("eligibility")
+@handle_api_errors
+def resource_eligibility(
+    ctx: typer.Context,
+    sku_code: Optional[str] = typer.Option(None, "--sku-code", help="Billing SKU from an IBEE product catalog"),
+    estimated_cost_minor: Optional[int] = typer.Option(None, "--estimated-cost-minor", help="Cost in the currency's minor unit"),
+    operation: Optional[str] = typer.Option(None, "--operation", help="Billing operation, for example CREATE_RESOURCE"),
+    resource_type: Optional[str] = typer.Option(None, "--resource-type", help="For example cpu_vm or block_volume"),
+    quantity: Optional[int] = typer.Option(None, "--quantity"),
+    size_gb: Optional[int] = typer.Option(None, "--size-gb"),
+    require: bool = typer.Option(False, "--require", help="Exit 1 unless the answer is allowed=true"),
+) -> None:
+    """Ask Billing whether the workspace may create a billable resource.
+
+    Prints Billing's decision as returned (JSON by default; -o table|yaml|id). Exits 0 for
+    any decision, unless --require is given and allowed is not true.
+    """
+    settings = get_settings(ctx)
+    decision = get_client(settings).billing.check_resource_eligibility(
+        **compact_payload(
+            sku_code=sku_code, estimated_cost_minor=estimated_cost_minor, operation=operation,
+            resource_type=resource_type, quantity=quantity, size_gb=size_gb,
+        )
+    )
+    data = to_data(decision)
+    rows = list(data.items()) if isinstance(data, dict) else []
+    emit(decision, settings=settings, default="json", title="Billing eligibility", headers=("Field", "Value"), rows=rows, id_field="organization_id")
+    if require and field(decision, "allowed") is not True:
+        raise typer.Exit(code=1)

ibee_cli-0.5.0/src/ibee_cli/commands/block_storage.py

@@ -0,0 +1,186 @@
+"""Standalone Block Storage volumes (``ibee block-storage``).
+
+Each command makes one SDK call and prints the server's answer; the server checks
+names, sizes, plans, states and billing. To attach a volume to a VM use
+``ibee vms|gpus volume-attach`` and ``volume-detach``.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..context import get_client, get_settings
+from ..helpers import compact_payload, confirm_destructive, field, idempotency_key_option
+from ..render import cell, emit, handle_api_errors, print_json
+
+app = typer.Typer(
+    help="Standalone Block Storage volumes. Attach them to VMs with 'ibee vms volume-attach'.",
+    no_args_is_help=True,
+)
+
+ID_FIELD = "id"
+LIST_HEADERS = ("ID", "Name", "Size (GB)", "State", "Site", "Attached to")
+NODE_LEVEL_NOTE = (
+    "Advanced: records a storage-node attachment only. Use 'ibee vms volume-attach' / 'volume-detach' for VMs."
+)
+
+
+def _block_storage(ctx: typer.Context):
+    settings = get_settings(ctx)
+    return settings, get_client(settings).block_storage
+
+
+def _first(item, *names):
+    """The first of ``names`` that has a value (display only)."""
+    return next((value for value in (cell(item, name) for name in names) if value not in (None, "")), None)
+
+
+def _row(volume) -> tuple:
+    attached = ", ".join(str(_first(a, "vm_name", "vm_id", "node_name")) for a in cell(volume, "attachments") or [])
+    columns = ("id", "name", "size_gb", "state")
+    return (*(cell(volume, c) for c in columns), _first(volume, "site_name", "site_id"), attached or None)
+
+
+@app.command("list")
+@handle_api_errors
+def list_volumes(ctx: typer.Context) -> None:
+    """List volumes in the workspace (-o table shows a summary table)."""
+    settings, storage = _block_storage(ctx)
+    volumes = list(storage.list_block_volumes() or [])
+    emit(volumes, settings=settings, default="json", headers=LIST_HEADERS, rows=[_row(v) for v in volumes],
+         title="Block Storage volumes", id_field=ID_FIELD)
+
+
+@app.command("create")
+@handle_api_errors
+def create_volume(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Volume name"),
+    size_gb: int = typer.Option(..., "--size-gb", help="Size in GB"),
+    site_id: str = typer.Option(..., "--site-id", help="Placement site ID (see 'ibee compute sites')"),
+    site_name: Optional[str] = typer.Option(None, "--site-name", help="Site display name"),
+    sku_code: Optional[str] = typer.Option(None, "--sku-code", help="Block Storage SKU from the server's catalog"),
+    volume_class: Optional[str] = typer.Option(None, "--class", help="capacity, balanced or performance"),
+    replica_count: Optional[int] = typer.Option(None, "--replicas", help="Replica count"),
+    backup_enabled: Optional[bool] = typer.Option(None, "--backup-enabled/--no-backup", help="Volume backups"),
+    idempotency_key: Optional[str] = idempotency_key_option(),
+) -> None:
+    """Create a volume. The server resolves the plan and billing."""
+    settings, storage = _block_storage(ctx)
+    result = storage.create_block_volume(
+        name=name,
+        size_gb=size_gb,
+        site_id=site_id,
+        **compact_payload(
+            site_name=site_name,
+            sku_code=sku_code,
+            volume_class=volume_class,
+            replica_count=replica_count,
+            backup_enabled=backup_enabled,
+            idempotency_key=idempotency_key,
+        ),
+    )
+    if settings.output == "id":
+        typer.echo(str(field(field(result, "volume"), "id") or ""))
+        return
+    print_json(result)
+
+
+@app.command("get")
+@handle_api_errors
+def get_volume(ctx: typer.Context, volume_id: str = typer.Argument(..., help="Volume ID")) -> None:
+    """Show a volume and its attachments."""
+    _settings, storage = _block_storage(ctx)
+    print_json(storage.get_block_volume(volume_id), id_field=ID_FIELD)
+
+
+@app.command("operations")
+@handle_api_errors
+def list_operations(ctx: typer.Context, volume_id: str = typer.Argument(..., help="Volume ID")) -> None:
+    """List a volume's operations."""
+    _settings, storage = _block_storage(ctx)
+    print_json(storage.list_block_volume_operations(volume_id), id_field=ID_FIELD)
+
+
+@app.command("attach", help=f"Attach a volume to a storage node. {NODE_LEVEL_NOTE}")
+@handle_api_errors
+def attach_volume(
+    ctx: typer.Context,
+    volume_id: str = typer.Argument(..., help="Volume ID"),
+    node_name: str = typer.Option(..., "--node-name", help="Storage node name"),
+    mode: Optional[str] = typer.Option(None, "--mode", help="single-writer or multi-writer"),
+    vm_id: Optional[str] = typer.Option(None, "--vm-id"),
+    vm_name: Optional[str] = typer.Option(None, "--vm-name"),
+    vm_state: Optional[str] = typer.Option(None, "--vm-state"),
+    vm_site_id: Optional[str] = typer.Option(None, "--vm-site-id"),
+    vm_type: Optional[str] = typer.Option(None, "--vm-type", help="cloud or gpu"),
+    idempotency_key: Optional[str] = idempotency_key_option(),
+) -> None:
+    _settings, storage = _block_storage(ctx)
+    print_json(storage.attach_block_volume(
+        volume_id,
+        node_name=node_name,
+        **compact_payload(mode=mode, vm_id=vm_id, vm_name=vm_name, vm_state=vm_state, vm_site_id=vm_site_id,
+                          vm_type=vm_type, idempotency_key=idempotency_key),
+    ))
+
+
+@app.command("detach", help=f"Detach a volume from a storage node. {NODE_LEVEL_NOTE}")
+@handle_api_errors
+def detach_volume(
+    ctx: typer.Context,
+    volume_id: str = typer.Argument(..., help="Volume ID"),
+    node_name: str = typer.Option(..., "--node-name", help="Storage node name"),
+    force: Optional[bool] = typer.Option(None, "--force", help="Ask the server to skip its unmount check"),
+    confirm_unmounted: Optional[bool] = typer.Option(
+        None, "--confirm-unmounted", help="I have unmounted this volume from the server"
+    ),
+    vm_state: Optional[str] = typer.Option(None, "--vm-state"),
+    vm_type: Optional[str] = typer.Option(None, "--vm-type", help="cloud or gpu"),
+    reason: Optional[str] = typer.Option(None, "--reason"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    idempotency_key: Optional[str] = idempotency_key_option(),
+) -> None:
+    settings, storage = _block_storage(ctx)
+    confirm_destructive(settings, f"Detach volume '{volume_id}' from node '{node_name}'?", yes)
+    print_json(storage.detach_block_volume(
+        volume_id,
+        node_name=node_name,
+        **compact_payload(force=force, confirm_unmounted=confirm_unmounted, vm_state=vm_state, vm_type=vm_type,
+                          reason=reason, idempotency_key=idempotency_key),
+    ))
+
+
+@app.command("resize")
+@handle_api_errors
+def resize_volume(
+    ctx: typer.Context,
+    volume_id: str = typer.Argument(..., help="Volume ID"),
+    new_size_gb: int = typer.Option(..., "--new-size-gb", help="New size in GB"),
+    allow_online: Optional[bool] = typer.Option(None, "--allow-online", help="Resize while attached to a running VM"),
+    vm_state: Optional[str] = typer.Option(None, "--vm-state", help="State of the attached VM"),
+    idempotency_key: Optional[str] = idempotency_key_option(),
+) -> None:
+    """Resize a volume. After growing it, extend the filesystem inside the VM."""
+    _settings, storage = _block_storage(ctx)
+    print_json(storage.resize_block_volume(
+        volume_id,
+        new_size_gb=new_size_gb,
+        **compact_payload(allow_online=allow_online, vm_state=vm_state, idempotency_key=idempotency_key),
+    ))
+
+
+@app.command("delete")
+@handle_api_errors
+def delete_volume(
+    ctx: typer.Context,
+    volume_id: str = typer.Argument(..., help="Volume ID"),
+    force: Optional[bool] = typer.Option(None, "--force", help="Ask the server to detach and delete anyway"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+) -> None:
+    """Delete a volume and its data."""
+    settings, storage = _block_storage(ctx)
+    confirm_destructive(settings, f"Delete Block Storage volume '{volume_id}'?", yes)
+    print_json(storage.delete_block_volume(volume_id, **compact_payload(force=force)), id_field=ID_FIELD)