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). The cpus, transaction, pod-update, storage-update, storage-connect and model-sets commands, pod-create --cpu-line, --local-volume, --template-port and --model-set, pod-start --placement and storage-create --usage-warning need meshive 1.2 or later (1.1 was not released on its own). From 1.2, pod-start without --placement starts the pod the way the console would; 1.0 always used same_node.

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 transactions <workspace>         # pod operations in flight (why a pod is still creating)
meshive transaction <workspace> <id>     # one pod operation by ID, even after it finished or failed

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 cpus                   # CPU lines for CPU pods, with prices
meshive templates              # templates (official, plus a workspace's custom ones)
meshive template <id>          # show a single template
meshive model-sets <workspace> --template <id>   # model sets a template can start with

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 workspace-create [<name>] [--wait]                # free, no confirmation; prints the workspace ID
meshive workspace-update <workspace> --name <name> [--estimate]   # rename; the ID stays the same
meshive workspace-delete <workspace> [--check]            # only an empty workspace; can't be undone
meshive pod-create <workspace> <name> --template <id> [--gpu <model>] [--model-set <slug>] [--hf-token <id>]
meshive pod-update <workspace> <pod> [--gpu <model>] [--env KEY=VALUE] ...   # change only what you pass
meshive pod-stop|pod-start|pod-restart|pod-delete <workspace> <pod>
meshive storage-create <workspace> <name> --size <GiB>   # network storage, at least 10 GiB
meshive storage-update <workspace> <storage> [--name <label>] [--size <GiB>]
meshive storage-connect <workspace> <storage>            # one-time SSH/SFTP login to a volume
meshive storage-delete <workspace> <storage>
meshive model-register <workspace> <hf-repo>              # free; prints the model ID
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 and storage are shown in GiB (MiB below 1 GiB) and file sizes in KiB, MiB, GiB or TiB — the same 1024-based units as the console. GPU VRAM keeps the usual GB label (24 GB vram). Usage rates are in percent, with n/a when a measurement is unavailable; network throughput is in Mbps (bits per second ÷ 1,000,000).

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 (GPU pods, tasks and serverless inference all draw from it), the auto-recharge setting, and whether a default payment method is on file. -o name prints just the 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), ROLE (admin, billing or viewer — a viewer can’t make changes), STATUS, PODS (pod count), PRICE/HR.

A workspace is ready for pods and tasks when its STATUS is running. One you just created with workspace-create isn’t yet, and can be missing from this list for a moment.

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). Resources on a machine under maintenance aren’t billed while its window is open.

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. Resources on a machine with an open maintenance window aren’t billed.

It also lists the pod’s URLs (ENDPOINT, PORT, URL, STATE) and the logins the console shows on Connect (CREDENTIAL, VALUE), such as the ACCESS_PASSWORD a ComfyUI pod generates. Secret values are hidden unless you add --show-secrets:

meshive pod <workspace> <pod> --show-secrets

Secret values come back only to an API key with write scope; a read-only key gets ***, and the CLI says so.

When they apply, it also says that the system stopped the pod and why, why the pod can’t start on its original machine now, and what a waiting pod is waiting for. -o json prints the API payload as your key receives it: secret variables are ***, except the Connect logins a key with write scope gets.

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 transactions

Shows the pod operations still in flight in a workspace — the way to see why a pod is still creating. Alias txn.

meshive transactions <workspace>

Columns: POD, TXN (the transaction ID a write command printed), ACTION (create, start, stop, restart, …), STATUS, STEP (the current stage), PROGRESS, DETAIL (the failure reason when one is known) and UPDATED. A pod that stays creating is usually pulling its image, not stuck. PROGRESS is shown for stages that report it — image pull, asset fetch and storage preparation — and is - when the stage reports none, which does not mean 0%. Finished operations drop off the list, and a failed one stays for only a few minutes, so an empty result means nothing is in flight, not that nothing failed; check the pod’s own status, or look the operation up with meshive transaction. -o json returns every step with its diagnostics.

