CLI Reference

The meshive command groups read operations into a handful of subcommands. Run meshive with no arguments (or meshive --help) to print usage.

meshive --version
meshive me                     # current API key's owner
meshive api-keys               # your API keys (prefixes only)
meshive credit                 # credit balance
meshive credit-history         # top-ups and refunds

meshive workspaces             # list workspaces
meshive workspace <workspace>  # cost & resource summary of one workspace
meshive members <workspace>    # members and roles

meshive pods <workspace>       # list pods in a workspace
meshive pods --all             # list pods across every workspace
meshive pod <workspace> <pod>  # show a single pod
meshive pod-metrics <workspace> <pod>    # live resource usage of a pod

meshive storages <workspace>   # storages (volumes) in a workspace
meshive storage <workspace> <storage>    # show a single storage

meshive assets <workspace>     # assets (datasets, models, outputs, ...)
meshive asset <id>             # show an asset with its versions
meshive asset-storage <workspace>        # managed asset storage, cost, credit status

meshive gpus                   # GPUs available to rent right now, with prices
meshive templates              # templates (official, plus a workspace's custom ones)
meshive template <id>          # show a single template

meshive servings <workspace>   # serverless serving deployments
meshive serving <id>           # show a serving deployment
meshive tasks <workspace>      # serverless tasks
meshive task <id>              # show a task

meshive machines               # list your machines (as a host)
meshive machine <id>           # show a single machine
meshive machine-metrics <id>   # live metrics of a machine
meshive earnings               # your earnings (as a host)

Global options

Every subcommand (except --version) accepts these:

Option	Description
--api-key <key>	Meshive API key. Overrides MESHIVE_API_KEY and the saved login.
--base-url <url>	API base URL. Overrides MESHIVE_BASE_URL and the saved login.
-o, --output <format>	table (default), json (raw payload), or name (IDs only, one per line).
--json	Shorthand for -o json.
--timeout <seconds>	HTTP timeout (default 30).

Scripting with -o json / -o name

-o json prints the full, unmodified server payload — including nested fields the table omits (a pod’s machine/template, a machine’s full specs and state, a task’s script). Pipe it to jq for scripting. -o name prints one ID per line, ready for xargs; single-value commands (credit, earnings) print just their headline number. Color and the human-readable table are automatically suppressed when output isn’t a terminal, when JSON is requested, or when NO_COLOR / MESHIVE_NO_COLOR is set.

Units

RAM, storage and VRAM are shown in GB using the same conversion as the console; usage rates in percent, with n/a when a measurement is unavailable; network throughput in Mbps.

Authentication commands

meshive login

Prompts for your API key (hidden input), verifies it against the API, and saves it to ~/.meshive/credentials.json. Accepts --api-key to skip the prompt.

meshive login

meshive logout

Removes the saved credentials file.

meshive logout

See Authentication for key resolution.

meshive me

Shows the owner of the current API key — email, username, and role. Alias: whoami.

meshive me

email:    you@example.com
username: you
role:     user

meshive api-keys

Lists your active API keys. Alias: keys. Only the display prefix (meshive_a1b2c3d4) is ever shown — the secret is returned once at creation and is not stored, so there is no way to reveal it later. Issue and revoke keys in the console.

meshive api-keys

Columns: NAME, ID, PREFIX, SCOPES, STATUS, CREATED, LAST USED, EXPIRES.

meshive credit

Shows your credit balance: total, paid (usable for GPU pods and workspaces), bonus (usable for serverless inference only), the auto-recharge setting, and whether a default payment method is on file. -o name prints just the total balance.

meshive credit

meshive credit-history

Lists credit top-ups and refunds (refunds are negative). Defaults to the last 90 days.

meshive credit-history
meshive credit-history --since 2026-07-01 --until 2026-07-31

Columns: DATE, AMOUNT, METHOD, PAID, ID. Stripe receipt and invoice links are not included — open them in the console.

meshive workspaces

Lists the workspaces you can access. Alias: ws.

meshive workspaces

Columns: NAME (display label), ID (namespace name — the value you pass to pods/pod), STATUS, PODS (pod count), PRICE/HR.

meshive workspace

Shows one workspace: the current hourly price, the average daily cost over the last 7 days, the GPUs / vCPUs / RAM / storage it holds, a per-resource table (pods, storages, serverless deployments — active / paused / disabled), and the last 7 days of daily cost broken down by pod, storage, serverless, task, and asset.

meshive workspace <workspace>

Maintenance schedules and messages from hosts are in the JSON payload (-o json).

meshive members

