gitlink-cli

The official GitLink CLI tool — built for humans 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 12 AI Agent Skills.

中文文档

Install · AI Agent Skills · Auth · Commands · Contributing

Why gitlink-cli?

• Agent-Native Design — 12 structured Skills out of the box, compatible with Claude Code, OpenClaw, and other AI platforms — Agents can operate GitLink with zero extra setup
• Wide Coverage — Repository, Issue, PR, Branch, Release, CI, Org, Search, User — all core domains covered
• AI-Friendly & Optimized — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output
• Cross-Platform — Runs on macOS, Linux, and Windows (x64/arm64), install via npm install -g @gitlink-ai/cli in one command, binary auto-downloaded
• Open Source, Zero Barriers — MulanPSL-2.0 license, ready to use, just npm install
• Up and Running in 3 Minutes — Interactive login or GITLINK_TOKEN env var, from install to first API call in just 3 steps
• Secure & Controllable — OS-native keychain credential storage, GITLINK_TOKEN env var for CI/CD & non-interactive environments, auto git remote context resolution
• Three-Layer Architecture — Shortcuts (human & AI friendly) → Raw API (full coverage) → Config (configuration management)

Features

Category	Capabilities
📦 Repo	List, create, fork, delete repositories, view repo info
🐛 Issue	Create, update, close, comment on issues, 6 batch operations (close/status/priority/assignee/label/create), metadata queries, comment management
📖 Wiki	View, create, update, delete Wiki pages
🔀 PR	Create, merge, review pull requests, reopen, update, view commits/versions/diffs, comment management
📁 File	Browse directories, read files, create/update/delete files, batch commit, view commit history and diffs
🏁 Milestone	List, create, view, update, delete milestones, change status
🌿 Branch	Create, delete, list, protect, unprotect branches
🏷️ Release	Create, view, delete releases
🔗 Webhook	Create, view, update, delete, test webhooks, configure automation triggers
🏢 Org	Manage organizations, members, teams
🔧 CI	View builds, logs, CI/CD operations
🔍 Search	Search repositories, users
👤 User	View user profiles and info
📋 Board	View kanban board, filter issues by status/assignee/priority, move tasks, assign people, workload analytics
📋 PM	Sprint management, kanban boards, weekly reports
🤖 Workflow	AI-powered issue triage, PR review, release notes

Installation & Quick Start

Requirements

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

Quick Start (Human Users)

Note for AI assistants: If you are an AI Agent helping the user with installation, jump directly to Quick Start (AI Agent), which contains all the steps you need to complete.

Install

一键安装（推荐） — 无需 npm、无需 Go:

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

From npm:

npm install -g @gitlink-ai/cli

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

From source:

Requires Go 1.26+.

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 building from source, use go install . instead of make install.

Configure & Use

# 1. Configure (one-time, interactive guided setup)
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 set env var (for CI/CD, non-interactive environments)

# 3. Start using
gitlink-cli repo +list

Quick Start (AI Agent)

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

Step 1 — Install

# One command: CLI binary + all Skills auto-installed
npm install -g @gitlink-ai/cli

Step 2 — Configure

gitlink-cli config init

Step 3 — Login

For interactive environments:

gitlink-cli auth login

For non-interactive environments (CI/CD, Trae sandbox, MCP, etc.):

export GITLINK_TOKEN="your-private-token"

To get a private token, go to GitLink web → Settings → Private Tokens.

Step 4 — Verify

gitlink-cli user +me

Installation & Uninstallation

Detailed install guide: doc/INSTALL.md
Detailed uninstall guide: doc/UNINSTALL.md

Quick Install

Linux/macOS: curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash
Windows PowerShell: powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1
npm: npm install -g @gitlink-ai/cli

Quick Uninstall

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

💡 Tip: See detailed guides: doc/INSTALL.md | doc/UNINSTALL.md

Usage Examples

Repository Operations

# List repositories
gitlink-cli repo +list

# View repository info
gitlink-cli repo +info --owner Gitlink --repo forgeplus

# Create a repository
gitlink-cli repo +create -n my-project -d "Project description"

# Fork a repository
gitlink-cli repo +fork --owner Gitlink --repo forgeplus

Issue Management

# List issues
gitlink-cli issue +list --owner Gitlink --repo forgeplus

# Create an issue
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" -b "Steps to reproduce..."

# View an issue
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123

# Close an issue
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123

# Preview batch close without changing data
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,124 --dry-run

# Batch close issues from a CSV file
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv

# Add a comment
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed"

# Batch delete issues
gitlink-cli issue +batch-destroy --owner Gitlink --repo forgeplus --numbers 100,101,102

Issue Metadata & Comments

# List available issue statuses
gitlink-cli issue +statuses

# List issue authors
gitlink-cli issue +authors --keyword zhang

# List issue assignees
gitlink-cli issue +assigners

# List issue priorities
gitlink-cli issue +priorities

# Edit a comment
gitlink-cli issue +comment-edit --number 42 --comment-id 100 --body "updated comment"