PROGRESS names the pause when downloaded bytes stop moving (verifying, waiting for storage), and when an input asset download fails the command prints the last 10 lines of that download container’s log under the table.

meshive transaction

Shows one pod operation by its transaction ID — the one pod-create or another pod write command printed, or the TXN column of meshive transactions. There is no time limit, so it also shows operations that finished or failed long ago.

meshive transaction <workspace> <id>

The output gives the pod, the action, the status, the current step with its progress and, for a failed operation, the reason — the step it failed at and why, such as an image that can’t be pulled. A table of every step (STEP, STATUS, DETAIL, UPDATED) follows, and when an input asset download failed, the end of that download container’s log. -o json returns the full operation.

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. Storage on a machine with an open maintenance window isn’t billed.

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, SIZE and FILES (- for a linked source that was never measured), 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>

It lists the asset’s files (FILE, SIZE, STATUS — the first 50; -o json has them all), its upload state while it isn’t ready, and where it came from.

meshive asset-import

Links a Hugging Face repo, a CivitAI model or a direct file URL as an asset, so tasks and pods can use it with --input-asset. It needs a read & write key.

meshive asset-import <workspace> Qwen/Qwen3-0.6B
meshive asset-import <workspace> https://civitai.com/models/4384 --type checkpoint
meshive asset-import <workspace> meta-llama/Llama-3.1-8B --hf-token <id> --path '*.safetensors' --path '*.json'
meshive civitai-keys <workspace>          # key IDs for --civitai-key; hf-tokens lists Hugging Face token IDs

Nothing is copied: the asset is ready at once and has no storage charge, and pods and tasks download it from the source when they start — so the command doesn’t ask for confirmation. --revision pins a Hugging Face branch, tag or commit; --path links only matching files. A private or gated source needs a token or key saved in the console; when one is missing, the error says what to do.

meshive asset-download

Saves an asset’s files, keeping their paths inside the asset. A read key is enough.

meshive asset-download <id>                       # into ./<id>
meshive asset-download <id> -d models/sdxl        # into a directory of your choice
meshive asset-download <id> --path 'config/*'     # only matching files (fnmatch, repeatable)

Existing files are overwritten. One request covers at most 500 files, so split a larger asset with --path. Linked assets (fetched from Hugging Face or CivitAI when a pod starts) can’t be downloaded. Accounts that have never paid have a daily download limit.

meshive asset-storage

Shows how much managed asset storage a workspace uses, the price per GiB-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 the workspace’s billing account has credit 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 cpus

Lists the CPU lines you can rent for CPU pods right now — each a CPU vendor, product line and generation with a fixed RAM type — with the hourly price per vCPU and per GiB of RAM.

meshive cpus
meshive cpus --rental spot            # price for spot instead of on-demand

Columns: LINE (the value for pod-create --cpu-line), CPU, RAM (DDR generation), RENTAL, PER vCPU/HR, PER GiB/HR, MAX vCPU and MAX RAM (the most one pod can get on a single machine), MACHINES. Like gpus, it is a live snapshot.

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 model-sets

Lists the model sets a template can start with — ready-made bundles of model files, like the console’s model set tiles (see Bundled ComfyUI workflows).

meshive model-sets <workspace> --template <id>

Columns: SLUG (the value for pod-create --model-set), NAME, TASK, FILES, SIZE, MIN VRAM (~ marks an estimate) and LICENSE (with a count of files whose license isn’t known). A template that adds its own set automatically, or has no model folders, takes no model set; the command says so and why. -o json lists each set’s files and workflows, and -o name prints the slugs. From 1.3, a set gated on Hugging Face gets a line saying where to accept its license and to create the pod from its Quick Deploy template with pod-create --hf-token.

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. It also shows its input assets, the asset a failed download stopped on, how far the output upload has got and its last error, and when the outputs were deleted. 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 task-outputs