Lists a workspace’s members with their role (admin, billing, viewer) and join date.

meshive members <workspace>

meshive pods

Lists pods in a workspace, or across all workspaces with --all.

meshive pods <workspace>       # one workspace (by ID)
meshive pods --all             # every workspace (adds a WORKSPACE column)

Note

Pass either a workspace ID or --all, not both and not neither. With --all, a workspace that fails to list is skipped with a warning rather than aborting the whole command.

Columns: NAME, ID, (WORKSPACE with --all), STATUS, RENTAL, PRICE/HR, CREATED. Price is shown only for running pods (stopped/waiting pods aren’t billed).

Filters

Filtering is client-side — the API returns the full list and the CLI narrows it.

Flag	Description
--status	Filter by status. Repeatable or comma-separated, e.g. --status running,error.
--rental	spot or demand.
--name	Substring match on the display name (alias).

meshive pods <workspace> --status running
meshive pods <workspace> --status running,error    # comma-separated…
meshive pods <workspace> --status running --status error   # …or repeated
meshive pods <workspace> --rental spot
meshive pods <workspace> --name llama

Valid pod statuses (an unknown value is rejected with the list, rather than silently returning nothing):

pending  creating  running  waiting  stopping
stopped  error  unreachable  terminating  terminated

meshive pod

Shows a single pod in detail.

meshive pod <workspace> <pod>

Both arguments are IDs — the workspace’s namespace name and the pod’s name (the ID column from meshive pods), not the display aliases. Output includes name, id, workspace, status, rental, price/hr, created time, and a maintenance notice when the pod is under maintenance.

meshive pod-metrics

Shows a pod’s live resource usage: CPU cores and usage, RAM size and usage, each GPU’s core and VRAM usage and temperature, and ephemeral disk usage.

meshive pod-metrics <workspace> <pod>

A usage shows as n/a when the measurement is not available (for example right after start). A pod that has not been placed on a machine yet has no metrics and the command fails with an explanation.

meshive storages

Lists the storages (volumes) in a workspace.

meshive storages <workspace>

Columns: NAME (display label), ID (volume name — the value you pass to storage), TYPE, STATUS, SIZE, USED, PRICE/HR, PODS (linked pods), CREATED.

Filters

Filtering is client-side.

Flag	Description
--type	nfs, hostPath, ephemeral, or emptyDir (case-insensitive).
--status	Filter by status (repeatable or comma-separated). Same values as pod statuses.
--name	Substring match on the display name.

meshive storage

Shows a single storage: size, usage, free space, price, the pods it is mounted in, whether it is encrypted, and a maintenance notice when its host machine is under maintenance.

meshive storage <workspace> <storage>

meshive assets

Lists the assets in a workspace — datasets, models, adapters, checkpoints, outputs, configs and plain files — one page at a time.

meshive assets <workspace>
meshive assets <workspace> --type dataset          # dataset, model, adapter, checkpoint, output, config, file
meshive assets <workspace> --status frozen         # active, source_missing, frozen, deleted, purged, merged
meshive assets <workspace> --page 2 --page-size 50 # 1-100 per page (default 20)
meshive assets <workspace> --name imagenet         # substring match within the page (client-side)

By default deleted, purged and merged assets are hidden; pass --status to see one of those states. --type, --status and paging are applied by the API. When there are more pages, a hint line shows the page count.

Columns: NAME, ID (asset_… — the value you pass to asset), TYPE, STATUS, VERSIONS (ready versions), SIZE and FILES (latest ready version), STORAGE (managed, s3 for your own bucket, or external for a linked Hugging Face / CivitAI source), UPDATED.

meshive asset

Shows a single asset: type, status and reason, storage location, size and file count of the latest ready version, who created it, whether it is in use and by what, and a table of its versions (newest first) with their status, size, ingest source and storage. A failed import shows its reason.

meshive asset <id>

The file list of each version is in the JSON payload (-o json). No download links are included — download from the console.

meshive asset-storage

Shows how much managed asset storage a workspace uses, the price per GB-month, the estimated monthly cost, and the asset credit status: normal, grace (with the time until uploads are blocked), or blocked (with the deadline after which managed assets are deleted unless credit is added). Also shows whether paid credit is available to start pods and tasks. Assets in your own S3 bucket are not billed and are not counted.

meshive asset-storage <workspace>

-o name prints just the estimated monthly cost.

meshive gpus

Lists the GPU tiers you can rent right now — one row per (model, VRAM) pair — with the per-GPU hourly price, how many GPUs are available in total, the most you can put in one pod, and how many machines offer that tier.

