Skip to content
Meshive GPU Cloud Docs

SDK & CLI Overview

Install the Meshive Python package, authenticate with an API key, and manage your account, workspaces, pods, storage, assets, GPUs, templates, serverless deployments, and host machines from the command line, from Python, or from an AI agent.

The meshive Python package ships a command-line tool and a Python SDK from a single install. Use the CLI to inspect and manage your account, workspaces, pods, and host machines from a terminal; use the SDK to do the same programmatically — both synchronously and with asyncio. The same operations are available to AI coding agents through the Meshive MCP server.

What you can do today

Section titled “What you can do today”

Reading mirrors what you see in the console:

  • Account — me (who the key belongs to), api-keys (your keys, prefixes only), credit and credit-history (balance, top-ups, refunds)
  • Workspaces — workspaces, workspace (cost and resource summary), members
  • Pods — pods / pod, plus pod-metrics for live CPU/RAM/GPU/disk usage and transactions / transaction for pod operations and why one failed
  • Storage — storages / storage (the volumes in a workspace)
  • Assets — assets / asset (datasets, models, outputs and their files) and asset-storage (managed usage, cost, credit status)
  • Catalog — gpus and cpus (GPUs and CPU lines you can rent right now, with prices), templates / template, and model-sets (the model sets a template can start with)
  • Serverless — servings / serving and tasks / task
  • Host — machines / machine, machine-metrics, and earnings for the machines you contribute as a host

Writing (needs a Read & write key — see below):

  • Workspaces — workspace-create (an empty workspace costs nothing; wait until it is running before creating anything in it), workspace-update (rename) and workspace-delete (only an empty workspace — see Deleting a workspace). Needs meshive 1.6 or later.
  • Pods — pod-create (shows the hourly estimate first, optionally with a model set), pod-update (change a pod like the console’s edit screen), pod-stop, pod-start, pod-restart, pod-delete
  • Storage — storage-create, storage-update (rename, grow, usage warning), storage-connect (one-time SSH/SFTP login), storage-delete
  • Serverless — serving-deploy, serving-scale, serving-pause, serving-resume, serving-delete, task-submit, task-stop
  • Logs — logs (a pod’s last lines) and task-logs

Every command has a Python SDK counterpart (client.list_gpus(), client.create_pod(), …) — see the SDK reference.

Install

Section titled “Install”

Requires Python 3.10+. The only runtime dependency is httpx (0.27 or later, below 1.0).

Terminal window
pip install "meshive>=1,<2"

Verify the install:

Terminal window
meshive --version

These references describe 1.x. In a requirements file, keep the same pin (meshive>=1,<2) so you get fixes without breaking changes. CPU lines, local storage created with a pod, template port changes, storage usage warnings, waiting starts, transaction lookup, editing pods and storage, connecting to storage over SSH and model sets arrived in 1.2 (1.1 was not released on its own); if you use them, pin meshive>=1.2,<2.

Upgrading from a pre-1.0 release

Section titled “Upgrading from a pre-1.0 release”

1.0.0 works with code written for the 0.1 releases; no changes are needed. Change your pin to meshive>=1,<2, reinstall, and regenerate your lock file if you use one. Most pre-1.0 releases are being removed from PyPI (0.1.4 stays; the 1.0.0 release notes list the dates), so a pin to one of them stops installing after its removal date. Environments where one is already installed keep working.

Authentication

Section titled “Authentication”

The SDK and CLI authenticate with a Meshive API Key. Issue one in the console under a workspace’s Settings → API keys. Keys look like meshive_ followed by a 64-character token and come in two permission levels:

PermissionWhat it allowsExpiry
Read onlyEverything that lists or shows resourcesRequired: 365 days by default and at most
Read & writeThe above, plus creating and renaming workspaces, deleting empty ones, and creating, changing and deleting pods, storage, servings and tasks — including anything that spends creditRequired: 30 days by default, 90 at most

Every key expires. A write key that leaks can create pods on your account and delete pods, storage volumes and servings one at a time; it can’t delete a workspace that still holds assets, finished tasks, saved credentials or the other things listed under Deleting a workspace. A read key can fetch pod and task logs, which routinely contain tokens your container printed. Keys issued before this rule was introduced keep working until you revoke them. Revoke any key at any time from the same console page; the SDK reports a revoked or expired key as AuthenticationError, and a read-only key used for a write command as PermissionDeniedError.

When a key stops or deletes a pod, or deletes a storage volume, a serving or a workspace, the key’s owner gets an email naming the key and where the request came from (SDK & CLI, or the MCP client). If you didn’t expect it, revoke the key.

The recommended flow is meshive login, which verifies the key against the API and stores it locally so later commands need no flags:

  1. Log in

    Section titled “Log in”
    Terminal window
    meshive login          # prompts for the key (hidden input)

    The key is verified before it is saved. On success it’s written to ~/.meshive/credentials.json with file mode 0600 (owner read/write only).

  2. Use any command

    Section titled “Use any command”
    Terminal window
    meshive me             # works with no --api-key

  3. Log out when done

    Section titled “Log out when done”
    Terminal window
    meshive logout         # removes the saved credentials

Providing the key without logging in

Section titled “Providing the key without logging in”

meshive login is optional. You can also pass the key per-command or via the environment. The resolution order is --api-key flag › MESHIVE_API_KEY env › meshive login file:

Terminal window
export MESHIVE_API_KEY=meshive_xxxxxxxx
meshive me

Relocating the config directory

Section titled “Relocating the config directory”

By default credentials live in ~/.meshive/ (directory mode 0700). Set MESHIVE_CONFIG_DIR to relocate it — useful for test isolation or juggling multiple accounts:

Terminal window
export MESHIVE_CONFIG_DIR=/path/to/alt-config

Next

Section titled “Next”
  • CLI Reference — every command, flag, and filter
  • Python SDK — sync and async clients, models, and error handling
  • AI agents (MCP) — use Meshive from Claude Code, Codex, Cursor and other agents in natural language