# Delete a comment
gitlink-cli issue +comment-delete --number 42 --comment-id 100

# List replies to a comment
gitlink-cli issue +replies --number 42 --comment-id 100

Pull Requests

# List PRs
gitlink-cli pr +list --owner Gitlink --repo forgeplus

# Create a PR (same-repo branch)
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: Search feature" --head feature/search --base master

# Create a PR (from a fork)
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: New feature" --head your_username/forgeplus:feature/my-feature --base master

# View a PR
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42

# Merge a PR
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42

# View changed files
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42

File & Code Operations

# List root directory
gitlink-cli file +ls --owner Gitlink --repo forgeplus

# Browse subdirectory
gitlink-cli file +tree --path src/

# Read file content
gitlink-cli file +read --path README.md

# Read README
gitlink-cli file +readme

# Search files by name
gitlink-cli file +search --q "test"

# Create a file
gitlink-cli file +create --path docs/new.md --content "# New Doc" --branch master --message "add doc"

# Update a file (auto-fetches sha)
gitlink-cli file +update --path README.md --content "updated" --branch master --message "update readme"

# Delete a file (auto-fetches sha)
gitlink-cli file +delete --path old.txt --branch master

# Batch commit multiple files
gitlink-cli file +batch --branch master --message "batch update" --files '[{"action_type":"create","file_path":"a.txt","content":"hello"}]'

# View commit history
gitlink-cli file +commits

# View commit diff
gitlink-cli file +diff --sha abc1234

Milestone Management

# List milestones
gitlink-cli milestone +list --owner Gitlink --repo forgeplus

# Create a milestone
gitlink-cli milestone +create --name "v1.0" --description "First release" --date 2026-12-31

# View milestone details
gitlink-cli milestone +view --id 1

# Update a milestone
gitlink-cli milestone +update --id 1 --name "v1.0-rc1"

# Close a milestone
gitlink-cli milestone +status --id 1 --status closed

# Delete a milestone
gitlink-cli milestone +delete --id 1

PR Enhanced Operations

# Reopen a closed PR
gitlink-cli pr +reopen --id 42

# Update PR title/description
gitlink-cli pr +update --id 42 --title "New title"

# List commits in a PR
gitlink-cli pr +commits --id 42

# List PR versions
gitlink-cli pr +versions --id 42

# View diff of a specific PR version
gitlink-cli pr +vdiff --id 42 --version 5

# List changed files (v1 API with pagination)
gitlink-cli pr +filesv1 --id 42

# Edit a PR review comment
gitlink-cli pr +comment-edit --id 42 --comment-id 100 --body "updated" --state resolved

# Delete a PR review comment
gitlink-cli pr +comment-delete --id 42 --comment-id 100

Branch Management

# List branches
gitlink-cli branch +list --owner Gitlink --repo forgeplus

# Create a branch
gitlink-cli branch +create --name feature/new-feature

# Delete a branch
gitlink-cli branch +delete --name feature/old-feature

# Protect a branch
gitlink-cli branch +protect --name main

# Remove branch protection
gitlink-cli branch +unprotect --name main

Board (Kanban)

# View kanban board layout
gitlink-cli board +view --owner Gitlink --repo forgeplus

# List status columns with issue counts
gitlink-cli board +columns --owner Gitlink --repo forgeplus

# Filter issues by status and assignee
gitlink-cli board +issues --owner Gitlink --repo forgeplus --status in-progress --assignee zhangsan

# Move an issue to a different status
gitlink-cli board +move --owner Gitlink --repo forgeplus --number 42 --status resolved

# Assign an issue to someone
gitlink-cli board +assign --owner Gitlink --repo forgeplus --number 42 --assignee zhangsan

# View board analytics and statistics
gitlink-cli board +stats --owner Gitlink --repo forgeplus

Webhook Management

# List all webhooks
gitlink-cli webhook +list --owner Gitlink --repo forgeplus

# Create a webhook
gitlink-cli webhook +create --owner Gitlink --repo forgeplus --url https://ci.example.com/webhook --events push,pull_request

# Create webhook with secret
gitlink-cli webhook +create --url https://jenkins.example.com/webhook --secret my-secret-key --events push --description "CI/CD trigger"

# View webhook details
gitlink-cli webhook +info --id 456

# Update webhook
gitlink-cli webhook +update --id 456 --url https://new-url.example.com/webhook --events push,pull_request,issue

# Test webhook
gitlink-cli webhook +test --id 456

# Delete webhook
gitlink-cli webhook +delete --id 456

# List supported event types
gitlink-cli webhook +events

Release Management

# List releases
gitlink-cli release +list --owner Gitlink --repo forgeplus

# Create a release
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..."

# View a release
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>

CI/CD Operations

# List builds
gitlink-cli ci +list --owner Gitlink --repo forgeplus

# View build log
gitlink-cli ci +log --owner Gitlink --repo forgeplus -i <build_id>

# Restart a build
gitlink-cli ci +restart --owner Gitlink --repo forgeplus -i <build_id>