Lists a task’s output files, or saves them with --download.

meshive task-outputs <task_id>
meshive task-outputs <task_id> --download ./results

-o json includes each file’s temporary download link.

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), change a resource (workspace-update, pod-update, storage-update), can raise a running cost (serving-scale when it widens the replica range, turns autoscale on or raises the price cap) or delete something (workspace-delete, pod-delete, storage-delete, serving-delete, model-delete) first print what will happen — for creations and edits, 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). workspace-update doesn’t use a transaction: it applies the rename before it returns. 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, or not reached that status, by --wait-timeout, pod-create exits with code 1 (the transaction id is still printed — the create was accepted, check meshive pods). A creation that fails — for example because the image can’t be pulled — ends the wait at once: pod-create prints the reason, points to meshive transaction for the details, and exits with code 1.

--estimate on pod-create, pod-update, storage-create, storage-update, task-submit, workspace-create and workspace-update prints the price (for workspace-update, the current and new name) and stops without creating or changing anything — no confirmation, no credit spent. workspace-delete --check does the same for a deletion. workspace-update --estimate and workspace-delete --check also work with a Read only key, with the same role requirement.

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. Existing storage you attach, automatically created storage and Asset Hub retention are separate. The cap is checked at preflight — for pod-create against the estimate, which includes any new --local-volume — 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. The CLI 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 workspace-create

meshive workspace-create [<name>] [--estimate] [--wait] [--wait-timeout <s>]

Creates a workspace, as you would in the console. An empty workspace costs nothing — pods, storage and tasks in it are billed as usual — so the command doesn’t ask for confirmation. Needs meshive 1.6 or later.

Option	Meaning
<name>	The workspace’s display name: at most 63 characters, without control characters, and different from every workspace name you already use (an exact match, so Research and research are different names). Leading and trailing spaces are removed. Leave it out and a name starting with my-workspace- is generated.
--estimate	Print the name the workspace would get and what it costs, and stop; nothing is created. A name you already use is refused here too.
--wait	After the request is accepted, wait until the workspace is running, then print it.
--wait-timeout <s>	How long --wait waits, in seconds.

meshive workspace-create research --estimate
meshive workspace-create research --wait
meshive workspace-create -o name          # a generated name; prints just the workspace ID

The output shows accepted, the name, the workspace ID (the ID column of meshive workspaces, which every other command takes), the transaction ID, and a reminder that the workspace must be running before you create anything in it. With --wait, it adds the status and says the workspace is running instead of the reminder. On success, -o name prints the workspace ID and -o json the raw response.

The request returns before the workspace is ready. A pod or task in a workspace that isn’t running is refused (Workspace not found or not ready, Workspace is not ready), and storage or a serving may be accepted and then fail later — so wait for running first, with --wait or by checking meshive workspaces. With --wait, the command polls every few seconds:

• A workspace that is missing from the list for a moment, or shows terminated for one poll, doesn’t stop the wait — both can happen right after creation.
• error ends the wait at once with exit code 1.
• If the workspace isn’t running by --wait-timeout, the command exits 1 and names the workspace and the last status it saw. terminated as the last status means setup failed.

A failed wait doesn’t undo the create. The workspace ID is printed on stderr before the wait starts (Workspace <id> accepted; waiting for it to be running.), and nothing goes to stdout after a failed wait, even with -o name or -o json. Check meshive workspaces before running the command again.

The request itself can be refused:

• Name Taken — one of your workspaces already has that name, whatever its status. Choose another name or leave it out.
• A name that is too long or has control characters is refused (HTTP 422) before anything is created.
• No Cluster Available (HTTP 503) — no cluster can take a new workspace right now. The command has already waited and retried, so wait at least 30 seconds before running it again.

