CLI Reference

The meshive command groups operations into subcommands. Run meshive with no arguments (or meshive --help) to print usage. Read commands work with any key; the write commands at the end of this page need a Read & write key (see Authentication).

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 files
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)

# write commands (Read & write key) — they show an estimate and ask for confirmation
meshive pod-create <workspace> <name> --template <id> [--gpu <model>]
meshive pod-stop|pod-start|pod-restart|pod-delete <workspace> <pod>
meshive storage-create <workspace> <name> --size <GB>
meshive storage-delete <workspace> <storage>
meshive serving-deploy <workspace> <model-id> --price-cap <USD>
meshive serving-scale|serving-pause|serving-resume|serving-delete <id>
meshive task-submit <workspace> <name> --script <file> --image <image> (--gpu <model> | --cpu-preset <preset>)
meshive task-stop <id>
meshive logs <workspace> <pod>           # last lines of a pod's logs
meshive task-logs <id>                   # last lines of a task's logs

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:    [email protected]
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 (a compatibility count — 1 while the asset is ready and not deleted, 0 otherwise; assets no longer have real version history), SIZE and FILES (the asset’s current file set), 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, its current size and file count, who created it, whether it is in use and by what. A failed import shows its reason.

meshive asset <id>

This SDK release still prints a versions table for compatibility. Since assets no longer have real version history, it shows at most one entry — the asset’s own current state (status, size, ingest source, storage) — and none at all once the asset is deleted or not yet ready. The file list itself 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.

Write commands

Everything below needs a key issued with the Read & write permission. Two rules apply to all of them:

• Confirmation. Commands that spend credit (pod-create, pod-start, storage-create, serving-deploy, serving-resume, task-submit), can raise a running cost (serving-scale when it widens the replica range, turns autoscale on or raises the price cap) or delete something (pod-delete, storage-delete, serving-delete) first print what will happen — for creations, the hourly estimate — and then ask [y/N]. Pass --yes (-y) to skip the question in scripts; without it, a non-interactive run exits with code 2 and changes nothing.
• Asynchronous. A successful write returns immediately with a transaction id (accepted: yes). The resource changes state in the background; use meshive pod <workspace> <pod> --wait running, or pod-create --wait running, to block until it is there. If the pod has not appeared by --wait-timeout, pod-create exits with code 1 (the transaction id is still printed — the create was accepted, check meshive pods).

--estimate on pod-create, storage-create and task-submit prints the price and stops without creating anything — no confirmation, no credit spent.

Amounts are printed exactly as the web console shows them: an hourly rate to three decimals ($0.068/hr), every other amount — balances, daily and monthly totals, cost so far — to two ($2.10). A rate below a tenth of a cent therefore reads $0.000/hr rather than being rounded away. Use -o json when you need the unrounded number.

Price cap

For pods/tasks, --max-price <USD> caps the final compute hourly rate, including CPU/RAM. Attached or automatically created storage and Asset Hub retention are separate. The cap is checked at preflight and again before placement: a pod may be accepted and then fail asynchronously if its final rate exceeds the cap. Read back the status and billed rate with meshive pod. CPU capped requests are refused when a rate cannot be quoted. For storage-create, the cap applies to the volume’s final initial hourly rate.

Retrying a write

The SDK inside the CLI reuses a key during automatic request retries. Starting the CLI command again generates a new key. Version 0.1.1 has no --idempotency-key option or operation lookup command. After a timeout or --wait failure, inspect the resource list and accepted transaction first; do not blindly rerun a creation. Successful -o json write results include idempotencyKey, operationMethod and operationPath. For recovery across process restarts, use the SDK’s explicit keys and operation lookup. CLI terminal errors do not currently print those recovery fields.

meshive pod-create

meshive pod-create <workspace> <name> --template <id> [options]

Creates a pod from a template. Omit --gpu for a CPU pod.

Option	Meaning
--template <id>	Template ID from meshive templates (required).
--gpu <model>	GPU model exactly as meshive gpus prints it, e.g. "RTX 3060".
--gpu-count <n>	GPUs per pod (default 1, max 8).
--vram <GB>	VRAM tier when a model comes in several sizes.
--spot	Spot (preemptible) rental instead of on-demand.
--vcpu <n>, --ram <GB>	Override the recommended vCPU and RAM. Only vCPU/RAM above the amount included with the GPU cost extra. The system disk is sized by the server (the estimate shows it as disk) and cannot be changed — attach a storage volume for data.
--volume <storage>:/mount	Attach an existing storage volume (repeatable). Create volumes with storage-create.
--env KEY=VALUE, --secret KEY	Environment variables; --secret marks one as secret.
--port <port>[:<name>[:internal]]	Expose a port (repeatable).
--command <cmd>	Override the template’s command.
--region <code>	Target location, e.g. KR.
--internet-premium, --uptime-premium, --cpu-premium	Premium options; each narrows the eligible machines.
--max-price <USD>	Cap the final compute hourly rate, excluding storage and Asset Hub charges.
--estimate	Print the estimate and exit without creating.
--wait <status>, --wait-timeout <s>	After creating, wait until the pod reaches the status (e.g. running). Exit code 1 if it does not appear in time.
-y, --yes	Skip the confirmation.

