@runinfra/cli 0.1.0

package/LICENSE

@@ -0,0 +1,48 @@
+RunInfra CLI License
+
+Copyright (c) 2026 RightNow AI. All rights reserved.
+
+1. LICENSE GRANT
+
+RightNow AI grants you a non-exclusive, non-transferable, revocable license
+to install and use this software ("the CLI") for the purpose of accessing
+the RunInfra service and downloading model packages your workspace is
+entitled to.
+
+2. RESTRICTIONS
+
+You may not redistribute, sell, sublicense or publish the CLI or any part of
+it. You may not modify the CLI and distribute the result. You may not remove
+or alter this notice.
+
+These restrictions apply to the CLI itself. They do NOT apply to the model
+packages the CLI downloads: each package carries its own license, stated on
+its product page and included in its kit, and that license governs your use
+of that package.
+
+3. NO WARRANTY
+
+THE CLI IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+The CLI writes large files to disk and transfers large amounts of data over
+your network. You are responsible for available disk space, for any metered
+bandwidth costs your provider charges, and for where you choose to store
+downloaded packages.
+
+4. LIMITATION OF LIABILITY
+
+IN NO EVENT SHALL RIGHTNOW AI BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE CLI OR THE USE OR OTHER DEALINGS IN THE CLI.
+
+5. TERMINATION
+
+This license ends if you breach it, or when your entitlement to the RunInfra
+service ends. On termination, stop using the CLI and delete it. Packages you
+have already lawfully downloaded remain governed by their own licenses.
+
+6. CONTACT
+
+https://runinfra.ai

package/README.md