Starting the command again generates a new idempotency key (see Retrying a write): after an interruption, check meshive workspaces first. If the first run did create the workspace, running again with the same name fails with Name Taken, and running again with no name creates a second workspace.

meshive workspace-update

meshive workspace-update <workspace> --name <name> [--estimate] [-y]

Renames a workspace. Needs meshive 1.6 or later and the admin or billing role in the workspace; a viewer is refused. Only the display name changes: the workspace ID stays the same, so every command and script that passes the ID keeps working, and every member sees the new name. Renaming costs nothing, but the command still prints the change and asks [y/N], because other people see it.

Option	Meaning
<workspace>	The workspace ID — the ID column of meshive workspaces, not its name.
--name <name>	The new name (required): at most 63 characters, without control characters, and different from the name of every other workspace you belong to (an exact match, so Research and research are different names). Leading and trailing spaces are removed. An empty name is refused (exit 2). A workspace you have deleted no longer counts. Using the workspace’s current name succeeds and changes nothing.
--estimate	Print the workspace ID, its current name and the new name, and stop; nothing is renamed and nothing is asked. A name you already use is refused here too.
-y, --yes	Skip the confirmation.

meshive workspace-update a1b2c3d4e5f60718 --name research-2 --estimate
meshive workspace-update a1b2c3d4e5f60718 --name research-2 --yes

workspace id: a1b2c3d4e5f60718
current name: research
new name:     research-2

After the rename the command prints the workspace ID and the confirmed name. -o name prints the workspace ID (with --estimate too), and -o json the raw response. The request can be refused:

• Name Taken — another of your workspaces already has that name. Choose another.
• A name that is too long or has control characters is refused (HTTP 422) before anything changes.
• Workspace Not Found — the workspace is already being deleted.
• You are not a member of workspace — a wrong workspace ID, or a workspace you don’t belong to.

The new name is applied at once, but meshive workspaces can take a moment to show it, so keep using the ID.

meshive workspace-delete

meshive workspace-delete <workspace> [--check] [-y]

Deletes a workspace that is empty, and only that. It can’t be undone. Needs meshive 1.6 or later and the admin or billing role in the workspace.

The command checks the workspace first, every time. If anything is still in it, the command prints what is left on stderr and exits 1 without asking — --yes doesn’t change that. Only an empty workspace gets the question Delete workspace '<name>' (<id>)? This can't be undone. [y/N].

Option	Meaning
<workspace>	The workspace ID — the ID column of meshive workspaces, not its name.
--check	Only run the check: print whether the workspace can be deleted and what is still in it, and stop. Nothing is deleted and nothing is asked. Exit 0 if it can be deleted, 1 if not.
-y, --yes	Skip the confirmation (not the check).

meshive workspace-delete a1b2c3d4e5f60718 --check
meshive workspace-delete a1b2c3d4e5f60718 --yes

workspace id: a1b2c3d4e5f60718
name:         research
can delete:   no
Still in it:
  pods: 2
  assets: 14
  members: 1

The list counts what is left, by kind. The names are the blockers of the SDK’s check_workspace_delete, with spaces for underscores. The SDK page says what each one means and how to clear it.

A workspace counts as empty when none of these is left:

• pods (stopped ones too), storage volumes and servings
• tasks — queued or running ones, finished ones that are still in the Tasks list, and tasks whose outputs are still being saved
• assets, custom templates and custom registered models
• saved credentials (Hugging Face tokens, CivitAI keys, object-storage credentials, registry logins), webhooks and active inference API keys
• other members, and invitations sent in the last day that haven’t been accepted
• earnings from shared serving capacity that haven’t been credited yet
• operations that are still running, including the workspace’s own setup

Your own meshive_… API keys, billing history, short-lived inference results, files in your own bucket, links added when you attach a model set and anything you have already deleted don’t count, except a removed task whose outputs are still being saved.

