# SSH Key Pairs

Key pairs are SSH public/private key pairs used for secure access to instances. You can either generate a new key pair (AceCloud creates both keys and returns the private key once) or import an existing public key.

**Command:** `ace key-pair`

**Aliases:** `ace keypair`, `ace kp`

***

## Table of Contents

* [List Key Pairs](#list-key-pairs)
* [Get Key Pair Details](#get-key-pair-details)
* [Create a Key Pair](#create-a-key-pair)
  * [Generate a New Key Pair](#generate-a-new-key-pair)
  * [Import an Existing Public Key](#import-an-existing-public-key)
* [Delete Key Pairs](#delete-key-pairs)

***

## List Key Pairs

List all SSH key pairs in the current project.

```bash
ace key-pair list
```

**Aliases:** `ls`

### Example Output

```
NAME                           TYPE     FINGERPRINT
deploy-key                     ssh      ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90
my-laptop                      ssh      12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
```

```bash
# JSON output
ace key-pair list -o json
```

***

## Get Key Pair Details

Get details of a specific key pair by name.

```bash
ace key-pair get <key-name>
```

**Aliases:** `show`

### Example

```bash
ace key-pair get deploy-key
```

### Detail Output

```
Name:              deploy-key
Type:              ssh
Fingerprint:       ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90
Public Key:        ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC7...
```

```bash
# JSON output
ace key-pair get deploy-key -o json
```

***

## Create a Key Pair

There are two modes for creating a key pair:

### Generate a New Key Pair

Omit `--public-key` to have AceCloud generate a new SSH key pair. The private key is returned **once** and cannot be retrieved again.

```bash
ace key-pair create --name deploy-key
```

**Output:**

```
Key pair created.
  Name:            deploy-key
  Fingerprint:     ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78:90

Private Key (save this — it will not be shown again):
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----
```

**Save the private key immediately.** It is displayed only once at creation time. If you lose it, you must delete the key pair and create a new one.

Save the private key to a file and set proper permissions:

```bash
# Save the output, then:
chmod 600 ~/.ssh/deploy-key.pem
```

### Import an Existing Public Key

Provide your own public key with the `--public-key` flag. No private key is returned because you already have it.

```bash
ace key-pair create --name my-laptop --public-key "ssh-rsa AAAAB3NzaC1yc2EAAA... user@host"
```

```bash
# Or read from a file
ace key-pair create --name my-laptop --public-key "$(cat ~/.ssh/id_rsa.pub)"
```

**Output:**

```
Key pair created.
  Name:            my-laptop
  Fingerprint:     12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef
```

### Flags

| Flag           | Required | Description                                                           |
| -------------- | -------- | --------------------------------------------------------------------- |
| `--name`       | Yes      | Key pair name (must be unique within project)                         |
| `--public-key` | No       | SSH public key string (≥100 characters). Omit to generate a new pair. |

> **Note** — Imported public keys must be at least **100 characters long**. A standard `ssh-keygen -t ed25519` or `ssh-keygen -t rsa -b 4096` output easily exceeds this; truncated or invalid keys are rejected with a clear error.

***

## Delete Key Pairs

Delete one or more key pairs by name.

```bash
# Delete a single key pair
ace key-pair delete <key-name>

# Delete multiple key pairs
ace key-pair delete <key-1> <key-2> <key-3>
```

**Aliases:** `rm`

### Examples

```bash
ace key-pair delete old-key
ace key-pair delete staging-key production-key
```

```
Deleted 1 key pair(s).
```

Deleting a key pair does not affect instances that were launched with it. Those instances will continue to accept the corresponding private key for SSH access.

***

## Using Key Pairs with Instances

Reference a key pair by name when creating an instance:

```bash
ace instance create \
  --name my-vm \
  --flavor C4i.medium \
  --image Ubuntu-22.04-LTS \
  --network <vpc-id> \
  --security-group <sg-id> \
  --key deploy-key
```

Then SSH into the instance using the corresponding private key:

```bash
ssh -i ~/.ssh/deploy-key.pem ubuntu@<instance-ip>
```

The default SSH username depends on the image:

| Image          | Default User             |
| -------------- | ------------------------ |
| Ubuntu         | `ubuntu`                 |
| CentOS / Rocky | `centos` or `cloud-user` |
| Debian         | `debian`                 |
| Windows        | Use console or RDP       |

***

## Command Reference

| Command                                                | Description                   |
| ------------------------------------------------------ | ----------------------------- |
| `ace key-pair list`                                    | List all key pairs            |
| `ace key-pair get <name>`                              | Get key pair details          |
| `ace key-pair create --name <name>`                    | Generate a new key pair       |
| `ace key-pair create --name <name> --public-key <key>` | Import an existing public key |
| `ace key-pair delete <name> [name...]`                 | Delete one or more key pairs  |


---

# 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.acecloud.ai/knowledge-base/cli/compute/key-pairs.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.