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 workspaces             # list workspaces
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 machines               # list your machines (as a host)
meshive machine <id>           # show a single machine

Global options

Every subcommand (except --version) accepts these:

Option	Description
--api-key <key>	Meshive API key. Overrides MESHIVE_API_KEY and the saved login.
--json	Emit the raw API JSON instead of the formatted table. Disables color.

Scripting with --json

--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). Pipe it to jq for scripting. Color and the human-readable table are automatically suppressed when output isn’t a terminal, when --json is set, or when NO_COLOR / MESHIVE_NO_COLOR is set.

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 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 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 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.

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 machine id for machines). This is what you pass to meshive pods <id> / meshive pod <id> <id> / meshive machine <id>. 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, or both a workspace and --all).