# CLI Reference

The `clore` CLI lets you manage the Clore.ai GPU marketplace directly from your terminal — search for GPUs, deploy instances, SSH in, and manage orders without writing any code.

***

## Installation

```bash
pip install clore-ai
```

This installs both the Python SDK and the `clore` CLI command.

**Requirements:** Python 3.9+

***

## Configuration

### Set your API key

Get your key from the [Clore.ai dashboard](https://clore.ai) → **API** section, then configure:

```bash
clore config set api_key YOUR_API_KEY
```

This saves the key to `~/.clore/config.json`.

### Or use an environment variable

```bash
export CLORE_API_KEY=your_api_key_here
```

### View current config

```bash
# Show all config
clore config show

# Get a specific value
clore config get api_key
```

***

## Commands

| Command                               | Description                        |
| ------------------------------------- | ---------------------------------- |
| `clore search`                        | Search the GPU marketplace         |
| `clore deploy <server_id>`            | Create a new order (rent a server) |
| `clore orders`                        | List your orders                   |
| `clore cancel <order_id>`             | Cancel an order                    |
| `clore ssh <order_id>`                | SSH into an active order           |
| `clore wallets`                       | Show wallet balances               |
| `clore servers`                       | List your hosted servers           |
| `clore server-config <name>`          | Get server configuration           |
| `clore spot <server_id>`              | View spot market for a server      |
| `clore spot-price <order_id> <price>` | Set spot price                     |
| `clore config set <key> <value>`      | Set a config value                 |
| `clore config get <key>`              | Get a config value                 |
| `clore config show`                   | Show all configuration             |
| `clore --version`                     | Show version                       |

***

## Detailed Usage

### `clore search`

Search the GPU marketplace with filters and sorting.

```bash
# List all available servers (sorted by price, top 20)
clore search

# Filter by GPU model
clore search --gpu "RTX 4090"

# Filter by GPU and max price
clore search --gpu "RTX 4090" --max-price 5.0

# Multi-GPU rigs
clore search --min-gpu 4

# Sort by GPU count, show top 10
clore search --sort gpu --limit 10

# Combine filters
clore search --gpu "A100" --min-ram 128 --max-price 10.0 --sort price --limit 5
```

**Options:**

| Option        | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| `--gpu`       | text   | Filter by GPU model (e.g. `"RTX 4090"`)  |
| `--min-gpu`   | int    | Minimum GPU count                        |
| `--min-ram`   | float  | Minimum RAM in GB                        |
| `--max-price` | float  | Maximum price in USD/hour                |
| `--sort`      | choice | Sort by: `price` (default), `gpu`, `ram` |
| `--limit`     | int    | Max results to show (default: 20)        |

**Example output:**

```
🔍 GPU Marketplace
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ ID  ┃ GPU                             ┃ Count ┃ RAM (GB) ┃ CPU                          ┃ Price/h (USD) ┃ Location ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ 123 │ 1x NVIDIA GeForce RTX 4090      │     1 │    64.0  │ AMD Ryzen 9 5900X            │       $0.3200 │ US       │
│ 456 │ 2x NVIDIA GeForce RTX 4090      │     2 │   128.0  │ Intel Core i9-13900K         │       $0.5800 │ DE       │
└─────┴─────────────────────────────────┴───────┴──────────┴──────────────────────────────┴───────────────┴──────────┘
Showing 2 servers
```

***

### `clore deploy <server_id>`

Create a new order to rent a GPU server.

```bash
# On-demand order with SSH
clore deploy 123 \
  --image cloreai/ubuntu22.04-cuda12 \
  --type on-demand \
  --currency bitcoin \
  --ssh-password MySecurePass123 \
  --port 22:tcp \
  --port 8888:http

# Spot order
clore deploy 123 \
  --image cloreai/pytorch \
  --type spot \
  --currency bitcoin \
  --spot-price 0.000005 \
  --port 22:tcp

# With environment variables
clore deploy 123 \
  --image cloreai/ubuntu22.04-cuda12 \
  --type on-demand \
  --currency bitcoin \
  --ssh-password MyPass123 \
  --port 22:tcp \
  --env WANDB_API_KEY=your_key \
  --env HF_TOKEN=your_token
```

**Arguments:**

| Argument    | Description                                 |
| ----------- | ------------------------------------------- |
| `server_id` | Server ID to rent (get from `clore search`) |

**Options:**

| Option           | Type   | Required | Description                                            |
| ---------------- | ------ | -------- | ------------------------------------------------------ |
| `--image`        | text   | Yes      | Docker image (e.g. `cloreai/ubuntu22.04-cuda12`)       |
| `--type`         | choice | Yes      | `on-demand` or `spot`                                  |
| `--currency`     | text   | Yes      | Payment currency (e.g. `bitcoin`)                      |
| `--ssh-password` | text   | No       | SSH password (alphanumeric, max 32 chars)              |
| `--ssh-key`      | text   | No       | SSH public key                                         |
| `--port`         | text   | No       | Port mapping (repeatable), format: `PORT:PROTOCOL`     |
| `--env`          | text   | No       | Environment variable (repeatable), format: `KEY=VALUE` |
| `--spot-price`   | float  | No       | Spot price per day (required for spot orders)          |

***

### `clore orders`

List your active orders.

```bash
# Active orders
clore orders

# Include completed/expired orders
clore orders --completed
```

**Options:**

| Option        | Description                      |
| ------------- | -------------------------------- |
| `--completed` | Include completed/expired orders |

**Example output:**

```
📦 My Orders
┏━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Server ID ┃ Type      ┃ Status ┃ Image                             ┃ IP                      ┃
┡━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 38 │ 6         │ on-demand │ Active │ cloreai/ubuntu22.04-cuda12        │ n1.c1.clorecloud.net    │
└────┴───────────┴───────────┴────────┴───────────────────────────────────┴─────────────────────────┘
Total: 1 orders
```

***

### `clore cancel <order_id>`

Cancel an active order.

```bash
# Cancel order
clore cancel 38

# Cancel with issue report
clore cancel 38 --issue "GPU was overheating"
```

**Arguments:**

| Argument   | Description        |
| ---------- | ------------------ |
| `order_id` | Order ID to cancel |

**Options:**

| Option    | Description                        |
| --------- | ---------------------------------- |
| `--issue` | Cancellation reason / issue report |

***

### `clore ssh <order_id>`

Auto-connect via SSH to a running order. The CLI resolves the hostname and port from your order details.

```bash
# Connect as root (default)
clore ssh 38

# Connect as a different user
clore ssh 38 --user ubuntu
```

**Arguments:**

| Argument   | Description            |
| ---------- | ---------------------- |
| `order_id` | Order ID to connect to |

**Options:**

| Option   | Default | Description  |
| -------- | ------- | ------------ |
| `--user` | `root`  | SSH username |

***

### `clore wallets`

Show your wallet balances and deposit addresses.

```bash
clore wallets
```

**Example output:**

```
💰 Wallet Balances
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Currency         ┃ Balance      ┃ Deposit Address                           ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ bitcoin          │ 0.00153176   │ tb1q6erw7v02t7hakgmlcl4wfnlykzqj05alndruwr │
│ CLORE-Blockchain │ 150.00000000 │ cLr1q8x...                                │
└──────────────────┴──────────────┴───────────────────────────────────────────┘
```

***

### `clore servers`

List servers you are hosting on the marketplace.

```bash
clore servers
```

***

### `clore server-config <name>`

Get the configuration of a specific server you host.

```bash
clore server-config "MyGPU"
```

**Example output:**

```
Server: MyGPU
ID: 42
Connected: True
Online: True
Visibility: public
Min Rental Length: 72
GPUs: NVIDIA GeForce RTX 4090
On-Demand Price (USD): $0.35
Spot Price (USD): $0.18
CPU: AMD Ryzen 9 5900X 12-Core Processor
RAM: 64.0 GB
GPU: 1x NVIDIA GeForce RTX 4090
```

***

### `clore spot <server_id>`

View current spot market offers for a server.

```bash
clore spot 6
```

**Example output:**

```
📊 Spot Market - Server 6
┏━━━━━━━━━━┳━━━━━━━━━━━┓
┃ Order ID ┃ Price     ┃
┡━━━━━━━━━━╇━━━━━━━━━━━┩
│ 39       │ 4.2e-06   │
└──────────┴───────────┘
```

***

### `clore spot-price <order_id> <price>`

Update the price on your spot market offer.

```bash
clore spot-price 39 0.000003
```

> **Note:** You can only lower spot prices once every 600 seconds, and by a limited step size.

***

### `clore config`

Manage CLI configuration.

```bash
# Set API key
clore config set api_key YOUR_API_KEY

# Get a value
clore config get api_key

# Show all config
clore config show
```

Configuration is stored in `~/.clore/config.json`.

***

## Workflows

### Search → Rent → SSH → Cancel

A typical end-to-end workflow:

```bash
# 1. Find an RTX 4090 under $5/hour
clore search --gpu "RTX 4090" --max-price 5.0 --sort price --limit 5

# 2. Deploy on the cheapest server (e.g. ID 123)
clore deploy 123 \
  --image cloreai/ubuntu22.04-cuda12 \
  --type on-demand \
  --currency bitcoin \
  --ssh-password MyPass123 \
  --port 22:tcp \
  --port 8888:http

# 3. Check your order status
clore orders

# 4. SSH into the instance (e.g. order ID 456)
clore ssh 456

# 5. When done, cancel the order
clore cancel 456
```

### Monitor balances before renting

```bash
# Check you have enough funds
clore wallets

# Search and rent
clore search --gpu "A100" --sort price --limit 3
clore deploy 789 \
  --image cloreai/ubuntu22.04-cuda12 \
  --type on-demand \
  --currency bitcoin \
  --ssh-password SecurePass \
  --port 22:tcp
```

### Spot market workflow

```bash
# 1. Check spot offers for a server
clore spot 6

# 2. Create a spot order
clore deploy 6 \
  --image cloreai/pytorch \
  --type spot \
  --currency bitcoin \
  --spot-price 0.000005 \
  --ssh-password MyPass123 \
  --port 22:tcp

# 3. Adjust your spot price
clore spot-price 39 0.000003
```

### Server hosting management

```bash
# View your servers
clore servers

# Check a server's config
clore server-config "MyGPU"
```

***

## Next Steps

* [**Python SDK**](https://docs.clore.ai/developers/python-sdk) — Automate workflows with Python
* [**REST API**](https://docs.clore.ai/for-hosts/api) — Raw API documentation
* [**On-Demand vs Spot**](https://docs.clore.ai/for-renters/on-demand-vs-spot) — Understand pricing models