CLI reference

The matmul command rents GPUs from your terminal: find an offer, launch a VM or Docker image, SSH in, and watch your balance. It's a thin wrapper over the Python SDK, which calls the REST API.

Install and log in

pip install matmul-cloud
matmul --help
matmul login

matmul login prints a one-time code and opens the console in your browser. Sign in if you need to, check that the page shows the same code, and click Authorize this CLI. The CLI then receives a new API key named after your machine (for example cli: robin-mbp) and saves it to ~/.config/matmul/config.json (mode 600). Over SSH, or on a machine without a browser, it prints the link instead: open it on any device. The key acts as you, in the organization you're signed in to. (Browser login needs a matmul-cloud release after 0.1.0; with 0.1.0, use an API key as below.)

Only approve a code you just started yourself. If someone sends you a login link, click Deny: approving it would give their terminal access to your account.

For CI and scripts, where nobody can click Authorize, create a key on the CLI & API page of the console and set MATMUL_API_KEY, or save it with matmul login --api-key lmk_.... Every command reads these environment variables, which take precedence over the file:

Wherever a command takes an instance, you can give its id (ins_...) or its name. A name has to be unambiguous among your instances that aren't deleted.

Offers

matmul offers

Lists machines you can launch right now, cheapest first, with GPU, VRAM per GPU, vCPUs, RAM, region, price per hour and offer id.

SSH keys

An organization can hold up to 20 keys. Viewers can list keys but not add or remove them.

Instances

matmul instance create

matmul instance create --name dev --gpu H100 --max-price 3 --wait
matmul instance create --name nb --gpu H100 --image pytorch/pytorch:latest --keep-alive --wait

--gpu takes the cheapest match. To launch one particular machine from the list (a region, a size, a price), pass its id from the OFFER ID column of matmul offers with --offer, and its price as the guard:

matmul offers --gpu H100                   # note the OFFER ID and PRICE
matmul instance create --name dev --offer <OFFER_ID> --max-price <PRICE> --wait

Offers are live. If that machine has been taken since you listed it, the launch fails with "that offer is no longer available; search again"; if its price went above --max-price, it fails with "the price rose above your max_hourly_price_cents; search again". Nothing is charged either way: run matmul offers again. The console's Launch page shows the same command, filled in, for any offer you pick.

--args, --keep-alive, --env, --port and --shm need --image. With --wait, the CLI shows elapsed time and status while the provider boots the machine, which often takes several minutes, and gives up after 15 minutes. With --image, the instance is running only once the container is up, so pulling a large image adds to the wait.

matmul instance ls / get / rm

Instance status is one of provisioning, running, error, deleting and deleted. ls and get print a warning first if your account is frozen.

matmul ssh

matmul ssh [--host] REF [-- COMMAND...]
matmul ssh dev -- nvidia-smi
matmul ssh dev -- 'nvidia-smi; df -h'        # one quoted string: a shell command line
matmul ssh dev -- python -c 'print(1)'       # several words: passed on exactly as typed

Opens a shell on a running instance, using your system ssh. On an instance with an image you land inside the container; --host gives you the VM instead. Anything after -- runs instead of a shell: a single argument is run as a shell command line, the way plain ssh does it, and several arguments are passed on word by word. When input isn't a terminal (a script, CI, or a pipe such as echo 'print(1)' | matmul ssh dev -- python), the command runs without asking for one, inside the container too.

In matmul-cloud 0.1.0, put --host before the instance name, and container commands always ask for a terminal and treat a single quoted argument as one word. --host after the name, command lines and non-terminal use needs a matmul-cloud release after 0.1.0.

Public app links: expose, unexpose, ports

matmul expose REF PORT, matmul unexpose REF PORT and matmul ports REF manage public HTTPS links to ports on an instance. They're built but switched off for now; the CLI says so if you try. Until then, use SSH port forwarding: ssh -L 8888:localhost:8888 ....

Billing

Billing commands need the owner role. The API enforces the top-up minimum ($10) and maximum; see Pricing & billing.

Managed jobs

Not available on MatMul yet. The commands exist, and when the server has jobs switched off, matmul run says so and suggests matmul instance create. How they'll work is in Managed jobs.

Flags for matmul run:

Exit codes and errors

Errors go to stderr as error: ... with the API's message. The exit code is 2 for authentication and permission errors (a bad key, or your role doesn't allow it) and 1 for anything else.

• "no API key: set MATMUL_API_KEY or run `matmul login`": log in first.
• "invalid api key": the key was revoked or mistyped. Run matmul login again, or create a new key.
• "the code expired before it was approved" or "the login was denied in the browser" (from matmul login, exit code 1): run matmul login again. A code is good for 10 minutes.
• "not allowed for your role": viewers can't launch or add and remove SSH keys; only owners can use billing.
• "insufficient balance" or "account frozen": add credit with matmul billing add-credit.
• "that offer is no longer available" or "the price rose above your max_hourly_price_cents": run matmul offers again.
• "instance limit reached": delete an instance first; its slot frees up as soon as you do. New accounts can run one at a time.
• "GPU capacity is temporarily limited; please try again later": MatMul is at its platform-wide capacity cap. Nothing was launched or charged; try again later (see Pricing & billing).

The old LEMNOS_* environment variables and ~/.config/lemnos/config.json still work if the MATMUL_* ones aren't set.