Metadata-Version: 2.4
Name: ys-baserow-cli
Version: 0.4.0
Summary: Baserow API 客户端与命令行工具
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0

# baserow-cli

Baserow API 客户端与命令行工具。

## 安装

推荐用 [pipx](https://pypa.github.io/pipx/) 全局安装 CLI 工具——它会为每个工具建独立虚拟环境，但命令暴露到 `$PATH`，不污染项目依赖。

```bash
# 首次：装 pipx（macOS / Debian / 自举三选一）
brew install pipx          # macOS
apt install pipx           # Debian/Ubuntu
pipx ensurepath            # 把 ~/.local/bin 加到 PATH

# 装包：baserow 命令可用
pipx install ys-baserow-cli

# 试用不装：跑最新版的命令
pipx run --spec ys-baserow-cli baserow --help

# 升级
pipx upgrade ys-baserow-cli
```

需要 Python 3.8+。

### 从源码开发

```bash
git clone <repo>
cd baserow-cli
pipx install -e .          # 可编辑装到全局
# 或者
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
python -m unittest tests.test_e2e -v
```

## 配置

创建 `~/.config/baserow-cli/.env`：

```bash
mkdir -p ~/.config/baserow-cli
cat > ~/.config/baserow-cli/.env <<EOF
endpoint=http://your-baserow:7890
email=user@example.com
password=yourpassword
EOF
chmod 600 ~/.config/baserow-cli/.env
```

字段说明：

| 字段 | 说明 |
|------|------|
| `endpoint` | Baserow 地址，含 `http(s)://` 和端口 |
| `email` | 登录邮箱 |
| `password` | 登录密码 |

## 命令

| 命令 | 说明 |
|------|------|
| `baserow whoami` | 当前用户信息 |
| `baserow databases` | 列出所有数据库 |
| `baserow tables --database-id N` | 列出数据库的表 |
| `baserow fields --table-id N` | 列出表的字段 |
| `baserow rows --table-id N` | 列出表行 (分页) |
| `baserow get-row --table-id N --row-id M` | 获取单行 |
| `baserow create-row --table-id N --fields '{...}'` | 创建行 |
| `baserow update-row --table-id N --row-id M --fields '{...}'` | 更新行 |
| `baserow delete-row --table-id N --row-id M` | 删除行 |
| `baserow batch-create-rows --table-id N --items '[{...},{...}]'` | 批量创建行（最多 200 行/次） |
| `baserow batch-delete-rows --table-id N --row-ids '[1,2,3]'` | 批量删除行 |
| `baserow get-database --id N` | 单个 database 详情 |
| `baserow create-database --workspace-id N --name X` | 创建 database |
| `baserow delete-database --id N` | 删除整个 database（危险） |
| `baserow get-table --id N` | 单个 table 详情 |
| `baserow update-table --table-id N --name X` | 改表名 |
| `baserow get-field --id N` | 单个字段详情 |
| `baserow update-field --field-id N --fields '{"name":"x"}'` | 改字段（fields 为 JSON 字典） |
| `baserow get-token --id N` | 单个 token 详情 |
| `baserow create-token --workspace-id N --name X` | 创建 API token |
| `baserow delete-token --id N` | 删除 token |
| `baserow refresh-token` | 主动刷新 JWT |
| `baserow create-table --database-id N --name X` | 创建表 |
| `baserow delete-table --table-id N` | 删除表 |
| `baserow create-field --table-id N --name X --type text` | 创建字段 |
| `baserow delete-field --field-id N` | 删除字段 |
| `baserow tokens` | 列出 API tokens |
| `baserow json METHOD /path [body]` | 原始 API 请求 |

## 参数覆盖

```bash
baserow --endpoint http://... --email ... --password ... databases
baserow --env-file /path/to/.env tables --database-id 289
```

## 输出约定

所有子命令对脚本友好：

- **stdout**: 永远是合法 JSON。
  - 数据查询命令（`databases` / `tables` / `fields` / `rows` / `tokens` / `get-*`）输出原始数据（数组或对象）。
  - `whoami` 输出 `{user_id, endpoint, email, token_expires_at}`。
  - 变更命令（`create-*` / `update-*` / `delete-*` / `batch-*` / `refresh-token`）输出 `{status: "ok", ...}` 信封，关键字段（`id` / `count` / `deleted_id` / `name` / `key`）平铺在顶层。
  - `create-token` 会同时输出新生成的 `key`（**仅此一次**）。
- **stderr**: 人类可读的日志、确认提示、错误消息。
- **退出码**: `0` = 成功或用户主动取消，`1` = API/网络/认证错误，`2` = 非交互式拒绝执行破坏性操作或缺凭证。

```bash
# 直接 pipe 给 jq
baserow databases | jq '.[].name'
baserow rows --table-id 906 | jq '.results[].name'

# 脚本里取 id
db_id=$(baserow create-database --workspace-id 182 --name "demo" | jq -r '.id')

# 自动化跑破坏性操作需要 --yes
baserow --yes delete-row --table-id 906 --row-id 1

# 错误捕获
if ! baserow get-row --table-id 906 --row-id 999 2>err.json; then
  jq -r '.error.detail' err.json   # stderr 是合法 JSON
fi
```

破坏性操作（`delete-*` / `batch-delete-rows`）在交互式终端会提示确认；在脚本环境（stdin 非 tty）必须加 `--yes`，否则拒绝执行并以退出码 `2` 报错。

## Python 客户端

```python
from baserow_api.client import BaserowClient

client = BaserowClient(
    endpoint="https://xxx:xxx",
    email="user@example.com",
    password="secret",
)

# 列出数据库
ok, dbs = client.list_databases()

# 列出表
ok, tables = client.list_tables(database_id=289)

# CRUD 行
ok, row = client.create_row(table_id=906, fields={"名字": "test"})
ok, row = client.update_row(table_id=906, row_id=1, fields={"名字": "updated"})
ok, _ = client.delete_row(table_id=906, row_id=1)
```


## API 参考
https://api.baserow.io/api/redoc/
