server-cli-tools/README.md

# Server CLI Tools

Interactive installer for setting up a consistent shell environment on Ubuntu/Debian servers. Clone to any server, run the installer, pick what you need.

## Quick start

```sh
git clone <repo-url> ~/server_cli_tools
cd ~/server_cli_tools
./install.sh              # interactive menu
./install.sh --all        # install everything
./install.sh --update     # pull latest + re-run menu
./install.sh --uninstall  # remove installed configs
```

## What's included

| # | Component | What it does |
|---|-----------|-------------|
| 1 | **Core packages** | `vim`, `bat`, `eza`, `fzf`, `htop`, `tmux`, `zsh`, `ripgrep`, `fd-find`, `zoxide`, `git-delta` |
| 2 | **Zsh + Oh-My-Zsh** | Shell, plugins (`zsh-autosuggestions`, `zsh-syntax-highlighting`, `z`), custom prompt theme |
| 3 | **Aliases + tools** | General, git, and docker aliases with a self-documenting help system (`h`) |
| 4 | **Terminal configs** | `bat` theme (base16) |
| 5 | **Docker** | `docker.io` via apt, service enabled, user added to `docker` group, management aliases |
| 6 | **Git config** | `git-delta` as pager with side-by-side diffs |

## Alias highlights

Type `h` after installation to see all aliases with descriptions. Some highlights:

```
ll    — eza with icons, groups, timestamps
pf    — fzf + bat file preview
cdf   — fuzzy cd into any subdirectory
mkcd  — mkdir + cd in one command
twd   — tar current directory
gdn   — numbered git diff (then gdn 3 to diff file #3)
gcpm  — git add -u + commit + push in one command
gstm  — git stash with mandatory message
ds    — toggle docker container start/stop
da    — docker ps -a
```

## How it works

- **Idempotent** — safe to run multiple times; skips already-installed packages
- **Non-destructive** — existing configs are backed up to `~/.server_cli_tools_bkp/<timestamp>/`
- **Selective** — interactive menu lets you toggle individual components
- **Ubuntu/Debian** — uses `apt`; warns on other distros (configs still work)

## Repo structure

```
server_cli_tools/
  install.sh                    # main installer
  configs/
    aliases/
      .aliases                  # general aliases (server-adapted)
      .functions.sh             # helper functions + alias help system
      .git_aliases              # git shortcuts + stash management
      .docker_aliases           # docker management aliases
      .git_bash_autocomplete    # bash git completion
    custom_tools/
      backup_dotfiles.sh        # backup conflicting dotfiles
    bat/config                  # bat theme
    zsh/zhann-elvis.zsh-theme   # custom zsh prompt (git-aware)
    zshrc                       # .zshrc with oh-my-zsh + plugins
```

## Customization

After installation, create local overrides that won't be tracked:

- `~/.config/aliases/.local_aliases` — machine-specific aliases
- `~/.config/aliases/.custom_aliases` — temporary/personal aliases

Use `ea l` to edit local aliases, `ea c` for custom, `sa` to re-source.

## Troubleshooting

### Terminal type / colors over SSH

Clients such as [Ghostty](https://ghostty.org/) set `TERM` to values like `xterm-ghostty`. SSH forwards that to the server, but the server usually has no matching terminfo entry. Symptoms include:

- `'xterm-ghostty': unknown terminal type` when running `./install.sh` (the interactive menu calls `clear`)
- Broken or missing colors in `vim`, `htop`, `tmux`, and other TUI programs

`install.sh` detects an unknown `TERM` at startup and falls back to the first available of `xterm-256color`, `xterm`, `screen`, or `dumb`. You can also use the non-interactive installer: `./install.sh --all`.

For **all future SSH sessions** to any server, force a portable `TERM` on the client before connecting. Add a wrapper on your **local** machine (not the server). The function body is the same in bash and zsh; what differs is where you put it and how you check that it took effect.

**Bash** (`~/.bashrc`) — append at the end of the file:

```bash
unalias ssh 2>/dev/null
ssh() {
  TERM=xterm-256color command ssh "$@"
}
```

**Zsh** (`~/.zshrc`) — append at the end, *after* Oh-My-Zsh and other plugins so nothing loads later and overrides it:

```zsh
unalias ssh 2>/dev/null
ssh() {
  TERM=xterm-256color command ssh "$@"
}
```

Zsh also allows `function ssh { ... }` with the same body; `ssh() { ... }` is equivalent. In both shells, `command ssh` calls the real binary and avoids recursion.

| | Bash | Zsh |
|---|------|-----|
| Config file | `~/.bashrc` | `~/.zshrc` |
| Placement | End of file | End of file, after OMZ/plugins |
| Clear alias first | `unalias ssh` (if present) | Same — plugins sometimes define `ssh` aliases |
| Argument forwarding | `"$@"` | `"$@"` — not `"@"` |
| Reload | `exec bash` or new terminal | `exec zsh` or new terminal |
| Check wrapper is active | `type ssh` | `whence -v ssh` (`type` can be ambiguous in zsh) |

Verify:

```sh
# bash
type ssh
ssh myhost 'echo $TERM'

# zsh
whence -v ssh
ssh myhost 'echo $TERM'
```

Both should report a shell function and print `xterm-256color` on the remote host.

One-off:

```sh
TERM=xterm-256color ./install.sh
```

Optional: in `~/.ssh/config`, `SetEnv TERM=xterm-256color` under `Host *` only works when the remote `sshd` accepts `TERM` via `AcceptEnv` — many servers do not, so the shell wrapper above is more reliable.