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
  • 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 (what you can rent right now, with prices) and templates / template
  • Serverless — servings / serving and tasks / task
  • Host — machines / machine, machine-metrics, and earnings for the machines you contribute as a host

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

  • Pods — pod-create (shows the hourly estimate first), pod-stop, pod-start, pod-restart, pod-delete
  • Storage — storage-create, 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.

Terminal window
pip install "meshive==0.1.1"

Verify the install:

Terminal window
meshive --version

These references target 0.1.1 and the matching Meshive API. Older installs can lack write recovery, separate migration loss consent, serving cost confirmations and task log cursors. Package publication, server deployment and documentation publication are separate; a successful install alone does not verify the server version.

Authentication

Section titled “Authentication”

The SDK and CLI authenticate with a Meshive API Key. Issue one in the console under a workspace’s Settings → Secret. 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, changing and deleting pods, storage, servings and tasks — 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; 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.

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