No API key can delete a workspace that still holds things. A person can still delete it in the console, which removes what’s in it for good; the SDK reference says how the console treats it. A write key can still delete pods, storage volumes and servings one at a time — see Authentication.

A deletion runs in the background. The workspace leaves meshive workspaces within a moment, and its name stays taken for a while — creating a workspace with it is refused with Name Taken until the deletion has finished. The key’s owner gets an email naming the key. -o name prints the workspace ID after a delete; with --check it prints the ID whatever the result, so rely on the exit code. -o json prints the raw response.

meshive pod-create

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

Creates a pod from a template. Omit --gpu for a CPU pod: it runs on the cheapest CPU line that fits unless you pick one with --cpu-line, and gets 8 vCPU and 32 GiB of RAM (or the nearest sizes the line offers) unless you set --vcpu / --ram.

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). meshive gpus shows the most one pod can get.
--vram <GB>	VRAM tier when a model comes in several sizes.
--spot	Spot (preemptible) rental instead of on-demand.
--vcpu <n>, --ram <GiB>	Override the default vCPU and RAM — the GPU’s recommended sizes, or 8 vCPU / 32 GiB for a CPU pod. Use sizes the console offers; any other size is refused with the allowed values. 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.
--cpu-line <line>	CPU pods only: the CPU line to run on, from the LINE column of meshive cpus (default: the cheapest line that fits).
--volume <storage>:/mount	Attach an existing network storage volume (repeatable). Create one with storage-create. Existing local storage can’t be attached to a new pod.
--local-volume <name>:/<path>:<GiB>[:encrypted]	Create local storage on the pod’s machine together with the pod (repeatable), e.g. scratch:/scratch:50. Add :encrypted for at-rest encryption. At least 10 GiB; not available with --spot. It is billed by size until you delete it — also while the pod is stopped — and the estimate includes it.
--env KEY=VALUE, --secret KEY	Environment variables; --secret marks one as secret. Variables the template requires need a value.
--port <port>[:<name>[:internal]]	Open a port the template doesn’t (repeatable). A port or port name the template already opens is refused, as is a port listed twice — to change one the template opens, use --template-port.
--template-port <port>[:<name>][:<new-port>][:internal|external]	Change a port the template opens (repeatable), as on the console’s deploy screen. <port> is its current number; the other fields are positional, and an empty one keeps the template’s value: 8080:ide renames it, 8080::8443 gives it the number 8443, 8080:::internal makes it internal only, 8080:ide:8443:external does all three. A name of only digits, or internal / external, is refused with the form to use instead. Template ports can’t be removed. A port the template doesn’t open is refused, as is a clash with another port or port name.
--command <cmd>	Override the template’s command (at most 4,096 characters).
--region <code>	Deprecated and ignored — pods are placed without a region. Still accepted with a warning; it will be removed in 2.0.
--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.
--input-asset <id>[=<dir>]	Place an asset in the pod (repeatable) — by default under /inputs/<name> or the template’s path for its type. It adds an input volume billed by size.
--watch <path>	Upload new files in this folder as assets (repeatable). The template’s output folders are watched already. Templates without an output folder take it too when the pod has storage for the folder.
--watch-off <path>	Turn off one of the template’s watched folders from the start (repeatable), as on the console’s create screen. meshive pod-watch --on turns it back on.
--watch-move <path>=<new path>	Move one of the template’s output folders to another path (repeatable); MESHIVE_SYS_OUTPUT_DIR and its storage follow. Needs meshive 1.4 or later.
--model-set <slug>	Start the pod with one of the template’s model sets, from the SLUG column of meshive model-sets. One set per pod; the estimate shows it.
--hf-token <id>	Quick Deploy templates whose model set is gated on Hugging Face: a token ID from meshive hf-tokens whose Hugging Face account accepted the model’s license. The files download with that token. Needs meshive 1.3 or later — see Gated model sets.
--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). A failed creation ends the wait at once with the reason. Exit code 1 if the creation fails or the pod isn’t there in time.
-y, --yes	Skip the confirmation.

