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

# CLI Hello World

The Vast.ai CLI gives you command-line access to the entire platform, authentication, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and more. Anything you can do in the web console, you can automate from your terminal.

This guide walks through the core workflow: install the CLI, authenticate, search for a GPU, rent it, wait for it to boot, connect to it, copy data, and clean up. By the end you'll understand the commands needed to manage instances without touching the web console.

## Prerequisites

* A Vast.ai account with credit (\~\$0.01-0.05, depending on test instance run time)
* Python 3 installed

## 1. Install the CLI

Install from PyPI:

```bash theme={null}
pip install vastai
```

Or grab the latest version directly from GitHub:

```bash theme={null}
wget https://raw.githubusercontent.com/vast-ai/vast-cli/master/vast.py -O vastai && chmod +x vastai
```

Verify the installation:

```bash theme={null}
vastai --help
```

## 2. Set Your API Key

Generate an API key from the [Keys page](https://cloud.vast.ai/manage-keys/) by clicking **+New**. Copy the key, you'll only see it once.

Save it to the CLI:

```bash theme={null}
vastai set api-key YOUR_API_KEY_HERE
```

This stores your key in a config file in your home directory. Do not share your API keys with anyone.

<Tip>
  The console creates a full-access key by default. You can also create scoped keys with limited permissions using `vastai create api-key`, useful for CI/CD or shared tooling. See the [permissions documentation](/api-reference/permissions) for details.
</Tip>

## 3. Verify Authentication

Confirm your key works by fetching your account info:

```bash theme={null}
vastai show user
```

This returns your user ID, email, balance, and SSH key. If you see an authentication error, double-check your API key.

## 4. Search for GPUs

Find available machines using `search offers`. This query returns on-demand RTX 4090s on verified machines with direct port access, sorted by deep learning performance per dollar:

```bash theme={null}
vastai search offers 'gpu_name=RTX_4090 num_gpus=1 verified=true direct_port_count>=1 rentable=true' -o 'dlperf_usd-'
```

Each parameter in the query controls a different filter:

| Parameter              | Meaning                                                     |
| ---------------------- | ----------------------------------------------------------- |
| `gpu_name=RTX_4090`    | Filter to a specific GPU model                              |
| `num_gpus=1`           | Exactly 1 GPU per instance                                  |
| `verified=true`        | Only machines verified by Vast.ai (identity-checked hosts)  |
| `direct_port_count>=1` | At least 1 directly accessible port (needed for direct SSH) |
| `rentable=true`        | Only machines currently available to rent                   |
| `-o 'dlperf_usd-'`     | Sort by DL performance per dollar, best value first         |

Note the `ID` of the offer you want, you'll use it in the next step. If no offers are returned, try relaxing your filters (e.g. a different GPU model or removing `direct_port_count`).

<Tip>
  Use `vastai search offers --help` for the full list of filter fields and options, or see the [CLI commands reference](/cli/reference/search-offers).
</Tip>

## 5. Register Your SSH Key

**Do this before creating an instance.** Your SSH public key must be registered on your account, it is applied at container creation time.

```bash theme={null}
vastai create ssh-key ~/.ssh/id_ed25519.pub
```

If you don't have a key yet, omit the argument and the CLI will generate one:

```bash theme={null}
vastai create ssh-key
```

Your key persists on your account, you only need to do this once per key. If you forgot and already created an instance, use the SSH key button on the instance card in the console to add a key without recreating.

## 6. Create an Instance

Rent the machine using `create instance` with the offer ID from step 4 (search):

```bash theme={null}
vastai create instance OFFER_ID --image pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime --disk 20 --onstart-cmd "echo hello && nvidia-smi" --ssh --direct
```

| Flag             | Meaning                                          |
| ---------------- | ------------------------------------------------ |
| `--image`        | Docker image to launch                           |
| `--disk 20`      | 20 GB of disk storage                            |
| `--onstart-cmd`  | Command to run when the instance boots           |
| `--ssh --direct` | Direct SSH access (lower latency than proxy SSH) |

The output includes the new instance ID:

```json theme={null}
{"success": true, "new_contract": 12345678}
```

Save the `new_contract` value, this is your instance ID.

<Note>
  Storage charges begin at creation. GPU charges begin when the instance reaches the `running` state.
</Note>

<Note>
  `--onstart-cmd` is limited to **16KB**. For longer scripts, gzip and base64 encode them, see the [Template Settings](/guides/templates/template-settings#on-start-script) page for the workaround.
</Note>

## 7. Wait Until Ready

The instance needs time to pull the Docker image and boot. Check the status with:

```bash theme={null}
vastai show instance INSTANCE_ID
```

The `status` field progresses through these states:

| Status    | Meaning                     |
| --------- | --------------------------- |
| `loading` | Docker image is downloading |
| `running` | Ready to use                |

Check every 10-30 seconds. Boot time is typically 1-5 minutes depending on the Docker image size.

<Warning>
  Always handle non-happy-path statuses in your poll loop. If `status` becomes `exited` (container crashed), `unknown` (no heartbeat from host), or `offline` (host disconnected), it will never reach `running`. Without a timeout or error check, your script will loop forever while the instance continues accruing disk charges. Destroy the instance and retry with a different offer if you see these states.
</Warning>

## 8. Connect via SSH

Once the instance is running, get the SSH connection details:

```bash theme={null}
vastai ssh-url INSTANCE_ID
```

Then connect:

```bash theme={null}
ssh root@SSH_HOST -p SSH_PORT
```

## 9. Copy Data

Use `vastai copy` to transfer files between your local machine and the instance:

```bash theme={null}
# Upload to instance
vastai copy local:./data/ INSTANCE_ID:/workspace/data/

# Download from instance
vastai copy INSTANCE_ID:/workspace/results/ local:./results/
```

You can also copy between instances or to/from cloud storage:

```bash theme={null}
# Instance to instance
vastai copy INSTANCE_A:/workspace/ INSTANCE_B:/workspace/

# Cloud storage (requires a configured cloud connection)
vastai copy s3.CONNECTION_ID:/bucket/data/ INSTANCE_ID:/workspace/
```

For cloud storage syncing and instance-to-instance transfers, see the [data movement guide](/guides/instances/storage/data-movement).

## 10. Clean Up

When you're done, destroy the instance to stop all billing.

Alternatively, to pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue.

**Destroy** (removes everything):

```bash theme={null}
vastai destroy instance INSTANCE_ID
```

**Stop** (pauses compute, disk charges continue):

```bash theme={null}
vastai stop instance INSTANCE_ID
```

## Next Steps

You've now completed the full instance lifecycle through the CLI: installation, authentication, search, creation, polling, data transfer, and teardown. From here:

* **SSH setup**, See the [SSH guide](/guides/instances/connect/ssh) for key configuration and advanced connection options.
* **Full command reference**, Every CLI command is documented under the Reference tab, grouped by domain ([Accounts](/cli/authentication), [Instances](/cli/reference/create-instance), [Search](/cli/reference/search-offers), [Serverless](/cli/reference/create-endpoint), and more).
* **Use templates**, Avoid repeating image and config parameters on every create call. See the [templates guide](/guides/templates/introduction) for creating and managing templates.