Wiki Management

# List wiki pages
gitlink-cli wiki +list --owner Gitlink --repo forgeplus

# View a wiki page
gitlink-cli wiki +view --owner Gitlink --repo forgeplus --title "Getting Started"

# Create a wiki page
gitlink-cli wiki +create --title "New Page" --content "Page content"

# Update a wiki page (overwrite)
gitlink-cli wiki +update --title "New Page" --cover "Updated content" --owner Gitlink --repo forgeplus 

# Append content to a wiki page
gitlink-cli wiki +update --title "New Page" --add "Appended content" --owner Gitlink --repo forgeplus

# Delete a wiki page
gitlink-cli wiki +delete --title "New Page" --owner Gitlink --repo forgeplus

Search

# Search repositories
gitlink-cli search +repos -k "machine learning"

# Search users
gitlink-cli search +users -k "zhangsan"

Raw API

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

# GET request
gitlink-cli api GET /users/me

# POST request
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'

# With query parameters
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

gitlink-cli supports bidirectional code sync between GitHub and GitLink:

Platform	Default Branch
GitHub	main
GitLink	master

Push to GitLink from local:

# Method 1: Use git command directly
git push gitlink main:master

# Method 2: Configure git remote
git config remote.gitlink.push refs/heads/main:refs/heads/master
git push gitlink

AI Agent Skills

The skills/ directory contains 12 Agent Skill files for AI-automated GitLink operations.

See skills/README.md for details.

Skill	Description
gitlink-shared	Authentication, global parameters, safety rules, API notes
gitlink-repo	Repository operations (create, view, delete, fork, etc.)
gitlink-issue	Issue operations (create, update, close, comment, etc.)
gitlink-pr	Pull request operations (create, merge, review, etc.)
gitlink-branch	Branch management (create, delete, list, protect, unprotect)
gitlink-release	Release management (create, view, delete, etc.)
gitlink-ci	CI/CD operations (builds, logs, etc.)
gitlink-search	Search (repositories, users, etc.)
gitlink-org	Organization management (members, teams, etc.)
gitlink-user	User management (profile info, etc.)
gitlink-pm	Project management (sprints, kanban, weekly reports, etc.)
gitlink-workflow	AI-powered workflows (issue triage, PR review, release notes, etc.)

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/               # Envelope + formatter
├── shortcuts/                # Shortcut implementations
│   ├── common/               # Framework (types, runner)
│   ├── repo/                 # Repository shortcuts
│   ├── issue/                # Issue shortcuts
│   ├── pr/                   # PR shortcuts
│   ├── board/                # Board (kanban) shortcuts
│   ├── branch/               # Branch shortcuts
│   ├── release/              # Release shortcuts
│   ├── org/                  # Organization shortcuts
│   ├── ci/                   # CI shortcuts
│   ├── search/               # Search shortcuts
│   ├── user/                 # User shortcuts
│   ├── wiki/                 # Wiki shortcuts
│   ├── file/                 # File & code shortcuts
│   ├── milestone/            # Milestone shortcuts
│   └── register.go           # Registration entry point
├── skills/                   # AI Agent Skills
│   ├── README.md             # Skills guide
│   ├── gitlink-shared/       # Shared rules
│   ├── gitlink-repo/         # Repository skill
│   ├── gitlink-issue/        # Issue skill
│   ├── gitlink-pr/           # PR skill
│   ├── gitlink-pm/           # Project management skill
│   └── ...
├── doc/                      # Design documents
│   ├── Design.md
│   ├── CODE_SYNC_STRATEGY_FINAL.md
│   └── ...
├── main.go
├── Makefile
├── go.mod
└── README.md

Documentation

• Skills Guide — AI Agent Skills detailed documentation
• Design Document — Architecture design and development plan

FAQ

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

Use the GITLINK_TOKEN environment variable + --format json for structured output:

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:

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

Q: What if my token expires?

Re-authenticate:

# Username/password login
gitlink-cli auth login

# Or use a private token (generate at GitLink web → Settings → Private Tokens)
gitlink-cli auth login --token

Q: How do I use gitlink-cli in CI/CD or non-interactive environments (e.g. Trae sandbox)?

Set the GITLINK_TOKEN environment variable — no auth login needed:

export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list   # Ready to use
gitlink-cli auth status   # Shows "✓ Logged in via GITLINK_TOKEN environment variable"

Priority: GITLINK_TOKEN env var > keyring/file stored token. When the env var is not set, the original interactive login flow works as before.

Q: What if npm installs successfully but gitlink-cli reports a missing binary?

Reinstall first:

npm install -g @gitlink-ai/cli

If the error persists, check whether the release page contains the asset for your platform, for example gitlink-cli_<version>_windows_amd64.zip on Windows x64. You can also download the binary manually from the release page or 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 automatically falls back to file storage (~/.config/gitlink-cli/credentials).

Q: Where can I find the full API reference?

See skills/gitlink-shared/REFERENCE.md.

License

MulanPSL-2.0