meshive gpus
meshive gpus --rental spot            # price for spot instead of on-demand
meshive gpus --vram 40                # only tiers with at least 40 GB VRAM
meshive gpus --model h100             # substring match on the model (client-side)

--rental and --vram are applied by the API; --model narrows the result locally. Availability is a live snapshot and changes as pods start and stop.

meshive templates

Lists official templates. Add --workspace to include that workspace’s custom templates as well.

meshive templates
meshive templates --workspace <workspace>
meshive templates --type ide          # ide, framework, db, mlops, llmops, inference, generative, science, os, custom
meshive templates --name jupyter      # substring match (client-side)

Columns: NAME, ID, TYPE, SOURCE (official / custom), HARDWARE, IMAGE.

meshive template

Shows a single template. A custom template can only be read together with the workspace that owns it.

meshive template <id>
meshive template <id> --workspace <workspace>     # custom template

Environment variables, endpoints, volume mounts and semantic paths are in the JSON payload (-o json).

meshive servings

Lists the serverless serving deployments in a workspace.

meshive servings <workspace>
meshive servings <workspace> --status active      # provisioning, active, scaling, draining, error
meshive servings <workspace> --name llama         # substring match on the model name

Columns: NAME (model), ID, STATUS (with a (paused) marker), REPLICAS (current, and the configured min-max), HEALTHY, PRICE/HR (shown while the deployment is billing).

meshive serving

Shows a single serving deployment, including its endpoint URL. Replica details and live metrics are in the JSON payload.

meshive serving <id>

meshive tasks

Lists the serverless tasks in a workspace, newest first.

meshive tasks <workspace>
meshive tasks <workspace> --status running,failed     # applied by the API
meshive tasks <workspace> --limit 20 --offset 20      # paging (limit 1-200, default 50)
meshive tasks <workspace> --name train                # substring match (client-side)

Valid task statuses:

queued  scheduling  pulling  fetching  running
succeeded  failed  timed_out  stopped

Columns: NAME, ID, STATUS, GPU, COST (so far), CREATED.

meshive task

Shows a single task: image, GPU/CPU/RAM, price and cost, timestamps, exit code, and the failure reason if it failed. The script, requirements, environment (secret values are masked) and the compute/disk cost breakdown are in the JSON payload (-o json).

meshive task <id>

meshive machines

Lists the machines you contribute to the network as a host. No workspace is needed — a host owns its machines directly. Alias: m.

meshive machines

Columns: NAME, ID, TYPE, STATUS, GPU (e.g. 8x NVIDIA H100), EARN/HR, UPTIME.

Filters

Flag	Description
--type	gpu, cpu, or storage.
--status	Filter by status (repeatable or comma-separated), e.g. online,offline.
--name	Substring match on the display name.

meshive machines --status online
meshive machines --type gpu
meshive machines --name node-a

Note

Unlike pod statuses, machine statuses aren’t validated against a fixed list — the filter does a case-insensitive match against whatever state the server reports.

meshive machine

Shows a single machine in detail.

meshive machine <id>

The argument is the machine ID (the ID column from meshive machines). Output includes name, id, type, status, gpu, earn/hr, uptime, and host tier.

meshive machine-metrics

Shows a machine’s live metrics: CPU cores, usage and the cores allocated to pods; RAM likewise; each GPU’s core and VRAM usage and temperature; root and PV disk usage; and network throughput.

meshive machine-metrics <id>

A machine that is not part of a cluster yet has no metrics and the command fails with an explanation.

meshive earnings

Shows your host earnings: the current hourly rate, today’s total, the amount accumulated until the next payout, and a daily table (CPU / GPU / storage / total).

meshive earnings
meshive earnings --days 30                          # more of the daily table (default 7; 0 = all)
meshive earnings --since 2026-08-01 --until 2026-08-31

-o name prints just the amount accumulated until payout.

IDs vs names

List output shows two columns, and the distinction matters:

• ID — the canonical identifier (namespace_name for workspaces, pod_name for pods, the volume name for storages, asset_… for assets, numeric IDs for templates and servings, task_… for tasks, the machine id for machines). This is what you pass to the singular commands. It is unique and stable.
• NAME — the display alias you set. It is a label, not a key: it is not guaranteed unique and can change. Use --name to filter by it, but always address resources by their ID.

Exit codes

Code	Meaning
0	Success.
1	An API/auth error, or a missing/invalid API key.
2	Bad arguments (e.g. an unknown --status, a malformed --since date, --limit out of range, or both a workspace and --all).