Quick Start

This guide covers the essential lifecycle of using SKM. By the end of this tutorial, you will have initialized the SKM vault, safeguarded your existing SSH keys, created a new key profile, and learned how to switch between them securely.

Step 1: Initialize the SKM Key Store

Before SKM can manage anything, it needs to establish its local storage vault. By default, SKM creates a hidden directory at ~/.skm.

Run the initialization command:

skm init

What happens under the hood?

This is a critical step, and SKM handles your existing data carefully:

  1. SKM creates the ~/.skm directory.
  2. Migration: It scans your existing ~/.ssh directory for supported key pairs (like id_rsa/id_rsa.pub or id_ed25519/id_ed25519.pub).
  3. If it finds existing keys, it creates a new profile named default at ~/.skm/default/.
  4. It securely moves your existing keys into this default profile vault.
  5. Finally, it creates symlinks in ~/.ssh pointing back to the files in ~/.skm/default/.

Result: Your SSH client will continue to work exactly as it did before, but now SKM is managing the backend storage.

Step 2: Create a New SSH Key

Let's assume you need a separate identity for a client project. We will create a new key and assign it the alias client-project.

Use the create command, specifying the alias. It is highly recommended to provide a comment (usually an email address) using the -C flag.

skm create client-project -C "[email protected]" -t ed25519

Note: We used -t ed25519 to generate a modern, highly secure ED25519 key. If omitted, SKM defaults to standard RSA.

You will be prompted by the underlying ssh-keygen binary to enter a passphrase. Once complete, SKM saves this brand-new key pair directly into ~/.skm/client-project/.

Step 3: View Your Managed Keys

To see a clear overview of all the SSH keys SKM is currently tracking, use the ls (list) command:

skm ls

Example Output: 

✔ Found 2 SSH key(s)!

->      default         [rsa]           [[email protected]]
        client-project  [ed25519]       [[email protected]]

  • The Arrow (->): Indicates the currently active key.
  • Key Type: Displays the algorithm used (e.g., rsa, ed25519).
  • Comment: Displays the comment attached to the public key, helping you remember its purpose.

Step 4: Switch the Active Identity

When it is time to start working on the client's codebase, you need to swap your system's active SSH identity.

Use the use command followed by your desired alias:

skm use client-project

Example Output: 

Now using SSH key: [client-project]

The Interactive Menu (Pro-Tip)

If you forget your alias names, simply type skm use and press Enter. SKM will launch a beautiful, interactive CLI prompt powered by promptui. You can use your up/down arrow keys to select the profile you want to activate.

What happens during a switch?

  1. SKM deletes the old symlinks from your ~/.ssh directory.
  2. It generates new symlinks pointing to ~/.skm/client-project/id_ed25519 and id_ed25519.pub.
  3. (Optional) If you have configured a Hook script for client-project, SKM executes it now (see Configuration & Hooks to learn how to update Git configs automatically).

Congratulations! You now understand the core SKM workflow. For deep dives into specific commands like deploying keys to remote servers or backing them up, proceed to the Key Management and Backup & Restore sections.