> ## Documentation Index
> Fetch the complete documentation index at: https://docs.u-kiyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the public command-line client and manage compute.

## Install

Current CLI: **0.2.3**. Supported on Windows, macOS and Linux (including WSL). Use Node.js 22 or newer and native OpenSSH for `exec`/`ssh`. No npm package or repository access is required. Download the public release and verify its checksum before running it; stop if verification fails. Release versions and hashes are in [latest.json](https://u-kiyo.ai/releases/latest.json). Full platform-specific launcher/PATH instructions are in the [CLI installation guide](https://u-kiyo.ai/releases/cli/0.2.3/INSTALL.md).

<Tabs>
  <Tab title="macOS / Linux / WSL">
    ```bash theme={null}
    mkdir -p "$HOME/.local/share/ukiyo" && cd "$HOME/.local/share/ukiyo"
    curl -fsSLO https://u-kiyo.ai/releases/cli/0.2.3/ukiyo-cli-0.2.3.mjs
    echo "27d2429cdab6b8846f4ebe05bb688a711a003e0dbf6a7f0b26641ffed9f29710  ukiyo-cli-0.2.3.mjs" | shasum -a 256 -c -
    node "$HOME/.local/share/ukiyo/ukiyo-cli-0.2.3.mjs" offers --json
    ```

    On Linux without `shasum`, use `sha256sum -c -` for verification. Stop if verification fails. WSL uses Linux permission handling: keep credentials in your WSL home on its Linux filesystem, not under `/mnt/c`.
  </Tab>

  <Tab title="Windows PowerShell">
    Install Node.js 22 or newer and enable Windows **OpenSSH Client** under **Settings → System → Optional features** if `Get-Command ssh` fails. The CLI installer itself needs no administrator session.

    ```powershell theme={null}
    $release = Invoke-RestMethod https://u-kiyo.ai/releases/latest.json
    $installer = $release.tools.cli.files | Where-Object { $_.path -eq 'cli/0.2.3/install.ps1' }
    if (-not $installer) { throw 'CLI installer not found; stop here.' }
    $path = Join-Path $env:TEMP 'ukiyo-install-0.2.3.ps1'
    Invoke-WebRequest -UseBasicParsing $installer.url -OutFile $path
    if ((Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash.ToLowerInvariant() -ne $installer.sha256) { throw 'Checksum mismatch; stop here.' }
    powershell.exe -NoProfile -ExecutionPolicy Bypass -File $path
    ```

    Open a new terminal and run `ukiyo --version`. The Windows launcher is installed in `%LOCALAPPDATA%\Ukiyo\bin`. Do not run Unix `chmod` commands on Windows.
  </Tab>
</Tabs>

Public offers need no token. For a new account, run `ukiyo signup --json` after installing the launcher from the installation guide (or `node <downloaded-cli-path> signup --json`); no email, browser login, or Telegram is required. The CLI stores the credential securely without printing the raw secret. Unix storage uses 0700 directories/0600 files. Windows storage uses protected, user-only SID-based ACLs under `%USERPROFILE%\.ukiyo`. Unsafe permissions, ACLs, ownership, symlinks/junctions and identity overwrites are rejected. Existing scoped tokens may use private `UKIYO_API_TOKEN` configuration. The API URL defaults to production; override `UKIYO_API_URL` only when intentionally using another environment.

## Commands

Run `ukiyo --help` (or `node <downloaded-cli-path> --help`) for flags. The current autonomous workflow is `signup → balance → topup link → offers → rent → ACTIVE → exec → terminate`.

* `signup --json`: headless account and securely stored scoped credential.
* `balance --json`: balance and remaining key budget.
* `topup link --amount 5 --json`: one payer funding handoff.
* `offers --gpu RTX4090 --count 1 --json`: live cached inventory and customer prices.
* `rent --gpu RTX4090 --count 1 --budget 5 --wait --timeout 600 --json`: GPU/count intent with an accepted hourly ceiling; `--offer OFFER_ID` instead requests that exact offer without substitution. Preserve the same intent and `--idempotency-key` when retrying.
* `list`: deployments.
* `status <id>`: deployment state.
* `exec <deployment-id> --json -- nvidia-smi`: authenticated SSH without exposing the private key.
* `terminate <id> --yes --wait --json`: irreversible termination, with confirmed terminal state or a bounded timeout.

The CLI does not promise OS-keychain persistence. Keep secrets out of shell history and source control. Funding is required once before autonomous rentals; there is no per-rental human approval. A wait timeout retains the rental/deployment identity: inspect it and do not create a second rental. Legacy card checkout commands remain available; they are not the autonomous path.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.