# gitee-cli

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

## Basic Information

- **Project Name**: gitee-cli
- **Description**: Repository-focused CLI built from the official Gitee OpenAPI v5 spec.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitee-cli

`gitee-cli` is a repository-focused command line wrapper built from the official Gitee OpenAPI v5 spec.

It exposes repository-related operations as CLI commands, including:

- repository CRUD
- branches, tags, contents, releases
- repo activity such as stargazers and subscribers
- repo issues, pull requests, labels, milestones
- repo webhooks, git data, checks
- user/org/enterprise repo listings
- repository search

It also provides shorter aliases for common tasks:

- `auth status`
- `auth login`
- `auth clear`
- `repo get`
- `repo subscribers`
- `repo url`
- `repo clone`

## Install locally

```powershell
npm link
```

That makes `gitee-cli` available in your shell.

## Access token

Read from environment variables, in this order:

1. `GITEE_ACCESS_TOKEN`
2. `GITEE_TOKEN`
3. `ACCESS_TOKEN`

Optional for HTTPS clone:

- `GITEE_USERNAME`

You can also override auth for a single command:

- `--auth-token <token>`
- `--auth-username <login>`

PowerShell example:

```powershell
$env:GITEE_ACCESS_TOKEN = "your-token"
```

Persistent user env example:

```powershell
setx GITEE_ACCESS_TOKEN "your-token"
```

## Auth commands

Check current auth state:

```powershell
gitee-cli auth status
```

Validate a token and print shell commands for the current session:

```powershell
gitee-cli auth login --token <token>
```

Persist auth on Windows:

```powershell
gitee-cli auth login --token <token> --persist
```

Clear auth:

```powershell
gitee-cli auth clear
```

Tip: `--token` / `--auth-token` is convenient, but it can end up in shell history. Environment variables are safer for regular use.

## Inspect commands

```powershell
gitee-cli list
gitee-cli list subscribers
gitee-cli show get-v5-repos-owner-repo-subscribers
gitee-cli auth help
gitee-cli repo help
```

## Examples

Friendly aliases:

```powershell
gitee-cli repo get oschina/git-osc
gitee-cli repo subscribers oschina/git-osc --page 1 --per-page 5
gitee-cli repo url oschina/git-osc --ssh
gitee-cli repo clone oschina/git-osc
gitee-cli repo clone oschina/git-osc git-osc-local --branch master --depth 1 --https
gitee-cli repo clone oschina/git-osc --auth-token <token>
```

`repo clone` uses HTTPS automatically when `GITEE_ACCESS_TOKEN` is set. Otherwise it falls back to SSH. You can always force a protocol with `--https` or `--ssh`.

If you use HTTPS clone with a token, the CLI will try to resolve your Gitee login from `/api/v5/user`. If you prefer to skip that lookup, set `GITEE_USERNAME` yourself.

Raw OpenAPI-style commands:

```powershell
gitee-cli get-v5-user-repos --auth-token <token>
gitee-cli get-v5-repos-owner-repo --owner oschina --repo git-osc
gitee-cli get-v5-repos-owner-repo-subscribers --owner oschina --repo git-osc
```

Get repo detail:

```powershell
gitee-cli get-v5-repos-owner-repo --owner oschina --repo git-osc
```

List repo subscribers:

```powershell
gitee-cli get-v5-repos-owner-repo-subscribers --owner oschina --repo git-osc
```

List current user repos:

```powershell
gitee-cli get-v5-user-repos --visibility all
```

Create a personal repo:

```powershell
gitee-cli post-v5-user-repos --name demo --private false --has-issues true --has-wiki true
```

Use a JSON request body:

```powershell
gitee-cli post-v5-repos-owner-repo-commits --owner foo --repo bar --body-file .\commit-body.json
```

Pass complex form keys:

```powershell
gitee-cli post-v5-repos-owner-repo-check-runs `
  --owner foo `
  --repo bar `
  --param "output[title]=CI result" `
  --param "output[summary]=Everything passed"
```

Save binary output:

```powershell
gitee-cli get-v5-repos-owner-repo-zipball --owner oschina --repo git-osc --output .\git-osc.zip
```

## Notes from local verification

- `get-v5-repos-owner-repo` and `get-v5-repos-owner-repo-subscribers` work anonymously against public repos.
- `get-v5-search-repositories` currently returned an empty array in local anonymous tests for simple keywords like `git-osc`.
- `get-v5-repos-owner-repo-zipball` returned `401 Unauthorized` in local anonymous tests, so download-style endpoints may need a token even for public repos.
- `git clone https://gitee.com/...` prompted for credentials in local tests, so token-backed HTTPS clone or SSH is the safer default for automation.

## Update the OpenAPI spec

```powershell
npm run update:spec
```