Documentation

Everything you need to install, configure, and use Forged.

Installation

Forged is a single binary with no dependencies.

macOS

brew install forged

Linux / macOS (script)

curl -fsSL https://forged.ritik.me/install.sh | sh

From source

git clone https://github.com/itzzritik/forged
cd forged
just build-cli
./bin/forged setup

Setup

Run the setup wizard. It creates an encrypted vault, imports your existing SSH keys, installs the daemon as a system service, and configures ~/.ssh/config.

forged setup

You will be asked to create a master password. This encrypts your vault locally. It is never sent to any server.

After setup, the daemon starts automatically and runs in the background. It auto-starts on login via launchd (macOS) or systemd (Linux).

Usage

Once the daemon is running, SSH and Git work automatically. Forged serves keys over the standard SSH agent protocol.

ssh myserver                     # right key, automatically
git push origin main             # commits signed, automatically

Any SSH client that supports SSH_AUTH_SOCK works with Forged. You can verify with ssh-add -l.

Key Management

forged generate my-key -c "me@host"    # new Ed25519 key
forged add work --file ~/.ssh/id_ed25519  # import existing
forged list                               # show all keys
forged list --json                        # machine-readable
forged export my-key                      # public key to stdout
forged rename my-key github               # rename
forged remove old-key                     # delete

To import keys from 1Password or your existing SSH agent:

forged migrate --from ssh          # import from ~/.ssh/
forged migrate --from 1password    # import from 1Password CLI
forged migrate --from agent        # list keys in current agent

Host Matching

Map keys to hosts so the right key is always offered first. Supports exact hostnames, wildcards, IP ranges, and regex.

forged host github "github.com" "*.github.com"
forged host deploy "*.prod.company.com" "10.0.*"
forged hosts                       # list all mappings
forged unhost deploy "10.0.*"      # remove a mapping

You can also configure host rules in ~/.forged/config.toml:

config.toml

[[hosts]]
name = "GitHub"
match = ["github.com", "*.github.com"]
key = "github"
git_signing = true

[[hosts]]
name = "Production"
match = ["*.prod.company.com", "10.0.*"]
key = "deploy"

Git Signing

Forged can sign your Git commits with SSH keys. Run forged setup and say yes to Git signing, or configure manually:

~/.gitconfig

[user]
    signingkey = ssh-ed25519 AAAA...
[gpg]
    format = ssh
[gpg "ssh"]
    program = /usr/local/bin/forged-sign
[commit]
    gpgsign = true

Cloud Sync

Sync your encrypted vault across machines. The server stores only opaque blobs it cannot decrypt.

forged login                # opens browser for OAuth
forged sync                 # push/pull vault
forged sync status          # check sync state
forged logout               # clear credentials

On a new machine, install Forged, run forged login and forged sync, then enter your master password to decrypt the vault. All keys are available.

Configuration

Configuration file location:

macOS: ~/.forged/config.toml
Linux: ~/.config/forged/config.toml

config.toml

[agent]
socket = "~/.forged/agent.sock"
log_level = "info"

[sync]
enabled = false

Use forged config to open the config file in your editor, or forged config get / forged config set to manage individual values.

All Commands

forged setup                     first-time wizard
forged start / stop              manage daemon service
forged status                    daemon info + key count
forged doctor                    diagnose common issues

forged generate <name>           new Ed25519 key pair
forged add <name> --file <path>  import existing key
forged list                      all keys in vault
forged remove <name>             delete a key
forged export <name>             public key to stdout
forged rename <old> <new>        rename a key

forged host <key> <patterns>     map key to hosts
forged hosts                     list all mappings
forged unhost <key> <pattern>    remove a mapping

forged login                     authenticate with cloud
forged sync                      push/pull encrypted vault
forged sync status               check sync state
forged logout                    clear credentials

forged lock / unlock             clear or restore keys
forged change-password           change master password
forged migrate --from <source>   import from ssh/1password/agent
forged benchmark                 test Argon2id speed
forged logs                      tail daemon logs
forged config                    manage configuration

All commands support --json for machine-readable output.