Metadata-Version: 2.4
Name: sshctl
Version: 0.2.20
Summary: Manage SSH hosts in SQLite and connect via ssh
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.7.0

# sshctl（重写版）

`sshctl` 是一个命令行小工具：用 **SQLite** 管理你的 SSH 服务器别名（`name`），并且不使用 `~/.ssh/config`。

适合新人/日常使用：
- 你不用记 IP、端口、用户名；主要用 **id** 选择（更直观）
- 支持“向导式输入”（`--wizard`）：跟着提示一步步填
- 支持“懒人连接”（`sshctl ssh` 不传参数）：先列出现有服务器，再让你输入要连哪个

---

## 0. 依赖（第一次使用前先装）

### 系统依赖（必须）

因为 SSH 密码自动登录需要 `sshpass`：

```bash
apt update
apt install -y sshpass
```

> 如果你不保存密码，也可以不用 sshpass（纯手动输密码/或用密钥）。

### Python 依赖

项目会通过 pip 自动安装：`rich`。

---

## 1. 快速开始（新人 3 分钟上手）

### 第一步：进入目录

你现在把源码放在：

```bash
cd /mnt/sshctl-rewrite
```

### 第二步：安装（生成 `sshctl` 命令）

推荐用虚拟环境（更干净，不污染系统 Python）：

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .
```

装完之后就应该能看到：

```bash
sshctl -h
```

> 如果你不想安装，也可以临时运行：
>
> ```bash
> python3 -m sshctl.cli -h
> ```
> 注意：Python 包目录名是 `sshctl/`。

---

## 2. 常用命令（照着抄就能用）

### 2.1 初始化数据库

默认数据库路径：`~/.local/share/sshctl/servers.db`

```bash
sshctl init
```

### 2.2 添加服务器（推荐用向导）

> 你可以选择是否保存登录密码：
> - 保存：会以**明文**写入数据库（list 里不会显示明文，但 DB 文件里是明文）
> - 不保存：连接时每次手动输入密码

最省事：

```bash
sshctl add --wizard
```

它会提示你依次输入：
- `name`（别名，唯一，比如 hk1、prod、test）
- `host`（IP 或域名）
- `port`（默认 22）
- `user`（默认 root，也常用 ubuntu）
- `identity_file`（私钥路径，可空，比如 `~/.ssh/id_rsa`）
- `password`（登录密码，可空；若填写会加密保存，不会明文显示）
- `note`（备注，可空）

你也可以参数式添加（适合熟练后）：

```bash
sshctl add --name hk1 --host 1.2.3.4 --user root --port 22 --identity-file ~/.ssh/id_rsa
```

### 2.3 查看已有服务器

```bash
sshctl list
```

### 2.4 搜索服务器（记不清 name 时用）

```bash
sshctl search hk
sshctl search 192.168
sshctl search ubuntu
```

### 2.5 连接服务器

推荐：用序号连接（更快，不用记 name）：

```bash
sshctl ssh 1
```

懒人模式（不传参数）：

```bash
sshctl ssh
```

它会：
1) 先列出数据库里的服务器（带 `id` 列）
2) 让你直接输入 `id` 连接
3) 如果你直接回车，它会退回到“手动输入 name”的方式（兜底）

你仍然可以用 name 连接（兼容/兜底）：

```bash
sshctl ssh hk1
```

---

## 3. 密码保存方式（重要）

如果你在 `add/edit` 或 `ssh` 时提供了 `password`，sshctl 会把密码以**明文**写入数据库字段 `password`（不安全）。

- `list` 不会显示明文，只会显示“已设置”。
- 连接时会用 `sshpass` 自动登录。

强烈建议：仅在你完全信任机器且不共享账号/不外传数据库的情况下使用。

---

## 4. 关于 ~/.ssh/config（说明）

按你的需求：**不使用 `~/.ssh/config`**。

- `sshctl` 连接时只会从数据库读取 `host/user/port/identity_file/password` 拼装 ssh 命令
- 如果保存了 password，会用 `sshpass` 自动登录；否则走手动输入

---

## 4. 修改 / 删除

修改（推荐用序号；也支持 name）：

```bash
sshctl edit 1 --wizard
# 或
sshctl edit hk1 --wizard
```

删除（推荐用 id；也支持 name）：

```bash
sshctl del 1
# 或
sshctl del hk1
```

> 注意：本工具会在删除后自动把 id 重新编号为 1..N。

---

## 5. 连接逻辑说明（新人必读）

- 如果该服务器记录保存了 `password`：
  - 会用 `sshpass` 自动把密码喂给 ssh（无需手动输入）
- 如果没有保存 `password`：
  - sshctl 会在连接前主动提示你输入一次密码
  - 默认会把该密码保存到数据库（下次自动登录）
  - 如果你不想保存，可加：

```bash
sshctl ssh <id> --no-save-password
```

> 说明：你在 ssh 自己弹出的 `root@x.x.x.x's password:` 里输入的内容，程序是拿不到的。
> 所以要实现“输入一次并保存”，必须由 sshctl 在连接前主动问你一次。

> 提醒：要能手动输密码，必须在真实终端里运行（有 TTY）。
> 如果你用脚本/CI 这种非交互方式运行，ssh 可能无法提示你输入密码。

---

## 6. 帮助（随时查）

总帮助：

```bash
sshctl -h
# 或
sshctl help
```

查看某个子命令怎么用：

```bash
sshctl help add
sshctl help ssh
sshctl help edit
```

---

## 6. 常见问题（新人容易卡的点）

### Q1：为什么我输入 `sshctl` 提示 command not found？

因为你还没安装。

在项目目录执行：

```bash
pip install -e .
```

或用虚拟环境安装（推荐）。

### Q2：数据库文件在哪？能换地方吗？

默认在：`~/.local/share/sshctl/servers.db`

也可以自定义：

```bash
sshctl --db /path/to/servers.db list
```

---

## 7. 目录结构（给开发者/以后扩展用）

- `sshctl/cli.py`：CLI 入口（生成命令 sshcli）
- `sshctl/db.py`：SQLite 连接与初始化表结构
- `sshctl/repo.py`：CRUD
- `sshctl/ssh.py`：连接逻辑（不读取 ~/.ssh/config）
- `sshctl/model.py`：数据模型

