# gitee-cli

**Repository Path**: cc123hh/gitee-cli

## Basic Information

- **Project Name**: gitee-cli
- **Description**: Gitee 仓库管理命令行工具：零依赖 Python 脚本，支持仓库管理 / 建仓推送 / Issue 与 PR 查看
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-04
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">gitee</h1>

<p align="center">
  <img src="docs/banner.jpg" alt="gitee banner" width="760">
</p>

<p align="center">
  <img src="docs/badges/python.svg" alt="python 3.8+">
  <img src="docs/badges/platform.svg" alt="platform">
  <img src="docs/badges/deps.svg" alt="dependencies">
  <img src="docs/badges/tests.svg" alt="tests">
  <img src="docs/badges/license.svg" alt="license">
</p>

<p align="center">
  <b>在终端里把 Gitee 管起来：建仓、推送、看 Issue，一条命令。</b><br>
  零依赖 · 跨平台 · 单文件脚本 · 直接调 Gitee OpenAPI v5
</p>

---

## 📑 目录

- [快速开始](#-快速开始)
- [特性](#-特性)
- [安装](#-安装)
- [配置](#-配置)
- [命令一览](#-命令一览)
- [常见问题](#-常见问题)
- [License](#license)

## 🚀 快速开始

```console
$ gitee list
仓库                                             可见性    ★    更新
--------------------------------------------------------------------
cc123hh/imgen-cli                                公开      0   2026-11-04 13:15
cc123hh/emb-cli                                  公开      0   2026-11-04 12:40
cc123hh/private-notes                            私有      0   2026-11-03 21:08

$ gitee info emb-cli
仓库:   cc123hh/emb-cli
地址:   https://gitee.com/cc123hh/emb-cli
可见性: 公开
统计:   ★ 0  Fork 0  Watch 1
默认分支: main

$ cd ~/Scripts/new-tool && gitee push --public -d "我的新工具"
仓库不存在，正在创建 cc123hh/new-tool …
推送 main → https://gitee.com/cc123hh/new-tool.git …
已添加 remote origin
已设为公开
完成：https://gitee.com/cc123hh/new-tool
```

## ✨ 特性

| | |
|---|---|
| 🪶 **零依赖** | 只用 Python 标准库，拷到哪台机器都能跑 |
| 🖥️ **跨平台** | macOS / Linux / Windows，安装脚本全覆盖 |
| 📦 **仓库管理** | 列出、查看、创建、删除、公开/私有切换 |
| 🚀 **建仓推送一体** | `gitee push` 自动建仓 + 推送 + 设可见性 |
| 📋 **Issue / PR** | 命令行直接看列表与状态 |
| 🀄 **中文对齐** | 表格按中日韩字符显示宽度排版，不乱 |
| 🔒 **令牌不落库** | 只从 `GITEE_TOKEN` 读取 |

## 📥 安装

> 前提：Python 3.8+

### macOS / Linux

```bash
git clone https://gitee.com/cc123hh/gitee-cli.git
cd gitee-cli
./install.sh
```

### Windows

```powershell
git clone https://gitee.com/cc123hh/gitee-cli.git
cd gitee-cli
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

免安装直接用：`gitee.cmd list`

### 所有平台（pipx）

```bash
pipx install git+https://gitee.com/cc123hh/gitee-cli.git
```

## ⚙️ 配置

```bash
# 必需：私人令牌（https://gitee.com/profile/personal_access_tokens）
export GITEE_TOKEN="你的令牌"

# 可选
export GITEE_API="https://gitee.com/api/v5"
export GITEE_PROXY="http://127.0.0.1:7890"
```

Windows：`setx GITEE_TOKEN "你的令牌"`

> 令牌权限建议只勾：`projects`（仓库读写）、`pull_requests`、`issues`。

## 🧰 命令一览

### 账号

```bash
gitee whoami
```

### 仓库

```bash
gitee list                       # 我的仓库（按更新时间）
gitee list -n 50 --json          # 更多条数 / 原始 JSON
gitee info emb-cli               # 详情
gitee create my-tool -d "简介"    # 新建（默认私有）
gitee create my-tool --public    # 尝试公开（空仓库需推送后生效）
gitee public my-tool             # 设为公开
gitee private my-tool            # 设为私有
gitee delete my-tool -y          # 删除（-y 跳过确认）
```

### 一键建仓并推送

```bash
cd ~/Scripts/mytool
gitee push --public -d "我的小工具"
```

会自动：检查仓库是否存在 → 不存在则创建 → `git push` → 添加 `origin` → 需要时设为公开。

### Issue / Pull Request

```bash
gitee issues emb-cli             # 打开中的 Issue
gitee issues emb-cli -s all -n 50
gitee prs emb-cli
```

`repo` 参数写 `仓库名` 会自动补上你的用户名，也可以写完整的 `owner/repo`。

## 📋 参数

| 参数 | 适用命令 | 说明 |
|---|---|---|
| `-n/--limit` | list / issues / prs | 返回条数 |
| `--json` | list | 输出原始 JSON |
| `-s/--state` | issues / prs | `open` / `closed` / `all` |
| `-y/--yes` | delete | 跳过确认 |
| `-d/--description` | create / push | 仓库简介 |
| `--public` | create / push | 目标可见性 |
| `--name` | push | 仓库名（默认取目录名） |
| `--api/--proxy/--timeout` | 全部 | 覆盖环境变量 |

## ❓ 常见问题

<details>
<summary><b>提示鉴权失败（401/403）？</b></summary>

检查 `GITEE_TOKEN` 是否有效、是否勾选 `projects` 权限；令牌过期请重新生成。
</details>

<details>
<summary><b>创建时选了公开，结果还是私有？</b></summary>

Gitee 限制空仓库不能设为公开。推送首个提交后再执行 `gitee public 仓库名`；用 `gitee push --public` 会自动在推送后切换。
</details>

<details>
<summary><b>push 报「不是 git 仓库」？</b></summary>

`gitee push` 不会替你 `git init`，只负责建仓与推送。请先初始化并提交。
</details>

<details>
<summary><b>表格里中文对不齐？</b></summary>

已按 `unicodedata.east_asian_width` 计算显示宽度；若终端字体非等宽仍可能有偏差，属字体问题。
</details>

## 🤝 贡献

欢迎 Issue / PR。

## License

[MIT](LICENSE)