@@ -0,0 +1,458 @@
+# @runinfra/cli
+
+Sign in from your terminal and pull the optimized model packages your workspace
+owns.
+
+Node 20 or newer. **Zero runtime dependencies** by design, so it installs
+quickly and runs cleanly inside a slim container or a locked-down host.
+
+```console
+$ npm install -g @runinfra/cli
+$ runinfra login
+$ runinfra pull <slug> --out ./models
+```
+
+Replace `<slug>` with the slug shown on your package's page under
+**Optimized models** on runinfra.ai, for example
+`qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm`.
+
+If your registry cannot find `@runinfra/cli`, the release has not reached it
+yet. Run the CLI from a checkout instead, see [Development](#development).
+
+---
+
+## What the CLI never does
+
+- **It never sees your password.** Sign-in happens in your browser, in your
+  existing RunInfra session. The CLI only ever holds an authorization code and,
+  after the exchange, the key that code bought.
+- **It never asks you to paste an API key.** You do not create a key, copy a
+  key, or store a key by hand. Approving in the browser mints one, the CLI
+  writes it to a file only you can read, and revoking it in Settings kills it.
+- **It never prints the key.** `whoami` and `logout` show a redacted form
+  (`rp_k...8fq2`). No other code path renders it.
+- **The key it holds cannot spend money.** CLI keys carry `purpose = 'cli'`.
+  The inference gateway refuses every purpose that is not `customer`, so a
+  leaked credentials file cannot be turned into inference spend. It opens
+  exactly one door: downloading a package your workspace already owns.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `runinfra login [--device]` | Connects this terminal by having you approve it in a browser. |
+| `runinfra pull <slug> [--out DIR] [--concurrency N]` | Downloads a package this workspace owns. Resumable. |
+| `runinfra logout` | Deletes the local credential and tells you where to revoke the key. |
+| `runinfra whoami` | Shows what this machine has stored, and when its access expires. |
+
+---
+
+## `runinfra login`
+
+### What actually happens today
+
+There are two flows, and the CLI picks for you.
+
+**On a machine with a browser**, `runinfra login` opens the approval page
+itself, and the approved code is delivered straight back to a listener on
+`127.0.0.1`. You click Approve and the terminal connects on its own. If that
+listener cannot be reached, the page shows the code so you can paste it into
+the prompt that is already waiting, and the sign-in still completes.
+
+**On a headless box** reached over SSH, in CI, or with no graphical display,
+there is nothing to open, so the CLI prints a short code and you type it into
+the page on whatever device does have a browser. It never puts the code in a
+link: a link that arrives with the code already in it did not come from
+RunInfra.
+
+### On a laptop
+
+```console
+$ runinfra login
+Opened your browser to approve this terminal.
+  https://runinfra.ai/cli/authorize?request=3b1f2e9c-illustrative-request-id
+Waiting for approval. This request expires in 10 minutes.
+  Or paste the code shown on the approval page and press Enter:
+Connected to workspace <your-workspace-id>.
+  Credentials stored at /home/mona/.config/runinfra/credentials.json
+  This access expires 2026-10-24T09:14:02.118Z.
+  Revoke this terminal any time from Settings, API keys.
+```
+
+`Waiting for approval` repaints itself in place on a terminal, and is logged
+once every ten seconds when the output is piped to a file.
+
+### On a headless SSH box
+
+Identical, with a different reason line. The CLI does not try to open a browser
+over SSH, in CI, or on a machine with no graphical display: launching
+`xdg-open` there prints a stack trace and hangs.
+
+```console
+mona@gpu-07:~$ runinfra login
+Using the device flow because this is an SSH session.
+To connect this terminal:
+  1. On any device, open  https://runinfra.ai/cli/authorize
+  2. Type this code:      T4WX-9BQH
+The page will not fill the code in for you. If a link ever arrives with the code already in it, it did not come from RunInfra.
+  Waiting for approval, 891s left
+Connected to workspace <your-workspace-id>.
+  Credentials stored at /home/mona/.config/runinfra/credentials.json
+  This access expires 2026-10-24T09:14:02.118Z.
+  Revoke this terminal any time from Settings, API keys.
+```
+
+`runinfra login --device` skips the browser attempt entirely and prints the
+code immediately. It is a convenience, not a requirement.
+
+The code is what you type, never what you click. The page has no field that can
+be prefilled from a link, and the CLI discards the RFC 8628
+`verification_uri_complete` field precisely because a code-bearing link is how
+an attacker gets a victim to approve the **attacker's** terminal.
+
+### What the browser shows
+
+The approval page names the account, the workspace, the device label
+(`user@host`, sent by the CLI), the code you typed, and the one thing it
+grants: downloading optimized model packages the workspace already owns.
+Approving requires a role that can deploy in that workspace. A viewer sees
+"Not available for this role" instead of an Approve button, because a viewer
+approval would mint a key that is refused on its first use.
+
+### Timing and limits
+
+- A device code is valid for **15 minutes**. After that the CLI stops polling
+  and says so.
+- Polling starts at one request every **5 seconds** and backs off by five more
+  seconds each time the server says `slow_down`.
+- The minted key lives **90 days**, then `pull` refuses locally and asks you to
+  sign in again. Revoking from Settings ends it sooner.
+
+---
+
+## Where credentials live
+
+One file, `credentials.json`, holding the key, the API base it was minted
+against, the workspace id, the granted scope, and the expiry. No password, no
+refresh token, no cookie.
+
+| Platform | Path | Protection |
+| --- | --- | --- |
+| Linux, macOS | `$XDG_CONFIG_HOME/runinfra/credentials.json`, else `~/.config/runinfra/credentials.json` | Directory `0700`, file `0600` |
+| Windows | `%LOCALAPPDATA%\runinfra\credentials.json` | Directory ACL rewritten to the current user only |
+
+`RUNINFRA_CONFIG_DIR` overrides both, for CI and for mounted volumes.
+
+macOS purists would expect `~/Library/Application Support`. Every CLI already on
+that machine (gh, aws, docker, kubectl) uses `~/.config`, and matching the
+neighbours beats matching the platform guideline for a file people occasionally
+delete by hand.
+
+Windows uses `%LOCALAPPDATA%` rather than `%APPDATA%` so a roaming profile never
+syncs a live API key around a domain. `chmod` means nothing there (Node maps it
+to the read-only attribute), so the directory ACL is rewritten instead:
+
+```console
+icacls "%LOCALAPPDATA%\runinfra" /inheritance:r /grant:r "DOMAIN\user":(OI)(CI)F
+```
+
+`/inheritance:r` drops inherited entries, which on a domain machine routinely
+include Administrators and SYSTEM. `/grant:r` replaces any existing grant
+instead of adding a second one. `(OI)(CI)F` is object- and container-inherit
+full control, so the file created inside inherits it.
+
+If that call fails, the CLI **says so** rather than implying a protection it did
+not apply:
+
+```console
+warning: Could not restrict C:\Users\mona\AppData\Local\runinfra (icacls exited with code 5). The API key is protected only by your Windows profile permissions.
+```
+
+The mode is also applied with an explicit `chmod` on POSIX, because
+`writeFile`'s `mode` option only applies when it creates the file: overwriting an
+existing `0644` credentials file would otherwise keep the loose mode.
+
+---
+
+## `runinfra whoami`
+
+Reports what **this machine** has stored, and labels it as such. There is no
+identity endpoint on the CLI surface, so this does not claim a round trip it did
+not make. A key revoked from Settings five minutes ago still shows here, and
+fails on your next `pull`.
+
+```console
+$ runinfra whoami
+Workspace  <your-workspace-id>
+Key        rp_k3n9 (rp_k...8fq2)
+Grants     catalog:download
+Endpoint   https://runinfra.ai
+Connected  2026-07-26T09:14:02.118Z
+Expires    2026-10-24T09:14:02.118Z (in 2159h 58m)
+This is what this machine has stored. Access may have been revoked from Settings, API keys since it was granted.
+```
+
+The fields go to stdout and the closing sentence to stderr, so
+`runinfra whoami > terminal.txt` captures the facts without the caveat.
+
+---
+
+## Revoking access
+
+Two different actions, and the CLI is careful not to confuse them.
+
+**`runinfra logout` removes the local file. It does not revoke the key.**
+
+```console
+$ runinfra logout
+Removed this machine's credentials.
+  The key rp_k3n9 (rp_k...8fq2) is still valid until 2026-10-24T09:14:02.118Z.
+  To end its access now, revoke it in Settings, API keys on runinfra.ai.
+```
+
+That wording is deliberate. A lost laptop is not handled by deleting a file you
+no longer have access to.
+
+**To actually end a terminal's access:** open **Settings, API keys** on
+runinfra.ai. Every terminal you connected is listed there as
+`RunInfra CLI: user@host`, with its prefix, when it was created, and when it was
+last used. Revoke the row. The next command that terminal runs is refused:
+
+```console
+$ runinfra pull qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm
+error: This terminal's access was revoked.
+  Run `runinfra login` to connect it again.
+```
+
+Revocation takes effect on the next request, and your role in the workspace is
+re-read on every request too. Someone removed from a workspace, or demoted below
+deploy, loses CLI access immediately rather than at their next key rotation.
+
+One honest limit: a download URL already minted stays valid for its 30 minute
+lifetime. Revoking stops new downloads from starting, it does not reach into a
+transfer already in flight.
+
+---
+
+## `runinfra pull`
+
+```console
+$ runinfra pull qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm --out /data/models
+Downloading kit.zip (41.2 GB) into /data/models
+  kit.zip  [########----------------]  33.4%  13.8 GB / 41.2 GB  92.4 MB/s  ETA 49m 12s
+Transferred 41.2 GB in 1h 14m.
+  Checksum verified.
+Saved kit.zip.
+/data/models/kit.zip
+```
+
+The final path is the only thing on stdout, so `MODEL=$(runinfra pull ... )`
+works and progress does not pollute it.
+
+Options: `--out DIR` (defaults to the working directory) and `--concurrency N`
+(1 to 16, defaults to 8).
+
+### How resume works
+
+Interrupt it. Run the same command again.
+
+```console
+^C
+Stopping. Run the same command again to resume.
+error: Download interrupted.
+  Run the same command again to resume from the bytes already on disk.
+
+$ runinfra pull qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm --out /data/models
+Resuming kit.zip: 13.8 GB of 41.2 GB already on disk.
+  kit.zip  [##########--------------]  41.7%  17.2 GB / 41.2 GB  88.1 MB/s  ETA 46m 30s
+```
+
+A second Ctrl-C exits immediately without finishing the write in progress.
+
+Two files carry the state. `<name>.part` holds the bytes, preallocated to the
+final size so a full disk is discovered now rather than at 90%.
+`<name>.part.json` records which byte ranges are **durable**: a range is written
+to that file only after the data is flushed to disk, so a power cut can lose
+work but can never claim bytes that are not there.
+
+Resume is refused, and the partial file discarded, in three cases. Each one
+prints why:
+
+- **The sidecar is missing or unreadable.** The `.part` is preallocated, so its
+  length says nothing about which bytes are real. Guessing would produce a file
+  that passes every check except the checksum, hours later.
+- **The package was republished while you were downloading.** Version, size or
+  ETag moved. Continuing would splice two different artifacts into one file.
+- **The final file already exists at a different size.** Nothing is overwritten;
+  you are told to move it or pass a different `--out`.
+
+Everything else resumes. A dropped connection retries the affected chunk a few
+times with backoff before giving up. The download URL is valid for 30 minutes and a large kit is not, so the
+CLI renews it automatically 2 minutes before expiry and whenever storage refuses
+a stale signature. Every renewal re-checks that the artifact is still the same
+one.
+
+### Verification
+
+When the catalog published a sha256 for the package, the CLI hashes the file and
+compares. A mismatch renames nothing, so bad bytes never appear under the final
+name:
+
+```console
+error: The downloaded bytes do not match the published checksum for qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm.
+  The partial file was left at /data/models/kit.zip.part. Delete it and run the command again.
+```
+
+When the package publishes no checksum, the CLI says the file is **UNVERIFIED**
+rather than implying it checked something.
+
+### Before it writes anything
+
+`pull` proves entitlement first, then probes the real size, then checks free
+space against what is **left** plus 5% headroom. The failure you are most likely
+to hit happens in the first two seconds rather than in hour four:
+
+```console
+error: Not enough free space in /data/models: 12.4 GB available, 28.7 GB needed.
+  Free some space or pass --out to a larger volume, then run the same command again to resume.
+```
+
+---
+
+## Exit codes
+
+Scripted use is a first-class case, so failures are grouped rather than all
+being `1`.
+
+| Code | Meaning | Retry? |
+| --- | --- | --- |
+| 0 | Success | |
+| 2 | Bad usage, or an unsupported Node runtime | No |
+| 3 | Not signed in, denied, expired, or revoked | After `runinfra login` |
+| 4 | The workspace does not own the package, or its files are not published yet | No |
+| 5 | Network or server failure | Yes |
+| 6 | Integrity failure: checksum mismatch, or the artifact changed mid-download | Start over |
+| 7 | No space, or the destination is not writable | After freeing space |
+| 130 | Interrupted | Yes, it resumes |
+
+---
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `RUNINFRA_API_BASE` | Point at another deployment. Plaintext `http://` is accepted **only** for a loopback host, because the sign-in response carries a live API key. |
+| `RUNINFRA_CONFIG_DIR` | Where credentials are stored. Overrides the platform default. |
+
+The base a key was minted against travels with the key. If you sign in against a
+preview deploy and then run against production, the CLI warns and uses the base
+the key belongs to rather than sending that credential to a host that never
+issued it.
+
+---
+
+## The HTTP contract
+
+Every path and field this CLI speaks lives in `src/endpoints.ts`, read off the
+routes as built.
+
+| Route | Purpose |
+| --- | --- |
+| `POST /api/cli/device/init` | Start the device flow, returns the device code and the code you type |
+| `POST /api/cli/device/poll` | Poll for approval, returns the key once approved |
+| `POST /api/cli/device/loopback-init` | Start the browser flow, returns the request id the approval page opens |
+| `POST /api/cli/token` | Loopback authorization code exchange, the browser flow's final step |
+| `GET /cli/authorize` | The approval page, browser only |
+| `GET /api/catalog/<slug>/download` | Dual auth, accepts a `purpose='cli'` bearer key |
+
+Path choices are forced by the CSRF origin check: `/api/cli/token` and
+`/api/cli/device/` are exempt from it, because no non-browser HTTP client sends
+`Origin`. `/api/cli/authorize` is **not** exempt (that one is the browser
+approving with session cookies), so the CLI never calls it. **Any new
+CLI-called POST route must live under one of the two exempt prefixes or it will
+403 on every platform.**
+
+### Refusal envelope
+
+Sign-in routes answer OAuth-shaped `{ "error": "<code>" }` (RFC 6749 5.2, RFC
+8628 3.5) with `Retry-After` in the **header**, not the body:
+
+```
+invalid_request  invalid_grant  expired_token  access_denied
+authorization_pending  slow_down  rate_limited  temporarily_unavailable
+server_error  unsupported_code_challenge_method  invalid_scope
+```
+
+`invalid_grant` deliberately fuses replayed, unapproved, wrong-verifier,
+wrong-redirect and never-existed, and the device poll answers `expired_token`
+for a code it has never seen. The server refuses to be an oracle, so the CLI
+does not try to reconstruct the distinction either.
+
+The download route answers `{ ok: false, code }` with two vocabularies:
+`not_found`, `artifact_not_ready`, `rate_limited` for the download itself, and
+`missing_credentials`, `invalid_key`, `key_revoked`, `key_expired`,
+`workspace_access_revoked`, `auth_unavailable` when the key did not hold up.
+They map to different exit codes, so "your key was revoked" and "your workspace
+does not own this" never collapse into one sentence.
+
+### Sign-in success body
+
+```jsonc
+{ "apiKey": "rp_...", "keyPrefix": "rp_k3n9", "tokenType": "Bearer",
+  "scope": "catalog:download", "workspaceId": "<your-workspace-id>",
+  "expiresAt": "2026-10-24T09:14:02.118Z", "expiresIn": 7776000 }
+```
+
+Deliberately not called `access_token`: this is a RunInfra API key with no
+refresh and no introspection endpoint, and borrowing the OAuth name would
+promise a contract that does not exist.
+
+### How sign-in is secured
+
+OAuth 2.0 authorization code with PKCE (RFC 7636), plus the device shape
+(RFC 8628) for headless hosts. The code verifier stays in the CLI process and is
+never written, printed, or sent: only its SHA-256 challenge goes on the wire at
+request time. Codes are stored hashed, so reading the database cannot complete a
+pending sign-in. An approval is consumed by a single conditional UPDATE, so two
+racing exchanges cannot both mint a key. Redirect targets are restricted to
+loopback literals in the route, in the shared core, and in a database CHECK.
+
+### Server-side gaps
+
+Two things this CLI wants still do not exist. It degrades honestly rather than
+pretending, and each becomes a small change here when it lands.
+
+1. **Identity.** There is no `GET /api/cli/whoami`, so `whoami` reports the
+   local credential and says so in those words. It makes no network call, and
+   access it reports may already have been revoked from Settings.
+2. **Revocation from the terminal.** `logout` removes the local credential and
+   points you at Settings; it does not claim to have revoked the key, which
+   stays valid until its expiry. Ending a key from the terminal itself is not
+   offered yet: revoke it from **Settings, API keys** on runinfra.ai, which
+   takes effect on that terminal's next request.
+
+The browser sign-in flow that this document once listed as unbuilt now exists.
+It is created by `POST /api/cli/device/loopback-init`, which takes
+`{ codeChallenge, codeChallengeMethod, scope, redirectUri, deviceLabel }` and
+returns `{ requestId }`. It sits under `/api/cli/device/` so it inherits the
+origin exemption, which is why a route that is not a device route lives at
+that path.
+
+---
+
+## Development
+
+```console
+node ../node_modules/typescript/bin/tsc -p tsconfig.json      # build to dist/
+node ../node_modules/vitest/vitest.mjs run cli/src --root ..  # tests
+node bin/runinfra.mjs --help                                  # run it
+RUNINFRA_API_BASE=http://localhost:3000 node bin/runinfra.mjs login
+```
+
+Tests cover the pure logic, deliberately: range planning and resume arithmetic,
+sidecar validation, the lease-refresh decision, per-platform browser command
+selection, redirect construction for IPv4 and IPv6, credential and path
+resolution, and every response parser. Nothing in the test suite opens a socket
+to the internet.

package/bin/runinfra.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// The published entry point.
+//
+// Kept as hand-written JavaScript rather than compiled output so the shebang
+// and the exit-code handling are readable in the installed package, and so a
+// broken build surfaces as "cannot find dist/main.js" instead of a shebang
+// that silently disappeared.
+
+import { run } from "../dist/main.js";
+
+// Ctrl-C must stop the transfer, not kill the process mid-write: the
+// download engine watches this signal, finishes the write it is on, records
+// the last durable range, and returns 130. A second Ctrl-C exits hard, which
+// is the behaviour every terminal user expects when the first one is not
+// working.
+const controller = new AbortController();
+let interrupts = 0;
+
+process.on("SIGINT", () => {
+  interrupts += 1;
+  if (interrupts > 1) {
+    process.exit(130);
+  }
+  process.stderr.write("\nStopping. Run the same command again to resume.\n");
+  controller.abort();
+});
+
+// EPIPE is what `runinfra whoami | head -1` produces. It is not an error.
+// Anything else on stdout is reported and exits; throwing from inside an
+// error handler would crash with a stack trace instead of a sentence.
+process.stdout.on("error", (error) => {
+  if (error && error.code === "EPIPE") {
+    process.exit(0);
+  }
+  process.stderr.write(`error: could not write output: ${error?.message ?? error}\n`);
+  process.exit(1);
+});
+
+try {
+  process.exitCode = await run(process.argv.slice(2), { signal: controller.signal });
+} catch (error) {
+  process.stderr.write(
+    `error: ${error instanceof Error ? error.message : String(error)}\n`,
+  );
+  process.exitCode = 1;
+}

package/dist/args.js

@@ -0,0 +1,142 @@
+export const COMMANDS = ["login", "logout", "whoami", "pull"];
+export const MIN_CONCURRENCY = 1;
+export const MAX_CONCURRENCY = 16;
+function emptyArgs(command) {
+    return {
+        command,
+        device: false,
+        slug: null,
+        out: null,
+        concurrency: null,
+    };
+}
+function isFlag(token) {
+    return token.startsWith("-") && token !== "-";
+}
+function splitInlineValue(token) {
+    const equals = token.indexOf("=");
+    if (equals === -1)
+        return { name: token, value: null };
+    return { name: token.slice(0, equals), value: token.slice(equals + 1) };
+}
+export function parseArgs(argv) {
+    const tokens = [...argv];
+    if (tokens.some((token) => token === "--help" || token === "-h")) {
+        return { ok: true, args: emptyArgs("help") };
+    }
+    if (tokens.some((token) => token === "--version" || token === "-V")) {
+        return { ok: true, args: emptyArgs("version") };
+    }
+    const first = tokens[0];
+    if (first === undefined) {
+        return { ok: true, args: emptyArgs("help") };
+    }
+    if (isFlag(first)) {
+        return { ok: false, message: `Unknown option ${first}. Run \`runinfra --help\`.` };
+    }
+    if (!COMMANDS.includes(first)) {
+        return {
+            ok: false,
+            message: `Unknown command "${first}". Expected one of: ${COMMANDS.join(", ")}.`,
+        };
+    }
+    const command = first;
+    const args = emptyArgs(command);
+    const positionals = [];
+    for (let index = 1; index < tokens.length; index += 1) {
+        const raw = tokens[index];
+        if (raw === undefined)
+            break;
+        if (!isFlag(raw)) {
+            positionals.push(raw);
+            continue;
+        }
+        const { name, value: inline } = splitInlineValue(raw);
+        const takeValue = () => {
+            if (inline !== null)
+                return inline.length > 0 ? inline : null;
+            const next = tokens[index + 1];
+            if (next === undefined || isFlag(next))
+                return null;
+            index += 1;
+            return next;
+        };
+        switch (name) {
+            case "--device": {
+                if (command !== "login") {
+                    return { ok: false, message: `--device applies to \`runinfra login\` only.` };
+                }
+                args.device = true;
+                break;
+            }
+            case "--out":
+            case "-o": {
+                if (command !== "pull") {
+                    return { ok: false, message: `--out applies to \`runinfra pull\` only.` };
+                }
+                const value = takeValue();
+                if (value === null) {
+                    return { ok: false, message: "--out needs a directory, for example --out ./models." };
+                }
+                args.out = value;
+                break;
+            }
+            case "--concurrency":
+            case "-c": {
+                if (command !== "pull") {
+                    return { ok: false, message: `--concurrency applies to \`runinfra pull\` only.` };
+                }
+                const value = takeValue();
+                if (value === null) {
+                    return {
+                        ok: false,
+                        message: `--concurrency needs a number between ${MIN_CONCURRENCY} and ${MAX_CONCURRENCY}.`,
+                    };
+                }
+                if (!/^[0-9]+$/u.test(value)) {
+                    return {
+                        ok: false,
+                        message: `--concurrency must be a whole number between ${MIN_CONCURRENCY} and ${MAX_CONCURRENCY}, got "${value}".`,
+                    };
+                }
+                const parsed = Number.parseInt(value, 10);
+                if (parsed < MIN_CONCURRENCY || parsed > MAX_CONCURRENCY) {
+                    return {
+                        ok: false,
+                        message: `--concurrency must be between ${MIN_CONCURRENCY} and ${MAX_CONCURRENCY}, got ${parsed}.`,
+                    };
+                }
+                args.concurrency = parsed;
+                break;
+            }
+            default:
+                return {
+                    ok: false,
+                    message: `Unknown option ${name}. Run \`runinfra ${command} --help\`.`,
+                };
+        }
+    }
+    if (command === "pull") {
+        const slug = positionals[0];
+        if (slug === undefined) {
+            return {
+                ok: false,
+                message: "runinfra pull needs a package slug. Copy the exact slug from your package page on runinfra.ai, for example `runinfra pull qwen3-6-27b-fp8cd-v3-mlponly-h100-vllm`.",
+            };
+        }
+        if (positionals.length > 1) {
+            return {
+                ok: false,
+                message: `runinfra pull takes one package slug, got ${positionals.length}.`,
+            };
+        }
+        args.slug = slug;
+    }
+    else if (positionals.length > 0) {
+        return {
+            ok: false,
+            message: `runinfra ${command} takes no arguments, got "${positionals[0] ?? ""}".`,
+        };
+    }
+    return { ok: true, args };
+}