# gitlink-cli

[![GitLink](https://img.shields.io/badge/GitLink-Gitlink%2Fgitlink--cli-green)](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
[![License](https://img.shields.io/badge/License-MulanPSL--2.0-blue.svg)](https://license.coscl.org.cn/MulanPSL2)
[![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org)
[![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli)

The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for developers and AI Agents. Supports **macOS, Linux, and Windows**. Covers repository management, issue tracking, pull requests, CI/CD, and AI-powered workflows, with **40+ commands** and **20+ AI Agent Skills**.

**[中文文档](./README.zh-CN.md)**

---

## Project Overview

This project delivers automation capabilities for the GitLink open-source collaboration platform across three sub-tasks.

### Sub-task 1: Extend and Enhance GitLink-CLI Capabilities (50%)

> Focus: CLI feature expansion | Difficulty: Medium-High | Tech Stack: Go

Build a robust, cross-platform, AI-friendly CLI tool covering the full GitLink platform.

**Core Architecture — Three-Layer Design:**

```
Shortcuts (40+ commands)
  → Clean commands for humans and AI Agents
  → issue +create, pr +list, wiki +create ...
      ↓
Raw API (Full endpoint coverage)
  → Direct GitLink OpenAPI calls
  → api GET /users/me, api POST /.../issues ...
      ↓
Config & Auth (Configuration layer)
  → Auth, context resolution, output formatting
  → auth login, config init, --format json
```

**CLI Feature Matrix:**

| Category | Capabilities |
|----------|-------------|
| Repo | List, create, fork, delete, view repo info |
| Issue | Create, update, close, comment, 6 batch operations (close/status/priority/assignee/label/create) |
| Wiki | View, create, update, delete Wiki pages |
| PR | Create, merge, review, view changed files |
| Branch | Create, delete, list, protect, unprotect |
| Release | Create, view, delete releases |
| Webhook | Create, view, update, delete, test webhooks |
| Org | Manage organizations, members, teams |
| CI | View builds, logs, CI/CD operations |
| Search | Search repositories, users |
| User | View user profiles |
| PM | Sprint management, kanban, weekly reports |
| Raw API | Call any GitLink OpenAPI endpoint directly |

**Key Highlights:**

- **Agent-Native Design** — Every command tested with real Agents: concise parameters, smart defaults, structured output
- **Cross-Platform** — macOS / Linux / Windows (x64/arm64), one-command install
- **Secure & Controllable** — OS-native keychain storage, `GITLINK_TOKEN` env var for CI/CD
- **Smart Context Resolution** — Auto-resolves owner/repo from `git remote origin`
- **Zero-Barrier Open Source** — MulanPSL-2.0, `npm install -g @gitlink-ai/cli` and go

### Sub-task 2: Develop and Enrich GitLink Skills (20%)

> Focus: Agent Skill Development | Difficulty: Medium | No Go required — Markdown + CLI calls

Skills are structured knowledge bases designed for Claude Code and other AI Agents. Each Skill includes `SKILL.md` (command reference), `REFERENCE.md` (API reference), `TROUBLESHOOTING.md` (troubleshooting), and `examples/` (complete workflow examples). AI Agents can operate GitLink by reading Skills with zero manual documentation lookup.

**Skills Directory Structure:**

```
skills/
├── gitlink-shared/           # Auth, global params, safety rules, branch conventions
├── gitlink-repo/             # Repository management
├── gitlink-issue/            # Issue management
├── gitlink-pr/               # Pull Request
├── gitlink-branch/           # Branch management
├── gitlink-release/          # Release management
├── gitlink-wiki/             # Wiki management
├── gitlink-webhook/          # Webhook management
├── gitlink-org/              # Organization management
├── gitlink-user/             # User management
├── gitlink-ci/               # CI/CD
├── gitlink-search/           # Search functionality
├── gitlink-pm/               # Project management (Sprints / Kanban / Weekly Reports)
├── gitlink-team/             # Team management
├── gitlink-changelog/        # Release Notes / Changelog generation
├── gitlink-health/           # Project health reports (issue response time, PR merge efficiency, contributor activity)
├── gitlink-contrib/          # Contributor reports (statistics & rankings)
├── gitlink-compliance/       # Security & compliance (license scanning, secret detection, PII scanning)
├── gitlink-issue-triage/     # Issue auto-classification (tracker/priority/labels)
├── gitlink-onboard/          # New contributor onboarding (Good First Issue identification & welcome comments)
├── gitlink-workflow/         # AI workflow orchestration (issue triage, PR review, release notes)
├── gitlink-code-review/      # Intelligent code review (four-dimension scoring, structured review comments)
├── gitlink-research/         # Research assistance (project insights, trend tracking, compliance & reproducibility, collaboration matching, citation generation)
└── gitlink-code-insight/     # Feature panorama (all Shortcuts cataloged with descriptions & examples)
```

**All Skills at a Glance:**

| Skill | Description | Typical Commands |
|-------|-------------|-----------------|
| **gitlink-shared** | Auth, global params, API reference, safety rules | `auth login`, `auth status` |
| **gitlink-repo** | Repository management | `repo +list`, `repo +create`, `repo +info`, `repo +fork` |
| **gitlink-issue** | Issue management | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` |
| **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +review` |
| **gitlink-branch** | Branch management | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` |
| **gitlink-release** | Release management | `release +list`, `release +create`, `release +view` |
| **gitlink-wiki** | Wiki management | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` |
| **gitlink-webhook** | Webhook management | `webhook +list`, `webhook +create`, `webhook +test` |
| **gitlink-org** | Organization management | `org +list`, `org +info`, `org +members` |
| **gitlink-user** | User management | `user +me`, `user +info` |
| **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` |
| **gitlink-search** | Search functionality | `search +repos`, `search +users` |
| **gitlink-pm** | Project management | Sprint mgmt, kanban, weekly reports (via Raw API) |
| **gitlink-team** | Team management | `team +list`, `team +create`, `team +add-member` |
| **gitlink-changelog** | Release Notes generation | Auto-collect commits/PRs/Issues, generate structured changelogs |
| **gitlink-health** | Project health reports | Issue response time, PR merge efficiency, contributor activity stats |
| **gitlink-contrib** | Contributor reports | `contrib +report` |
| **gitlink-compliance** | Security & compliance | `compliance +scan`, `compliance +secrets`, `compliance +license` |
| **gitlink-issue-triage** | Issue auto-classification | Auto-detect tracker/priority/labels, generate audit reports |
| **gitlink-onboard** | New contributor onboarding | `onboard +welcome` |
| **gitlink-workflow** | AI workflow orchestration | Issue triage, PR review, repo setup, sprint reports |
| **gitlink-code-review** | Intelligent code review | Four-dimension scoring (quality/security/performance/maintainability) with auto-published reviews |
| **gitlink-research** | Research assistance | Project insights, trend tracking, compliance & reproducibility, collaboration matching, citation generation |
| **gitlink-code-insight** | Feature panorama | Complete Shortcuts catalog with descriptions & examples |

**How AI Agents Use Skills:**

```
User: "Create an Issue on GitLink for me"
    ↓
AI Agent reads gitlink-issue/SKILL.md
    ↓
AI Agent executes: gitlink-cli issue +create -t "..." -b "..."
    ↓
Done!
```

AI Agents can automatically: create/manage Issues, create/merge PRs, publish Releases, manage Wiki, triage Issues, generate Release Notes, perform code reviews, and more.

### Sub-task 3: Build End-to-End Automation Workflows (20%)

> Focus: Compose existing capabilities to solve real problems | Difficulty: Low-Medium | No low-level coding required

Combine gitlink-cli commands and Skills into complete, reproducible automation scenarios. Workflows are orchestrated via Shell/PowerShell scripts and support AI Agent-driven execution.

---

**Five Automation Workflows at a Glance:**

| # | Scenario | Script | Steps | Problem Solved |
|---|----------|--------|-------|---------------|
| 1 | Community Ops Automation | `01-community-ops.sh` | 7 | Untriaged issue backlog, manual weekly reports, manual Release Notes |
| 2 | Code Quality Gatekeeper | `02-code-quality-gatekeeper.sh` | 7 | Low PR review efficiency, inconsistent quality standards, AI code review |
| 3 | One-Click Project Init | `03-project-init.sh` | 8 | Repetitive new project setup, manual README/License/CI/Issue/Milestone config |
| 4 | Multi-Repo Collaboration | `04-multi-repo-collab.sh` | 7 | Scattered cross-repo status, lack of unified dashboard |
| 5 | Contributor Growth System | `05-contributor-growth.sh` | 6 | Hard-to-track contributor activity, lack of incentive mechanisms |

---

### Scenario 1: Community Ops Automation

**Script**: `workflows/01-community-ops.sh`

**Workflow**:

```
issue +list → Fetch all open Issues
    ↓
Classify by keyword: Bug / Feature / Question / Docs
    ↓
issue +label-add → Auto-apply labels
    ↓
repo +members → Get repository member list
issue +update → Rotate assignment to members
    ↓
pr +list → Count PRs merged this week
issue +list → Count Issues closed this week
    ↓
wiki +create → Publish community weekly report to Wiki
    ↓
release +create → Auto-generate Release Notes
```

**Chained Commands**:

| Step | Command | Purpose |
|------|---------|---------|
| 1 | `issue +list` | Fetch all open Issues |
| 2 | `issue +label-add` | Apply labels by category (bug/feature/question/documentation) |
| 3 | `repo +members` | Fetch repository member list |
| 4 | `issue +update` | Assign owners to Bug/Feature Issues |
| 5 | `pr +list` | Count PRs merged this week |
| 6 | `wiki +create` | Publish community weekly report |
| 7 | `release +create` | Auto-generate Release Notes |

**Output Value**: Label-based filtering (repo Issues page filterable by label), clear ownership (every Issue has an assignee), Wiki weekly report (team & community can track weekly progress in Wiki), Release Notes (no manual changelog compilation at release time).

**How to Run**:

```bash
bash workflows/01-community-ops.sh --owner your-org --repo your-repo
bash workflows/01-community-ops.sh --owner zzx-coder --repo gitlink-cli
```

---

### Scenario 2: Code Quality Gatekeeper

**Script**: `workflows/02-code-quality-gatekeeper.sh`

**Workflow**:

```
pr +list → Fetch all open PRs
    ↓
pr +view → Read PR details
pr +files → Get changed file list
pr +diff → Get code diff
    ↓
Load gitlink-code-review Skill:
  - Review dimensions & check items
  - Scoring rubric (90-100 Excellent, 75-89 Good, ...)
  - Issue severity levels (CRITICAL/HIGH/MEDIUM/LOW)
    ↓
┌─────────────────────────────────────────┐
│  AI Code Review (Claude + Skill)        │
│  Four-Dimension Scoring (25 each, 100 total):│
│  - Code Quality: complexity, naming, comments│
│  - Security: SQL injection, XSS, secrets │
│  - Performance: loop efficiency, resource leaks, N+1│
│  - Maintainability: duplication, SRP, coupling │
│                                         │
│  Output:                                │
│  - Structured issue list (severity+file+│
│    rule+description+suggestion)          │
│  - Positive practices (positive_notes)  │
│  - Recommendations (recommendations)    │
│  - Total score + PASS/FAIL              │
└─────────────────────────────────────────┘
    ↓
api POST /reviews → Publish review comments on PR
    ↓
ci +builds → Check CI build status
    ↓
pr +merge → Score >= threshold AND CI passes → auto-merge
```

**Sample AI Review Output**:

```
Overall Score:        88 / 100
Code Quality:         23 / 25
Security:             25 / 25
Performance:          20 / 25
Maintainability:      20 / 25

Issues Found:
  - [LOW] quality: PR entries use (@author) format, commit entries use
    (author) without @ prefix — unify to (@author) format
  - [LOW] maintainability: Example contributor list updated but full
    changelog link still points to old repo

Positive Notes:
  + Change intent is clear, all modified files consistently follow the requirement
  + Change scope is reasonable — only docs and examples, no logic changes, minimal risk

Recommendations:
  > Unify author annotation format between PR and commit entries
  > Add fallback handling docs for empty author field in collect-data.md
```

**Chained Commands**:

| Step | Command | Purpose |
|------|---------|---------|
| 1 | `pr +list` | Fetch open PR list |
| 2 | `pr +view` | Read PR details (title, author, status) |
| 3 | `pr +files` | Get changed file list |
| 4 | `pr +diff` | Get code diff content |
| 5 | `gitlink-code-review` | Load Skill review dimensions, checks, scoring rubric |
| 6 | `claude -p` | AI performs four-dimension code review per Skill methodology |
| 7 | `api POST .../reviews` | Publish review comments to PR |
| 8 | `pr +merge` | Auto-merge when score >= threshold and CI passes |

**Output Value**: Structured scoring (every PR gets a 0-100 quality score, team can set a unified merge bar), AI issue checklist (auto-identifies security risks, perf issues, code quality problems), PR comments (review results posted directly on PR), auto-merge (high-quality PRs merged without manual clicks).

**How to Run**:

```bash
# Review all open PRs
bash workflows/02-code-quality-gatekeeper.sh --owner your-org --repo your-repo

# Review a specific PR
bash workflows/02-code-quality-gatekeeper.sh --owner your-org --repo your-repo --pr-id 42

# Custom quality threshold (default: 80)
bash workflows/02-code-quality-gatekeeper.sh --owner your-org --repo your-repo --threshold 70

# Dry-run mode (no actual merge)
bash workflows/02-code-quality-gatekeeper.sh --owner your-org --repo your-repo --dry-run

# Example
bash workflows/02-code-quality-gatekeeper.sh --owner zzx-coder --repo gitlink-cli --pr-id 20
```

---

### Scenario 3: One-Click Project Init

**Script**: `workflows/03-project-init.sh` / `03-project-init.ps1`

**Workflow**:

```
repo +create → Create repository
    ↓
git clone → Clone empty repo locally
    ↓
Generate files → README.md (language template) + LICENSE (MIT)
               + CONTRIBUTING.md + .gitlink-ci.yml
    ↓
git add/commit/push → Push scaffolding files to repo
    ↓
milestone +create × 3 → Create project milestones:
  - v0.1.0 - MVP
  - v0.2.0 - Feature Complete
  - v1.0.0 - Production Ready
    ↓
issue +create × 5 → Create initial task Issues (with labels):
  - Set up CI/CD pipeline
  - Write project documentation
  - Establish code review process
  - Add unit tests
  - Configure dependency management
    ↓
branch +protect → Protect master branch
    ↓
release +create → Create v0.1.0 initial release
```

**Chained Commands**:

| Step | Command | Purpose |
|------|---------|---------|
| 1 | `repo +create` | Create new repository |
| 2 | `git clone` | Clone empty repo to local temp directory |
| 3 | File generation | Generate README.md / LICENSE / CONTRIBUTING.md / .gitlink-ci.yml |
| 4 | `git add/commit/push` | Push scaffolding files to master |
| 5 | `milestone +create` | Create 3 project milestones (MVP → Production) |
| 6 | `issue +create` | Create 5 initial Issues with labels |
| 7 | `branch +protect` | Set master branch protection rules |
| 8 | `release +create` | Create v0.1.0 initial release |

**Output Value**: Turnkey setup (post-clone repo already has README, LICENSE, CI config — start developing immediately), real repo files (README/LICENSE/CONTRIBUTING/CI are actual files, not Wiki pages), milestone roadmap (MVP to Production path already established), standardized Issues (key tasks created, team can claim directly), branch protection (prevents direct push to master, enforces PR workflow), first Release (version management from day one).

**How to Run**:

```bash
# Go project
bash workflows/03-project-init.sh --owner your-org --name my-go-app --description "My Go app" --lang go

# Python project (private)
bash workflows/03-project-init.sh --owner your-org --name my-api --description "REST API service" --lang python --private

# Node.js project
bash workflows/03-project-init.sh --owner your-org --name my-web --description "Web frontend" --lang node

# Java project
bash workflows/03-project-init.sh --owner your-org --name my-service --description "Microservice" --lang java
```

---

### Scenario 4: Multi-Repo Collaboration

**Script**: `workflows/04-multi-repo-collab.sh` / `04-multi-repo-collab.ps1`

**Workflow**:

```
repo +list → List all repos in the organization
    ↓
For each repo:
  issue +list → Get open/closed Issue counts
  pr +list → Get open/merged PR counts
  release +list → Get latest release & date
    ↓
Compute health score (aligned with gitlink-health Skill · 100-point deduction model):
  Core metrics (75 pts): Issue resolution rate < 50% → -25, PR merge rate < 50% → -25, no recent activity → -25
  Auxiliary metrics (25 pts): Open Issues > 20 → -10, Open PRs > 10 → -10, no release > 30 days → -5
  Five-grade rating: Excellent (≥90) → Good (≥70) → Moderate (≥50) → Needs Attention (≥30) → Critical (<30)
    ↓
Generate HTML dashboard:
  - Overview cards: repo count, total open Issues, total open PRs, total activity
  - Detail table: per-repo Issue/PR/Release status + collapsible details
  - Health color bands: green=Excellent / blue=Good / yellow=Moderate / orange=Needs Attention / red=Critical
    ↓
(Optional) release +create → Create same-version Release across all repos
```

**Chained Commands**:

| Step | Command | Purpose |
|------|---------|---------|
| 1 | `repo +list` | List all repos in the organization |
| 2 | `issue +list` | Fetch Issue data per repo |
| 3 | `pr +list` | Fetch PR data per repo |
| 4 | `release +list` | Fetch latest release per repo |
| 5 | Generate HTML | Output visual dashboard |
| 6 | `release +create` | (Optional) Coordinated release |

**Output Value**: Unified view (one HTML page shows health status of all org repos), health alerts (Open Issues > 10 → orange, > 20 → red), coordinated releases (sync multiple related repos with one command), shareable (HTML file can be sent to team or deployed internally).

**How to Run**:

```bash
# Scan all org repos
bash workflows/04-multi-repo-collab.sh --org your-org

# Specific repos only
bash workflows/04-multi-repo-collab.sh --org your-org --repos "repo-a,repo-b,repo-c"

# Dashboard + coordinated release
bash workflows/04-multi-repo-collab.sh --org your-org --release v2.0.0

# Custom output file + detail limit
bash workflows/04-multi-repo-collab.sh --org your-org --output my-dashboard.html --detail-limit 10

# Dry-run mode
bash workflows/04-multi-repo-collab.sh --org your-org --dry-run

# Example
bash workflows/04-multi-repo-collab.sh --org zzx-coder
```

Generates `dashboard.html` in the current directory — open in browser to view.

---

### Scenario 5: Contributor Growth System

**Script**: `workflows/05-contributor-growth.sh`

**Workflow**:

```
contrib +report → Generate HTML contribution report with ECharts pie chart
    ↓
issue +list → Count Issue activity
pr +list → Count PR activity
api GET /contributors → Get commit counts & API stats
    ↓
Compute contribution score (AHP Weighted Model):
  - Code changes: 30% (normalized)
  - PRs merged: 25% (normalized)
  - Issues created/resolved: 15% (normalized)
  - Issue comments: 15% (normalized)
  - Team member: 15% (binary yes/no)
  → Weighted sum yields 0-100 composite score
    ↓
Assign badges:
  Champion                >= 80 pts
  Core Contributor        >= 60 pts
  Active Contributor      >= 40 pts
  Contributor             >= 20 pts
  Newcomer                < 20 pts
    ↓
(Optional) issue +create → Auto-create badge-award Issue
    ↓
wiki +create → Publish leaderboard to Wiki
```

**Chained Commands**:

| Step | Command | Purpose |
|------|---------|---------|
| 1 | `contrib +report` | Generate HTML contribution report (with ECharts) |
| 2 | `issue +list` | Count open/closed Issue activity |
| 3 | `pr +list` | Count open/merged PR activity |
| 4 | `api GET /contributors` | Get API-level contributor stats |
| 5 | `issue +create` | (Optional) Auto-award badges |
| 6 | `wiki +create` | Publish leaderboard to Wiki |

**Output Value**: HTML contribution report (visual contribution distribution for team meetings), contributor leaderboard (quantifies each person's contribution, publicly transparent), Wiki leaderboard (permanent record, contributors can check rankings anytime), badge incentives (Issue-based badge awards boost sense of achievement and belonging).

**How to Run**:

```bash
# Basic run
bash workflows/05-contributor-growth.sh --owner your-org --repo your-repo

# Custom time period (default: 30 days)
bash workflows/05-contributor-growth.sh --owner your-org --repo your-repo --period 90

# Enable auto badge awards
bash workflows/05-contributor-growth.sh --owner your-org --repo your-repo --award

# Example
bash workflows/05-contributor-growth.sh --owner zzx-coder --repo gitlink-cli --award
```

---

### Environment Setup

**1. Install gitlink-cli**

```bash
gitlink-cli version
# If not installed, build from project root
cd gitlink-cli && make build
```

**2. Install jq (scripts use jq to parse CLI JSON output)**

```bash
# Ubuntu/Debian
sudo apt-get install -y jq
# macOS
brew install jq
```

**3. Authenticate**

```bash
gitlink-cli auth login                              # Interactive login (recommended)
export GITLINK_TOKEN="your-private-token"           # Or env var
gitlink-cli auth status                              # Verify: should show "✓ Logged in"
```

**4. Verify Environment**

```bash
gitlink-cli issue +list --owner zzx-coder --repo gitlink-cli --state open --limit 3 --format json | jq '.ok'
# Should output: true
```

---

### Shared Library `lib/common.sh`

Infrastructure shared across all workflow scripts:

| Function | Purpose |
|----------|---------|
| `check_auth` | Check auth status (env var or CLI login) |
| `gl_run` | CLI wrapper, auto-appends `--format json` |
| `gl_check` | CLI wrapper + JSON validation + ok field check |
| `json_ok` / `json_get` / `json_error` | JSON parsing utilities |
| `detect_owner_repo` | Auto-detect owner/repo from git remote |
| `log_step` / `log_ok` / `log_warn` / `log_err` | Colorized log output |

---

### Workflow Common Parameters

| Parameter | Description |
|-----------|-------------|
| `--owner` | Repository owner (auto-resolved from git remote) |
| `--repo` | Repository name (auto-resolved from git remote) |
| `--org` | Organization name (needed for multi-repo scenarios) |
| `--dry-run` | Preview mode, no write operations executed |
| `--help` | Show help message |

---

### Skills Used by Workflows

| Skill | Used In | Role |
|-------|---------|------|
| `gitlink-code-review` | Scenario 2 | Review dimensions, check items, scoring rubric |
| `gitlink-issue-triage` | Scenario 1 | Issue classification rules (keyword matching, priority detection) |
| `gitlink-changelog` | Scenario 1 | Release Notes generation templates |
| `gitlink-health` | Scenario 4 | Project health scoring model (100-point deduction) |
| `gitlink-onboard` | Scenario 5 | New contributor onboarding & Issue recommendation rules |
| `gitlink-workflow` | All | Base workflow orchestration |

---

### Testing

```bash
# Run test suite (validates against real GitLink repos)
bash workflows/test.sh

# Specify a repo
bash workflows/test.sh zzx-coder gitlink-cli
```

Test coverage: auth status checks, CLI JSON output format validation, data field extraction (issue/PR/repo/release/member/contributor), PR files and diff content parsing, Issue/PR View interfaces, Wiki/Label list interfaces, `common.sh` utility functions, script syntax validation.

---

### Workflows Directory Structure

```
workflows/
├── lib/
│   └── common.sh                  # Shared utility library (auth, JSON parse, CLI wrap, logging)
├── 01-community-ops.sh            # Scenario 1: Community Ops Automation
├── 02-code-quality-gatekeeper.sh  # Scenario 2: Code Quality Gatekeeper (AI review)
├── 03-project-init.sh             # Scenario 3: One-Click Project Init
├── 04-multi-repo-collab.sh        # Scenario 4: Multi-Repo Collaboration
├── 05-contributor-growth.sh       # Scenario 5: Contributor Growth System
├── test.sh                        # Test suite
└── README.md                      # Detailed workflow documentation
```

---

## Installation & Quick Start

### Requirements

- Supported platforms: macOS, Linux, Windows (x64/arm64)
- Go 1.26+ — only needed for building from source

### Quick Start (For Users)

**One-command install (recommended):**

```bash
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash
```

**From npm:**

```bash
npm install -g @gitlink-ai/cli
```

The binary is auto-downloaded for your platform during `postinstall`. No extra steps.

**From source:**

```bash
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
cd gitlink-cli
make install
```

> Windows users: Run `npm install -g @gitlink-ai/cli` in PowerShell or CMD. For source builds use `go install .` instead of `make install`.

**Configure & Use:**

```bash
# 1. Configure (one-time)
gitlink-cli config init

# 2. Log in (choose one)
gitlink-cli auth login            # Username/password (recommended)
gitlink-cli auth login --token    # Or paste a private token
export GITLINK_TOKEN="your-token" # Or env var (for CI/CD)

# 3. Start using
gitlink-cli repo +list
```

### Quick Start (For AI Agents)

> The following steps are for AI Agents. Some steps require the user to complete actions in a browser.

```bash
# Step 1 — Install (one command: CLI + all Skills)
npm install -g @gitlink-ai/cli

# Step 2 — Configure
gitlink-cli config init

# Step 3 — Login
gitlink-cli auth login                              # Interactive environments
export GITLINK_TOKEN="your-private-token"           # Non-interactive (CI/CD, MCP, etc.)

# Step 4 — Verify
gitlink-cli user +me
```

### Uninstall

**Linux/macOS**: `bash uninstall.sh`
**Windows PowerShell**: `.\uninstall.ps1`
**npm**: `npm uninstall -g @gitlink-ai/cli`

---

## Usage Examples

### Repository Operations

```bash
gitlink-cli repo +list
gitlink-cli repo +info --owner Gitlink --repo forgeplus
gitlink-cli repo +create -n my-project -d "Project description"
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
```

### Issue Management

```bash
gitlink-cli issue +list --owner Gitlink --repo forgeplus
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" -b "Steps to reproduce..."
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,124 --dry-run
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed"
```

### Pull Requests

```bash
gitlink-cli pr +list --owner Gitlink --repo forgeplus
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: Search feature" --head feature/search --base master
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: New feature" --head your_username/forgeplus:feature/my-feature --base master
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
```

### Branch Management

```bash
gitlink-cli branch +list --owner Gitlink --repo forgeplus
gitlink-cli branch +create --name feature/new-feature
gitlink-cli branch +delete --name feature/old-feature
gitlink-cli branch +protect --name main
gitlink-cli branch +unprotect --name main
```

### Webhook Management

```bash
gitlink-cli webhook +list --owner Gitlink --repo forgeplus
gitlink-cli webhook +create --owner Gitlink --repo forgeplus --url https://ci.example.com/webhook --events push,pull_request
gitlink-cli webhook +create --url https://jenkins.example.com/webhook --secret my-secret-key --events push --description "CI/CD trigger"
gitlink-cli webhook +info --id 456
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook --events push,pull_request,issue
gitlink-cli webhook +test --id 456
gitlink-cli webhook +delete --id 456
gitlink-cli webhook +events
```

### Release Management

```bash
gitlink-cli release +list --owner Gitlink --repo forgeplus
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..."
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
```

### Wiki Management

```bash
gitlink-cli wiki +list --owner Gitlink --repo forgeplus
gitlink-cli wiki +view --owner Gitlink --repo forgeplus --title "Getting Started"
gitlink-cli wiki +create --title "New Page" --content "Page content"
gitlink-cli wiki +update --title "New Page" --cover "Updated content" --owner Gitlink --repo forgeplus
gitlink-cli wiki +update --title "New Page" --add "Appended content" --owner Gitlink --repo forgeplus
gitlink-cli wiki +delete --title "New Page" --owner Gitlink --repo forgeplus
```

### Search

```bash
gitlink-cli search +repos -k "machine learning"
gitlink-cli search +users -k "zhangsan"
```

### CI/CD

```bash
gitlink-cli ci +list --owner Gitlink --repo forgeplus
gitlink-cli ci +log --owner Gitlink --repo forgeplus -i <build_id>
gitlink-cli ci +restart --owner Gitlink --repo forgeplus -i <build_id>
```

### Raw API

For endpoints not covered by shortcuts, use the Raw API directly:

```bash
gitlink-cli api GET /users/me
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
```

---

## Global Parameters

| Parameter | Description | Example |
|-----------|-------------|---------|
| `--owner` | Repository owner | `--owner Gitlink` |
| `--repo` | Repository name | `--repo forgeplus` |
| `--format` | Output format (json/table/yaml) | `--format json` |
| `--debug` | Enable debug output | `--debug` |

**Automatic context resolution:** When running inside a git repository, `--owner` and `--repo` are automatically resolved from `git remote origin`.

---

## Branch Conventions

| Platform | Default Branch |
|----------|---------------|
| GitHub | `main` |
| GitLink | `master` |

Push to GitLink:

```bash
git push gitlink main:master
# Or configure git remote
git config remote.gitlink.push refs/heads/main:refs/heads/master
git push gitlink
```

---

## Project Structure

```
gitlink-cli/
├── cmd/                      # Cobra command definitions
│   ├── root.go               # Root command + global flags
│   ├── auth/                 # Authentication commands
│   ├── api/                  # Raw API commands
│   ├── config/               # Configuration commands
│   └── cmdutil/              # Global utilities
├── internal/                 # Internal packages
│   ├── auth/                 # Login, token storage, transport
│   ├── client/               # HTTP client + pagination
│   ├── config/               # Config file management
│   ├── context/              # Git remote resolution
│   └── output/               # Output envelope + formatter
├── shortcuts/                # Shortcut implementations
│   ├── common/               # Framework (types, runner)
│   ├── repo/ issue/ pr/ branch/ release/ org/ ci/ search/ user/ wiki/
│   └── register.go           # Registration entry point
├── skills/                   # AI Agent Skills
│   ├── README.md             # Skills detailed guide
│   ├── gitlink-shared/       # Shared rules
│   ├── gitlink-repo/ issue/ pr/ branch/ release/ ...
│   ├── gitlink-health/       # Project health
│   ├── gitlink-changelog/    # Release Notes
│   ├── gitlink-code-review/  # AI code review
│   ├── gitlink-research/     # Research assistance
│   └── ...
├── workflows/                # End-to-end automation workflows
│   ├── README.md             # Workflow documentation
│   ├── lib/common.sh         # Shared utility library
│   ├── 01-community-ops.sh   # Community Ops Automation
│   ├── 02-code-quality-gatekeeper.sh  # Code Quality Gatekeeper
│   ├── 03-project-init.sh    # One-Click Project Init
│   ├── 04-multi-repo-collab.sh  # Multi-Repo Collaboration
│   ├── 05-contributor-growth.sh  # Contributor Growth System
│   └── test.sh               # Test suite
├── doc/                      # Design documents
│   ├── design.md
│   ├── CODE_SYNC_STRATEGY_FINAL.md
│   └── ...
├── main.go
├── Makefile
├── go.mod
├── README.md
└── README.zh-CN.md
```

---

## Documentation Index

- [Skills Guide](skills/README.md) — Detailed AI Agent Skills documentation
- [Workflow Documentation](workflows/README.md) — Detailed workflow documentation
- [Design Document](doc/design.md) — Architecture design & development plan
- [Installation Guide](doc/INSTALL.md) — Detailed install steps
- [Uninstall Guide](doc/UNINSTALL.md) — Detailed uninstall steps
- [API Reference](skills/gitlink-shared/REFERENCE.md) — Complete API reference
- [Troubleshooting](skills/gitlink-shared/TROUBLESHOOTING.md) — Common issues & solutions

---

## FAQ

### Q: How do I use gitlink-cli in scripts?

Use the `GITLINK_TOKEN` env var + `--format json`:

```bash
export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list --format json | jq '.data.projects[] | .name'
```

### Q: How does automatic owner/repo resolution work?

When running inside a git repository, the CLI automatically resolves `--owner` and `--repo` from `git remote origin`:

```bash
cd ~/my-gitlink-project
gitlink-cli issue +list  # Automatically uses the current repository
```

### Q: What if my token expires?

```bash
gitlink-cli auth login            # Username/password login
gitlink-cli auth login --token    # Or use a private token
```

### Q: How do I use gitlink-cli in CI/CD or non-interactive environments?

Set the `GITLINK_TOKEN` environment variable — no `auth login` needed:

```bash
export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list   # Ready to use
```

Priority: `GITLINK_TOKEN` env var > keychain/file-stored token.

### Q: npm install succeeded but `gitlink-cli` reports a missing binary?

Reinstall first: `npm install -g @gitlink-ai/cli`. If the error persists, check the release page for your platform's asset, or download the binary manually / build from source with `go install .`.

### Q: Where are credentials stored on Windows?

gitlink-cli uses Windows Credential Manager for secure token storage. If Credential Manager is unavailable, it falls back to file storage (`~/.config/gitlink-cli/credentials`).

---

## Related Resources

- [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) — Bidirectional code sync system
- [Test Report](doc/SKILLS_TEST_REPORT_2026-04-02.md) — Skills functional test report
- [Code Sync Strategy](doc/CODE_SYNC_STRATEGY_FINAL.md) — GitHub ↔ GitLink sync design

---

## License

[MulanPSL-2.0](https://license.coscl.org.cn/MulanPSL2)
