# 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**](/developers/python-sdk.md) — Automate workflows with Python
* [**REST API**](/for-hosts/api.md) — Raw API documentation
* [**On-Demand vs Spot**](/for-renters/on-demand-vs-spot.md) — Understand pricing models


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/developers/cli-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.