# CLI papers

> Đăng nhập bằng mã thiết bị, đẩy phiên bản từ thư mục LaTeX, xem trạng thái và báo cáo kiểm từ terminal bằng CLI papers.

`papers` là công cụ dòng lệnh mỏng cho nghiên cứu viên: đăng nhập một lần bằng mã thiết bị, rồi đẩy phiên bản và đọc báo cáo kiểm ngay từ thư mục LaTeX trên máy. Đây là đường chính khi bạn viết bài trên máy riêng.

## Cài đặt

CLI nằm trong repo của ứng dụng, cần Node 22 trở lên:

```sh
pnpm --filter @papers/shared build
pnpm --filter @papers/cli build
alias papers='node /duong/dan/repo/packages/cli/bin/papers.js'
papers --help
```

| Biến môi trường | Mặc định | Ý nghĩa |
| --- | --- | --- |
| `PAPERS_API_URL` | `https://papers-inseclab.khoi.pro` | Máy chủ; `papers login` lưu lại và các lệnh sau dùng lại |
| `PAPERS_CONFIG_DIR` | `~/.config/papers` | Nơi lưu `credentials.json` (thư mục 700, tệp 600) |

## Đăng nhập: `papers login`

```text
$ papers login
Mở https://papers-inseclab.khoi.pro/device và nhập mã: K7QM-2XPD
```

1. Mở trang `/device` trên trình duyệt đã đăng nhập (phiên phải đã qua **2FA**).
2. Nhập mã 8 ký tự (không phân biệt hoa/thường), bấm **Kiểm tra mã**.
3. Trang hiện IP, thiết bị, quyền và hạn của token; bấm **Cho phép** nếu đúng là bạn vừa chạy lệnh.

![Trang Duyệt thiết bị đăng nhập](../../../assets/shots/device.webp)

Mã hết hạn sau 10 phút. Token cấp cho CLI sống **90 ngày**, quyền `works:read works:write checks:read`; hết hạn thì `papers login` lại.

## Đẩy phiên bản: `papers push`

```sh
papers push ISL-2026-0001 --pdf paper.pdf                    # zip thư mục chứa paper.pdf
papers push ISL-2026-0001 --pdf paper.pdf --src ./latex      # zip thư mục khác
papers push ISL-2026-0001 --pdf paper.pdf --zip source.zip   # dùng zip có sẵn
papers push ISL-2026-0001 --pdf paper.pdf --kind revision --label R1 \
  --review reviews/R1.pdf --decision decision.pdf --response response.pdf
```

- `--pdf` bắt buộc. `--src` (thư mục) hoặc `--zip` (tệp có sẵn) là nguồn LaTeX; không có thì CLI zip thư mục chứa PDF.
- `--kind`: `submission` (mặc định), `revision`, `camera_ready`, `published`, `preprint`, `other`. `--label` là nhãn tự do.
- Bản sửa kèm được review, thư quyết định, thư phản hồi (`--review`, `--decision`, `--response`).
- Mỗi lần đẩy tạo **phiên bản mới**; công trình chưa có lần nộp thì CLI tạo lần nộp nháp trên venue edition mặc định.
- Kiểm tra tự chạy khi phiên bản có PDF + zip; CLI in mã phiên bản và đường dẫn mở trên web.

Zip do CLI tạo **bỏ** tệp build (`*.aux *.log *.out *.toc *.synctex(.gz) *.fls *.fdb_latexmk *.blg *.bcf *.run.xml *.nav *.snm *.vrb *.xdv *.dvi`), `.git/`, `.svn/`, `__pycache__/`, `.DS_Store`, `Thumbs.db`, `*~`, `*.zip`; **giữ** `.bbl`, `.bib` và mọi hình. Giới hạn: 2 000 tệp, 64 MB mỗi tệp, 200 MB tổng, sâu 8 cấp, zip đến 100 MB; symlink bị bỏ qua.

## Xem trạng thái và báo cáo

```sh
papers status ISL-2026-0001             # các phiên bản: nhãn, loại, số trang, thời điểm, mã phiên bản
papers report <version-id>              # 10 kiểm tra; mục chưa chạy hiện "chưa chạy"
papers report <version-id> --check similarity
papers report <version-id> --json       # dùng trong script hoặc agent
```

Mọi lệnh nhận `--json`. Mã thoát: `0` thành công, `1` lỗi nghiệp vụ hoặc mạng, `2` dùng lệnh sai.

## Đăng xuất và thu hồi token

`papers logout` thu hồi token trên máy chủ rồi xoá credential trên máy. Mất máy mà không chạy được lệnh này thì gọi `GET /api/v1/tokens` (bằng phiên đăng nhập web) để lấy `id` rồi `DELETE /api/v1/tokens/{id}`, hoặc nhờ trưởng phòng thu hồi hộ. Token của tài khoản bị khoá hoặc bị xoá khỏi lab bị từ chối ngay.