@howdoi-cli/ssh 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 howdoi-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# @howdoi-cli/ssh
+
+**howdoi knowledge base — ssh commands.**
+
+Part of the [howdoi](https://github.com/SiphoChris/howdoi-cli) ecosystem.
+
+## Install
+
+```bash
+npm install -g @howdoi-cli/ssh
+```
+
+This also installs `@howdoi-cli/core` (the engine and `howdoi` binary) automatically.
+
+## Usage
+
+```bash
+howdoi <what you want to do>
+```
+
+## Install more knowledge bases
+
+```bash
+npm install -g @howdoi-cli/unix
+npm install -g @howdoi-cli/git
+npm install -g @howdoi-cli/ssh
+npm install -g @howdoi-cli/docker
+npm install -g @howdoi-cli/networking
+npm install -g @howdoi-cli/all
+```
+
+## License
+
+MIT

package/data/ssh/ssh-agent.yaml

@@ -0,0 +1,46 @@
+tool: ssh-agent
+category: ssh
+description: Manage the SSH authentication agent
+package: "@howdoi-cli/ssh"
+intents:
+  - add ssh key to agent
+  - ssh agent not found
+  - ssh-add key
+  - load ssh key
+  - start ssh agent
+  - fix ssh agent not running
+  - ssh agent forwarding
+  - list loaded ssh keys
+  - remove key from agent
+  - clear all keys from agent
+  - fix permission denied publickey
+  - ssh key not being used
+examples:
+  - intent: start ssh agent
+    title: Start the SSH agent in current shell
+    command: eval "$(ssh-agent -s)"
+  - intent: add ssh key to agent
+    title: Add your default SSH key to the agent
+    command: ssh-add ~/.ssh/id_rsa
+  - intent: add ssh key to agent
+    title: Add an Ed25519 key (recommended key type)
+    command: ssh-add ~/.ssh/id_ed25519
+  - intent: add ssh key to agent
+    title: Add key and save passphrase to macOS keychain
+    command: ssh-add --apple-use-keychain ~/.ssh/id_ed25519
+    os: macos-only
+  - intent: list loaded ssh keys
+    title: List all keys currently loaded in the agent
+    command: ssh-add -l
+  - intent: remove key from agent
+    title: Remove a specific key from the agent
+    command: ssh-add -d ~/.ssh/id_ed25519
+  - intent: clear all keys from agent
+    title: Remove all keys from the agent
+    command: ssh-add -D
+  - intent: fix ssh agent not running
+    title: Fix "Could not open a connection to your authentication agent"
+    command: eval "$(ssh-agent -s)" && ssh-add ~/.ssh/id_ed25519
+  - intent: ssh agent forwarding
+    title: Connect with agent forwarding enabled
+    command: ssh -A user@host

package/data/ssh/ssh-config.yaml

@@ -0,0 +1,53 @@
+tool: ssh config
+category: ssh
+description: Manage SSH client configuration file (~/.ssh/config)
+package: "@howdoi-cli/ssh"
+intents:
+  - configure ssh alias
+  - create ssh shortcut
+  - set default ssh key for host
+  - edit ssh config
+  - add host to ssh config
+  - set ssh config for github
+  - use different key per host
+  - view ssh config
+examples:
+  - intent: edit ssh config
+    title: Open the SSH config file for editing
+    command: nano ~/.ssh/config
+  - intent: view ssh config
+    title: View the SSH config file
+    command: cat ~/.ssh/config
+  - intent: configure ssh alias
+    title: Example host entry with alias (add to ~/.ssh/config)
+    command: |
+      Host myserver
+        HostName 192.168.1.100
+        User ubuntu
+        IdentityFile ~/.ssh/id_ed25519
+        Port 22
+  - intent: set ssh config for github
+    title: GitHub-specific SSH config entry
+    command: |
+      Host github.com
+        HostName github.com
+        User git
+        IdentityFile ~/.ssh/id_ed25519
+  - intent: use different key per host
+    title: Use a different key for work vs personal GitHub
+    command: |
+      Host github-work
+        HostName github.com
+        User git
+        IdentityFile ~/.ssh/id_work
+
+      Host github-personal
+        HostName github.com
+        User git
+        IdentityFile ~/.ssh/id_personal
+  - intent: keep ssh connection alive
+    title: Global keep-alive setting in config
+    command: |
+      Host *
+        ServerAliveInterval 60
+        ServerAliveCountMax 3

package/data/ssh/ssh-keygen.yaml

@@ -0,0 +1,49 @@
+tool: ssh-keygen
+category: ssh
+description: Generate and manage SSH key pairs
+package: "@howdoi-cli/ssh"
+intents:
+  - generate ssh key
+  - create ssh key pair
+  - make new ssh key
+  - generate ed25519 key
+  - generate rsa key
+  - create ssh key for github
+  - add passphrase to ssh key
+  - change ssh key passphrase
+  - view ssh public key
+  - copy ssh public key
+  - check ssh key fingerprint
+  - remove host from known hosts
+  - fix host key verification failed
+examples:
+  - intent: generate ssh key
+    title: Generate a new Ed25519 key (recommended)
+    command: ssh-keygen -t ed25519 -C "your@email.com"
+  - intent: generate rsa key
+    title: Generate a 4096-bit RSA key
+    command: ssh-keygen -t rsa -b 4096 -C "your@email.com"
+  - intent: generate ssh key
+    title: Generate key with a specific filename
+    command: ssh-keygen -t ed25519 -f ~/.ssh/my_key -C "work laptop"
+  - intent: view ssh public key
+    title: Print your public key (to copy to GitHub, servers etc.)
+    command: cat ~/.ssh/id_ed25519.pub
+  - intent: check ssh key fingerprint
+    title: Show the fingerprint of a key
+    command: ssh-keygen -lf ~/.ssh/id_ed25519
+  - intent: change ssh key passphrase
+    title: Change the passphrase on an existing key
+    command: ssh-keygen -p -f ~/.ssh/id_ed25519
+  - intent: remove host from known hosts
+    title: Remove a host from known_hosts (fix host key errors)
+    command: ssh-keygen -R hostname
+  - intent: fix host key verification failed
+    title: Remove stale host key and reconnect
+    command: ssh-keygen -R hostname && ssh user@hostname
+  - intent: copy ssh public key
+    title: Copy public key to a remote server
+    command: ssh-copy-id user@hostname
+  - intent: copy ssh public key
+    title: Copy a specific public key to a remote server
+    command: ssh-copy-id -i ~/.ssh/id_ed25519.pub user@hostname

package/data/ssh/ssh.yaml

@@ -0,0 +1,50 @@
+tool: ssh
+category: ssh
+description: Connect to remote servers securely
+package: "@howdoi-cli/ssh"
+intents:
+  - connect to remote server
+  - ssh into server
+  - login to remote machine
+  - connect with specific key
+  - connect on different port
+  - run command on remote server
+  - ssh tunnel
+  - port forward over ssh
+  - local port forwarding
+  - remote port forwarding
+  - copy file over ssh
+  - keep ssh connection alive
+  - connect with verbose output
+  - debug ssh connection
+examples:
+  - intent: connect to remote server
+    title: Basic SSH connection
+    command: ssh user@hostname
+  - intent: connect with specific key
+    title: Connect using a specific identity file
+    command: ssh -i ~/.ssh/id_ed25519 user@hostname
+  - intent: connect on different port
+    title: Connect to a non-standard port
+    command: ssh -p 2222 user@hostname
+  - intent: run command on remote server
+    title: Run a single command on a remote server
+    command: ssh user@hostname "ls -la /var/log"
+  - intent: local port forwarding
+    title: Forward local port 8080 to remote port 80
+    command: ssh -L 8080:localhost:80 user@hostname
+  - intent: remote port forwarding
+    title: Expose local port 3000 on the remote server
+    command: ssh -R 9090:localhost:3000 user@hostname
+  - intent: ssh tunnel
+    title: Create a SOCKS proxy tunnel
+    command: ssh -D 1080 user@hostname
+  - intent: keep ssh connection alive
+    title: Keep connection alive with heartbeat
+    command: ssh -o ServerAliveInterval=60 user@hostname
+  - intent: connect with verbose output
+    title: Debug connection issues with verbose output
+    command: ssh -v user@hostname
+  - intent: connect to remote server
+    title: Connect and jump through a bastion host
+    command: ssh -J bastion-user@bastion user@target

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@howdoi-cli/ssh",
+  "version": "1.0.0",
+  "description": "SSH knowledge base for howdoi — keys, agent, config, tunnels, and more.",
+  "type": "module",
+  "files": [
+    "data",
+    "postinstall.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.mjs",
+    "publish:npm": "npm publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "howdoi": {
+    "type": "knowledge-base",
+    "dataDir": "data"
+  },
+  "dependencies": {
+    "@howdoi-cli/core": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["cli", "ssh", "terminal", "howdoi"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SiphoChris/howdoi-cli"
+  }
+}

package/postinstall.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync, existsSync, readFileSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { homedir } from "os";
+
+// process.argv[1] is always the path of the running script — reliable across
+// all package managers and working directories
+const scriptDir = dirname(resolve(process.argv[1]));
+const pkgJsonPath = join(scriptDir, "package.json");
+
+if (!existsSync(pkgJsonPath)) {
+  process.exit(0);
+}
+
+const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+const pkgName = pkgJson.name.replace("@howdoi-cli/", "");
+
+// Skip in monorepo dev context — check for workspace root two levels up
+const monoRootPkg = resolve(scriptDir, "..", "..", "package.json");
+if (existsSync(monoRootPkg)) {
+  try {
+    const root = JSON.parse(readFileSync(monoRootPkg, "utf-8"));
+    if (root.workspaces) {
+      console.log(`[howdoi] Dev mode — skipping XDG install for ${pkgJson.name}`);
+      process.exit(0);
+    }
+  } catch { /* continue */ }
+}
+
+const srcData = join(scriptDir, "data");
+if (!existsSync(srcData)) {
+  process.exit(0);
+}
+
+const xdgBase = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+const dest = join(xdgBase, "howdoi", pkgName);
+
+try {
+  mkdirSync(dest, { recursive: true });
+  cpSync(srcData, dest, { recursive: true });
+  console.log(`[howdoi] ✓ ${pkgJson.name}@${pkgJson.version} → ${dest}`);
+} catch (err) {
+  console.warn(`[howdoi] Warning: could not copy data: ${err.message}`);
+  console.warn(`[howdoi] howdoi will still work via node_modules fallback.`);
+}