These settings follow the same rules as the console; when one is refused, the error says what is allowed.

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" --local-volume scratch:/scratch:50 --estimate
meshive pod-create my-ws train-box --template 457 --gpu "RTX 3060" --max-price 0.10 --yes --wait running
meshive pod-create my-ws cpu-box --template <id> --cpu-line <line> --estimate     # a CPU pod
meshive pod-create my-ws ide-box --template <id> --gpu "RTX 3060" --template-port 8080:ide:8443 --estimate   # rename and renumber the template's port 8080

-o name prints the pod ID once it is known (with --wait), otherwise the transaction id. In the estimate, a new local volume shows as scratch (new local, 50 GiB)→/scratch.

With --model-set, the set’s files are added to the workspace before the pod is created, which can take several minutes. pod-create waits up to 15 minutes for that (or --timeout, if longer) and doesn’t resend the request after a timeout: the pod may still be created, so check meshive pods and meshive transactions before running it again. If any file can’t be added, no pod is created — the command lists the failed files and exits 1; files already added stay in the workspace and are reused next time. A slug the template doesn’t offer is refused with the sets it does.

meshive pod-update

meshive pod-update <workspace> <pod> [options]

Changes an existing pod the way the console’s edit screen does. Only what you pass changes; everything else stays as it is. The command first prints the estimate — the hourly price after the change (and now), whether the running pod restarts, and the list of changes — then asks for confirmation.

Option	Meaning
--name <label>	Rename the pod. A rename alone applies in place without a restart.
--template <id>	Move the pod to another template. Its variables, ports and command then start from the new template; the estimate lists what you added that doesn’t carry over.
--rental demand|spot	Change the rental type. Spot pods can’t have local storage; --detach it in the same command.
--gpu <model>, --gpu-count <n>, --vram <GB>	GPU pods: change the GPU. A new GPU resets vCPU and RAM per GPU to its recommended sizes; changing only the count keeps the per-GPU ratio.
--cpu-line <line>	CPU pods: change the CPU line. Cores and RAM reset to the console’s default.
--vcpu <n>, --ram <GiB>	Pod totals, in sizes the console offers.
--env KEY=VALUE, --secret KEY	Set or add environment variables.
--remove-env KEY	Remove a variable you added. The template’s variables can’t be removed.
--port <port>[:<name>[:internal]]	Open a new port.
--template-port <port>[:<name>][:<new-port>][:internal|external]	Rename, renumber, expose or hide a current port, as in pod-create.
--remove-port <port>	Close a port you opened. The template’s ports can’t be removed.
--command <cmd>	Replace the start command; --command "" goes back to the template’s.
--volume <storage>:/mount	Attach existing network storage, or local storage on the pod’s current machine.
--local-volume <name>:/<path>:<GiB>[:encrypted]	Create local storage on the pod’s machine and attach it, as in pod-create.
--detach <storage>	Detach a volume. The volume and its data stay.
--allow-node-migration	Let the pod move to another machine when its machine can’t fit the change.
--allow-data-loss	Separately consent to losing the pod’s unpreserved workspace files if it moves.
--drop-watched-folder <path>	Agree that the change removes this watched folder (repeatable).
--enable-folder-saving	Add the uploader to an older pod that has none, so its folders can be watched (needs storage on the pod; a running pod restarts once). meshive pod-watch --add on such a pod tells you to run this first. A pod that already has the uploader, or has no storage, is refused before anything restarts. Needs meshive 1.4 or later.
--max-price <USD>	Refuse the edit if the new compute hourly rate is above this.
--estimate	Print the changes and the new price, and exit without changing anything.
-y, --yes	Skip the confirmation.