meshive pod-create my-ws train-box --template 457 --gpu "RTX 3060" --estimate
meshive pod-create my-ws train-box --template 457 --gpu "RTX 3060" --max-price 0.10 --yes --wait running

-o name prints the pod ID once it is known (with --wait), otherwise the transaction id.

meshive pod-stop, pod-start, pod-restart, pod-delete

meshive pod-stop <workspace> <pod>
meshive pod-start <workspace> <pod> [--any-node] [--allow-data-loss] [-y]
meshive pod-restart <workspace> <pod>
meshive pod-delete <workspace> <pod> [--delete-local-storage <storage> ...] [-y]

• stop scales the pod to zero. Pod billing stops; attached storage keeps being billed.
• start resumes a stopped pod on its original machine, or with --any-node on an available machine. Moving can permanently delete unpreserved workspace files; local hostPath volumes stay behind. Billing confirmation is separate from data loss consent. When loss is possible or unknown, interactive use asks a second question; unattended use requires both --yes and --allow-data-loss, otherwise it exits 2 without starting the pod.
• delete removes the pod. Network storage survives; local (hostPath) volumes are deleted only when named with --delete-local-storage.

meshive storage-create, storage-delete

meshive storage-create <workspace> <name> --size <GB> [--type nfs|hostPath] [--disk NVMe|SSD|HDD] [--encrypted] [--region <code>] [--max-price <USD>] [--estimate] [-y]
meshive storage-delete <workspace> <storage> [-y]

Storage is billed hourly by capacity for as long as it exists, mounted or not. nfs (default) can be attached to any pod and supports --encrypted (at-rest encryption); hostPath is local to one machine and faster, but cannot be encrypted. Deleting a volume still linked to a pod fails with Storage In Use; remove its pod attachment or delete the pod first. Stopping a pod alone does not necessarily remove the attachment. Find the volume ID with meshive storages.

meshive serving-deploy, serving-scale, serving-pause, serving-resume, serving-delete

meshive serving-deploy <workspace> <model-id> --price-cap <USD> [--min-replicas 1] [--max-replicas 3] [--no-autoscale] [--max-context <tokens>] [--share-idle] [-y]
meshive serving-scale <id> [--min-replicas n] [--max-replicas n] [--autoscale|--no-autoscale] [--price-cap <USD>] [-y]
meshive serving-pause <id>
meshive serving-resume <id> [-y]
meshive serving-delete <id> [-y]

serving-deploy deploys a model you have already registered in the console (the registration ID is shown there). --price-cap is the hourly cap per replica, so the worst case is price-cap × max-replicas per hour. Paused servings stop billing and stop answering requests; serving-resume asks for confirmation because billing resumes. serving-scale asks when the change can raise the hourly cost (a larger replica range, --autoscale on a serving that had it off, a higher --price-cap); shrinking the range, --no-autoscale or a lower cap applies immediately.

meshive task-submit, task-stop

meshive task-submit <workspace> <name> (--script <file> | --script-text <code>) (--image <image> | --template <id>) (--gpu <model> | --cpu-preset <preset>) [options]
meshive task-stop <id>

Runs a Python script to completion on a GPU or CPU and stops billing when it ends.

Option	Meaning
--script <file> / --script-text <code>	The script (max 256 KB). Use print(..., flush=True) so output reaches the logs.
--image <image> / --template <id>	Container image, or a template to take it from.
--gpu <model>, --gpu-count <n>, --vram <GB>	GPU task.
--cpu-preset <preset>	CPU task, e.g. micro-2c8g, small-4c16g, standard-8c32g.
--requirements <file>	A requirements.txt installed before the script runs.
--env KEY=VALUE, --secret KEY, --arg <value>	Environment and script arguments (repeatable). Use --arg=--flag for values that start with a dash.
--max-duration <s>	Hard stop, 3600–86400 seconds (default 3600).
--input-asset <id>[:<version>]	Attach an asset under /inputs (repeatable). The optional :<version> is still accepted for compatibility and silently ignored — assets no longer have versions; the files fetched are whatever the asset holds at that time.
--webhook <url>, --max-price <USD>, --estimate, -y	As above.

The estimate quotes compute per hour when available, not a total-cost ceiling. max_duration bounds script runtime; input fetching can add compute charges, and volume/Asset Hub retention is separate. max_cost is therefore unknown even for GPU tasks. CPU presets have an unknown hourly estimate when their machine rate cannot be quoted.

meshive logs, task-logs

meshive logs <workspace> <pod> [--tail 200] [--container <name>] [--wait <s>]
meshive task-logs <id> [--tail 200] [--wait <s>] [--cursor <n>]

Prints the last --tail lines (up to 1000) of a pod’s or a task’s logs — a snapshot, not a stream. If nothing is buffered yet, or nobody has been watching the pod, the server starts a log watcher and waits up to --wait seconds (default 8) before answering; with --wait 0 it answers from the buffer and notes when those lines may be behind. Output is capped at 64 KB; a truncated note on stderr says when older lines were dropped. -o json returns the lines with timestamps. For tasks running on an external provider, task-logs prints the last lines by default and --cursor <n> (the next_cursor of a previous -o json result) prints only the lines after it.

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), or a write command that needed confirmation and got none (no TTY and no --yes, or you answered no).