# CLI guide

Use `sr` to launch an OS, inspect sessions and credits, and retrieve SSH or RDP connection details. Complete [installation and API access](/docs/authentication/) first.

## First session

```bash
sr images
sr credits
sr launch ubuntu-24.04 --ttl 30m --open
```

The launch command waits for readiness, prints the session ID and native connection details, and opens the browser when `--open` is supplied. Sign in to the browser with the account that owns the session.

For a Windows desktop:

```bash
sr launch windows-server-2025 --ttl 30m --open
```

The output includes the IP, RDP username and password, and browser URL. Linux output includes a suggested SSH command and a path to a privately saved key file. Copy the values from your own output; sample IDs and addresses in these docs are placeholders.

## Commands

| Command | Behavior |
| --- | --- |
| `sr login` | Prompt for an issued credential, validate it and save a new config file. |
| `sr images` | Print the available OS catalog and credit rates as JSON. |
| `sr credits` | Show remaining and used credits. |
| `sr credits --json` | Return the complete credit account response. |
| `sr launch IMAGE` | Create a session and wait for readiness by default. |
| `sr list` | List your sessions as JSON, including their states. |
| `sr get SESSION_ID` | Inspect a session; fetch credentials too if it is ready. |
| `sr destroy SESSION_ID` | Request destruction and wait for a terminal state. |
| `sr --help` | Show commands and global options. |
| `sr launch --help` | Show launch options. |

`sr serve` is an operator command for a configured local backend, not a step required to use the hosted service.

## Launch options

| Option | Default | Meaning |
| --- | --- | --- |
| `--ttl 30m` | `30m` | Absolute session lifetime. Accepts duration strings such as `5m`, `30m`, `1h`, or `300s`. |
| `--transfer-budget 50` | `50` | Maximum outbound-transfer credits, an integer from 10 through 500. |
| `--open` | Off | Open the returned browser URL. |
| `--json` | Off | Print the session response as JSON to stdout. |
| `--no-wait` | Off | Return a queued session without waiting for credentials. |
| `--key VALUE` | Generated UUID | Stable idempotency key for this logical launch. |

Trial sessions allow 5–30 minutes; funded sessions allow up to four hours. Basic Linux terminals default to Small (2 GiB). Add `--size standard` for 4 GiB, or `--size small` to be explicit. Security desktops and Windows support Standard only. CLI sessions run until their selected TTL or explicit destruction; browser inactivity does not end a CLI-launched job. A launch normally waits up to 15 minutes for readiness; there is no CLI timeout flag. Use an SDK if you need to configure the wait timeout.

To set a lower outbound-transfer limit:

```bash
sr launch ubuntu-24.04 --ttl 30m --transfer-budget 10
```

This permits up to 5 compute credits and 10 transfer credits. Only actual usage is deducted. Selecting these limits does not spend credits, and the VM stops if your balance runs out.

## Inspect and destroy

```bash
sr list
sr get ses_YOUR_SESSION_ID
sr destroy ses_YOUR_SESSION_ID
```

Replace `ses_YOUR_SESSION_ID` with the ID returned by launch. Closing your shell or browser does not destroy a session. If the destroy command times out, use `sr get` to check its state and retry destruction if needed.

`sr get` on a ready session prints native credentials, including the full SSH private key for Linux. Keep that output out of shared logs.

## Connect with SSH or RDP

For Linux, use the SSH command printed by `sr launch`. The CLI stores the key under the config directory's `keys/` subdirectory with mode `0600`. Native SSH/SFTP and RDP access currently require a network approved by the deployment operator; the browser does not require your own native ingress rule.

For Windows, open your RDP client and enter the returned IP and port, username, and password. Compare its certificate fingerprint with `credentials.certificate_fingerprint` before trusting a new host. A private browser session is also available through the returned URL.

For SSH scripts, pin the returned host key instead of disabling host-key checking. This Bash example also needs `jq` and OpenSSH:

```bash
umask 077
sr launch ubuntu-24.04 --ttl 30m --json > session.json
jq -r '.ip + " " + .credentials.host_public_key' session.json > session.known_hosts
ssh -o UserKnownHostsFile="$PWD/session.known_hosts" \
  -o StrictHostKeyChecking=yes \
  -i "$(jq -r '.credentials.private_key_path' session.json)" \
  "$(jq -r '.credentials.username + "@" + .ip' session.json)" uname -a
sr destroy "$(jq -r '.id' session.json)"
```

Use the same SSH key and host-key verification for `scp` or SFTP. Always destroy the VM even if your remote command fails; a shell trap or an SDK cleanup context is useful for longer automation. `session.json` contains sensitive connection details.

## Automation and safe retries

```bash
sr launch ubuntu-24.04 --ttl 30m --no-wait --json --key investigation-482 > session.json
sr get ses_YOUR_SESSION_ID
```

Launch writes its request key to stderr, so stdout remains parseable JSON. A no-wait response has no usable native credentials yet. Poll `sr get` with a short delay until `ready`, or until a terminal failure; do not poll continuously.

If a launch response is lost, repeat the same command with **the same key and identical launch options**. It resolves to the same logical session rather than allocating another one. Use a new key for a genuinely new session. A changed payload under an existing key is a conflict. Do not mix generated keys with a blind retry loop.

The CLI exits with status 1 on a runtime error and writes the error to stderr. See [Troubleshooting](/docs/troubleshooting/) for HTTP errors, timeouts, and insufficient credits.


## Security desktops

```bash
sr launch parrot --ttl 30m --open
sr launch sift --ttl 30m --open
sr launch remnux --ttl 30m --open
sr launch flare --ttl 30m --open
```

The tools are preinstalled. These images use Standard size automatically. Parrot, SIFT and REMnux return both an RDP password and an SSH key; the CLI prints both connection methods and stores the SSH key in its private keys directory. The browser link opens the desktop. FLARE-VM returns Windows RDP credentials. Use the username returned by the API; SIFT uses `sansforensics` and REMnux uses `remnux`.