All list options are repeatable. The pod type (GPU or CPU), premiums and image can’t change. A running pod restarts with the new settings; a stopped pod uses them at its next start. Input assets and watched folders are kept. The output prints the transaction to follow with meshive transaction.

meshive pod-update my-ws <pod> --gpu-count 2 --estimate
meshive pod-update my-ws <pod> --env HF_HOME=/data/hf --port 7860:gradio
meshive pod-update my-ws <pod> --name renamed-box --yes        # no restart

Some changes need consent first. Nothing changes; the command explains why, says what to run again with, and exits 2:

• The machine can’t fit the change. Run it again with --allow-node-migration to let the pod move. A move permanently deletes unpreserved workspace files, so when the pod has any, --allow-data-loss is needed as well.
• Watched folders would be removed because the storage they are on is detached. The command names the folders; run it again with --drop-watched-folder <path> for each.
• An older pod’s RAM can’t be read back exactly. Pass --ram (and --vcpu) with the change.

Local storage attached to a pod keeps it on its machine, so when that machine can’t fit the change, the edit is refused: detach the local storage with --detach, or keep the current resources. Other refusals — a template variable or port you tried to remove, a GPU change on a CPU pod — print the server’s reason.

meshive ssh

Prints a one-time SSH command and password for a pod — the same login as the console’s Connect tab. It doesn’t run ssh for you. It needs a read & write key.

meshive ssh <workspace> <pod>

The password expires after a few minutes, and each run issues a new one. The output also has a browser-terminal link with the password in it, so don’t paste it anywhere shared.

meshive pod-watch

Shows or changes a running pod’s watched folders — folders whose new files are uploaded as assets — without restarting it.

meshive pod-watch <workspace> <pod>                                   # list them
meshive pod-watch <workspace> <pod> --add /workspace/results --include '*.csv' [--existing] [-y]
meshive pod-watch <workspace> <pod> --off /workspace/outputs          # template folders can be turned off
meshive pod-watch <workspace> <pod> --remove /workspace/results

Adding or turning on a folder asks for confirmation because uploaded files are stored and billed; --existing also uploads the files already there. Removing or turning off applies at once. A folder on network storage can’t be watched, and a pod that is being created or changed can’t be edited until that finishes — the command prints the server’s reason.

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

