io.github.danmartuszewski/hop

# Before: remembering and typing this every time
ssh -i ~/.ssh/work_key deploy@app-server-prod-03.us-east-1.example.com -p 2222

# After
hop prod

hop prod                         # fuzzy match any server
hop exec production "uptime"     # run command on all prod servers
hop import                       # import your existing ~/.ssh/config
hop                              # launch the TUI, manage everything

brew install danmartuszewski/tap/hop

go install github.com/danmartuszewski/hop/cmd/hop@latest

git clone https://github.com/danmartuszewski/hop.git && cd hop && make build
./bin/hop

Install hop on this machine and register its MCP server. Do the steps in order;
stop and report on the first failure.

1. Pick ONE install method, in this priority:
   a. Homebrew (macOS or Linux):
        brew install danmartuszewski/tap/hop
   b. Go 1.22+ available:
        go install github.com/danmartuszewski/hop/cmd/hop@latest
   c. From source (no brew, no Go on PATH):
        git clone https://github.com/danmartuszewski/hop.git && cd hop && make install

2. Verify the binary is on PATH:
        hop version

3. Register the MCP server with whichever agent the user is running. Skip
   clients the user does not use:
   - Claude Code:  claude mcp add hop -- hop mcp
   - Codex CLI:    codex mcp add hop -- hop mcp
   - Claude Desktop / Cursor / Windsurf — add to the client's MCP config:
        { "hop": { "command": "hop", "args": ["mcp"] } }

4. (Optional) Seed the config from the user's existing SSH config. Preview
   first; --yes is required for a non-interactive run:
        hop import --dry-run
        hop import --yes

5. Confirm hop's MCP tools are reachable from the agent (e.g. list_connections).

Constraints:
- Do NOT run bare `hop` — it launches an interactive TUI and will hang a
  non-interactive session. Use subcommands (`hop version`, `hop list`, …).
- Do NOT modify ~/.ssh/config. hop reads it via `hop import` only.
- Do NOT commit secrets or identity files.

After step 3, restart the agent so it picks up the new MCP server.

version: 1

defaults:
  user: admin
  port: 22
  # use_mosh: true             # Uncomment to use mosh for all connections

connections:
  - id: prod-web
    host: web.example.com
    user: deploy
    identity_file: ~/.ssh/work_key   # Private key for this connection
    remote_dir: /var/www/myapp       # Land in this directory on connect
    project: myapp
    env: production
    tags: [web, prod]

  - id: prod-db
    host: db.example.com
    user: dbadmin
    port: 5432
    project: myapp
    env: production
    tags: [database, prod]

  - id: staging
    host: staging.example.com
    user: deploy
    project: myapp
    env: staging

  - id: private-server
    host: 10.0.1.50
    user: admin
    proxy_jump: bastion          # Connect via jump host
    forward_agent: true          # Forward SSH agent

  - id: remote-dev
    host: dev.example.com
    user: dan
    use_mosh: true               # Use mosh instead of SSH

groups:
  production: [prod-web, prod-db]
  web-servers: [prod-web, staging]

defaults:
  use_mosh: true

connections:
  - id: remote-dev
    host: dev.example.com

  - id: legacy-server
    host: old.example.com
    use_mosh: false              # Override: use SSH for this one

connections:
  - id: remote-dev
    host: dev.example.com
    user: dan
    use_mosh: true

hop connect myserver --mosh
hop myserver --mosh

connections:
  - id: prod-web
    host: web.example.com
    user: deploy
    remote_dir: /var/www/myapp   # cd here on connect

  - id: my-dev
    host: dev.example.com
    remote_dir: ~/projects/api   # ~ is expanded on the remote host

hop <query>           # fuzzy match and connect
hop connect <id>      # connect by exact ID

user@host.com
user@host.com:2222
ssh user@host.com -p 2222
ssh://user@host:port

hop import                   # Import from ~/.ssh/config
hop import --dry-run         # Preview what would be imported
hop import --file ~/.ssh/config.d/work  # Import from custom path

hop export --all                          # Export all to stdout
hop export --all -o backup.yaml           # Export all to a file
hop export --project myapp -o myapp.yaml  # Export by project
hop export --tag database                 # Export by tag
hop export --env production               # Export by environment
hop export --id web-1,web-2              # Export specific connections

theme_preset: everforest-dark

theme_preset: everforest-dark   # optional; omit to auto-pick default
theme:                          # applies to every preset
  primary: "#0066cc"
theme_dark:                     # only applies when the preset is a dark variant
  selection: "#1f1f28"
