> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/compute/key-pairs.md).

# 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  |