meshive pod-stop <workspace> <pod>
meshive pod-start <workspace> <pod> [--placement <placement>] [--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 (except on a machine with an open maintenance window).

• start resumes a stopped pod. --placement chooses where:

  Placement	Starts the pod
  same_node	On its original machine.
  any_node	On any machine with room. --any-node is short for this.
  wait_same_node	On its original machine; if it has no room yet, the pod stays waiting and starts by itself once it does.
  wait_any_node	On any machine; if none has room yet, the pod stays waiting and starts by itself once one does.

  Without --placement or --any-node, the server picks what the console’s Start button would: wait_any_node for a pod already waiting for any machine; any_node — or wait_any_node if no machine has room right now — when the pod can no longer run on its original machine; otherwise same_node, or wait_same_node if its original machine has no room right now. The output’s placement: row shows which one was used, and a waiting placement adds a note that the pod starts once a machine has room. Before 1.1 the default was always same_node; pass --placement same_node to keep that.

  Use --any-node or --placement, not both with different values. any_node and wait_any_node can move the pod to another machine, which can permanently delete unpreserved workspace files; local volumes stay behind on the old machine. 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. If the server’s own pick would move a pod with unpreserved workspace files, nothing starts either: the command prints the loss warning, names the placement and exits 2. To consent, run it again with --placement <that placement> --allow-data-loss (plus --yes when unattended).

• 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 <GiB> [--encrypted] [--usage-warning [<percent>]] [--max-price <USD>] [--estimate] [-y]
meshive storage-delete <workspace> <storage> [-y]

storage-create creates network (nfs) storage, which any pod in the workspace can attach. --size must be at least 10 GiB, as in the console. --encrypted turns on at-rest encryption. --usage-warning emails you when the volume is more than 90% full, like the console’s usage warning; give a whole percentage from 1 to 100 for another threshold, e.g. --usage-warning 80. Local storage can’t be created on its own — create it together with a pod with pod-create --local-volume. --type defaults to nfs, and hostPath is refused. --disk and --region are deprecated and ignored — storage is always NVMe — and print a warning; they will be removed in 2.0.

Storage is billed hourly by capacity for as long as it exists, mounted or not — except while its host machine has an open maintenance window. 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 storage-update

meshive storage-update <workspace> <storage> [--name <label>] [--size <GiB>] [--usage-warning [<percent>] | --no-usage-warning] [--estimate] [-y]

Renames a volume, grows it or changes its usage warning — only what you pass changes. A name another volume in the workspace already uses is refused, as in the console. It prints the new size and hourly price next to the current ones and asks for confirmation. --size can only grow a volume (at least 10 GiB); a smaller size is refused with the current size. Growing is billed at the new size from then on. --usage-warning turns the usage warning on, as in storage-create, and --no-usage-warning turns it off. A rename or a usage warning change applies at once; growing runs in the background and prints a transaction.

meshive storage-connect

meshive storage-connect <workspace> <storage> [--no-wait] [--wait-timeout <s>]

Opens a volume for SSH and SFTP, like the console’s Connect, and prints a one-time SSH command and password — the same kind of login as meshive ssh gives for a pod. It doesn’t run ssh for you, and it needs a read & write key. The command waits until the volume is ready (up to --wait-timeout, default 300 seconds); --no-wait prints the current status instead, with the login only if it is ready already. Encrypted storage is unlocked for this and locks again automatically after a while; the output says when. The password expires after a few minutes, and the browser-terminal link in the output contains it, so don’t paste either anywhere shared.

meshive model-detect, model-register, models, model-delete, hf-tokens

Register a Hugging Face model for serving without the console.

meshive model-detect <workspace> Qwen/Qwen3-0.6B            # can it be served? exits 1 if not
meshive model-register <workspace> Qwen/Qwen3-0.6B [--name <label>] [--framework vllm|sglang] [--context <tokens>] [--hf-token <id>]
meshive models <workspace>                                  # registrations; ID goes to serving-deploy
meshive model-delete <id> [-y]
meshive hf-tokens <workspace>                               # token IDs for private repos (added in the console)

Registering is free — the model downloads when you deploy it — so model-register doesn’t ask for confirmation. Registering the same repo again returns the existing registration. model-delete fails while a serving of that model is deployed.

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 registered model by its registration ID — the ID column of meshive models. --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 KiB). 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>	Attach an asset under /inputs (repeatable). The files fetched are whatever the asset holds at that time. An old <id>:<version> still works: the CLI warns and drops the version (assets no longer have versions).
--output-include <glob>	Upload only the files in /outputs that match, e.g. --output-include '*.safetensors' (repeatable). Without it, every file is uploaded. See Choosing which files to save. Needs meshive 1.5 or later.
--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 KiB; 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, a missing/invalid API key, pod-create --wait when the creation failed or the pod wasn’t ready in time, workspace-create --wait when the workspace reached error or wasn’t running in time, workspace-delete when the workspace isn’t empty (and workspace-delete --check when it can’t be deleted), or pod-create --model-set when the set’s files couldn’t be added or the answer didn’t come in time.
2	Bad arguments (e.g. an unknown --status, a malformed --since date, --limit out of range, both a workspace and --all, or --any-node with a different --placement), or a write command that needed confirmation and got none (no TTY and no --yes, or you answered no), including a pod-start that needed data-loss consent and got no --allow-data-loss, a pod-update that needs --allow-node-migration, --allow-data-loss, --drop-watched-folder or --ram before it can go ahead, a pod-update or storage-update with nothing to change, and a workspace-update with a blank --name.