theme_light:                    # only applies when the preset is a light variant
  foreground: "#1c1f24"

hop                          # Open TUI dashboard
hop <query>                  # Fuzzy match and connect
hop connect <id>             # Connect by exact ID
hop get <id> <field>         # Print single field value to stdout
hop get <id> f1,f2,f3        # Print multiple fields tab-separated
hop get <id>                 # Print all fields as "key value" lines
hop get --help               # Full field list and flags
hop list                     # List all connections
hop list --json              # List as JSON
hop list --flat              # Flat list without grouping
hop import                   # Import from ~/.ssh/config
hop import --file <path>     # Import from custom path
hop import --dry-run         # Preview without importing
hop export --all             # Export all connections to stdout
hop export --project <name>  # Export filtered connections
hop export --tag <tag> -o f  # Export to file
hop open <target...>         # Open multiple terminal tabs
hop exec <target> "cmd"      # Execute command on multiple servers
hop resolve <target>         # Test which connections a target matches
hop mcp                      # Start MCP server (read-only)
hop mcp --allow-exec         # Start MCP server with remote exec
hop version                  # Show version

hop resolve production              # see what "production" resolves to
hop resolve "web*"                  # test a glob pattern
hop resolve myapp-prod --tag=web    # combine target + tag filter

# Fuzzy connect
hop prod                # matches "prod-web", "prod-db", etc.
hop web                 # matches first *web* server

# Multi-exec with different target types
hop exec production "uptime"           # named group
hop exec myapp-prod "df -h"            # project-env pattern
hop exec "web*" "systemctl status"     # glob pattern
hop exec --tag=database "psql -c '\\l'" # tag filter

# Open multiple tabs
hop open production                    # named group
hop open web1 db1 api1                 # specific IDs
hop open myapp-prod -- "htop"          # with initial command

# List connections
hop list --flat

# Build an ssh invocation from config:
ssh -i "$(hop get prod identity_file)" "$(hop get prod user)@$(hop get prod host)"

# Read multiple fields at once (tab-separated):
IFS=$'\t' read -r host port user < <(hop get prod host,port,user)

# Fallback when a field is empty:
hop get prod port --default 22

# Strict shells: suppress the trailing newline.
hop get prod host -n

# Dump all non-empty scalar fields (ssh -G style "key value" lines):
hop get prod

# Read a single SSH option by key:
hop get prod options.StrictHostKeyChecking

# Structured output for jq and friends:
hop get prod host,port --json | jq -r .host

claude mcp add hop -- hop mcp

codex mcp add hop -- hop mcp

{
  "mcpServers": {
    "hop": {
      "command": "hop",
      "args": ["mcp"]
    }
  }
}

[mcp_servers.hop]
command = "hop"
args = ["mcp"]

hop mcp --print-client-config                  # read-only
hop mcp --print-client-config --allow-exec     # with remote exec enabled

claude mcp add hop -- hop mcp --allow-exec
codex mcp add hop -- hop mcp --allow-exec

# Bash (Linux)
hop completion bash | sudo tee /etc/bash_completion.d/hop > /dev/null

# Bash (macOS with Homebrew)
hop completion bash > $(brew --prefix)/etc/bash_completion.d/hop

# Zsh (add to ~/.zshrc)
source <(hop completion zsh)

# Fish
hop completion fish > ~/.config/fish/completions/hop.fish

-c, --config <path>    # Use custom config file
-v, --verbose          # Verbose output
-q, --quiet            # Suppress non-essential output
    --dry-run          # Print SSH command without executing
    --mosh             # Use mosh instead of SSH for this connection

make build          # Build binary to ./bin/hop
make test           # Run tests
make test-docker    # Run tests in Docker (isolated)
make install        # Install to $GOPATH/bin
make docker         # Build Docker image

# Build image
docker build -t hop .

# Run interactively
docker run -it --rm hop

# Run tests in container
docker build --target tester -t hop-test .

hop/
├── cmd/hop/           # Main entry point
├── internal/
│   ├── cmd/           # CLI commands (cobra)
│   ├── config/        # Configuration loading/saving
│   ├── export/        # Export logic
│   ├── fuzzy/         # Fuzzy matching
│   ├── mcp/           # MCP server (tools, resources, types)
│   ├── picker/        # Connection picker (promptui)
│   ├── resolve/       # Target resolution logic
│   ├── ssh/           # SSH connection handling
│   ├── sshconfig/     # SSH config parsing
│   └── tui/           # TUI dashboard (bubbletea)
├── Dockerfile
├── Makefile
└── README.md