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 11 AI Agent Skills.

中文文档

Install · AI Agent Skills · Auth · Commands · Contributing

Why gitlink-cli?

• Agent-Native Design — 11 structured Skills out of the box, compatible with Claude Code — 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 in one command
• 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
🔀 PR	Create, merge, review pull requests, view changed files
🌿 Branch	Create, delete, protect branches
🏷️ Release	Create, view, delete releases
🏢 Org	Manage organizations, members, teams
🔧 CI	View builds, logs, CI/CD operations
🔍 Search	Search repositories, users
👤 User	View user profiles and info
📋 PM	Sprint management, kanban boards, weekly reports
🤖 Workflow	AI-powered issue triage, PR review, release notes

Installation & Quick Start

Requirements

• Node.js 14+ (npm/npx) — for npm installation
• 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

Choose one of the following methods:

Option 1 — From npm (recommended):

# Install CLI
npm install -g @gitlink-ai/cli

# Install CLI Skills (required, works on all platforms)
gitlink-cli-install-skills

# Or install Skills with npx
npx skills add ccfos/gitlink-cli/skills -y -g

Option 2 — From source:

Requires Go 1.26+.

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

# Install CLI Skills (required)
npx skills add ./skills -y -g

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

# Install CLI
npm install -g @gitlink-ai/cli

# Install CLI Skills (required, works on all platforms)
gitlink-cli-install-skills

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

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

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

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

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>

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 11 Claude Code 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-release	Release management (create, view, delete, etc.)
gitlink-org	Organization management (members, teams, etc.)
gitlink-ci	CI/CD operations (builds, logs, etc.)
gitlink-search	Search (repositories, users, 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
│   ├── branch/               # Branch shortcuts
│   ├── release/              # Release shortcuts
│   ├── org/                  # Organization shortcuts
│   ├── ci/                   # CI shortcuts
│   ├── search/               # Search shortcuts
│   ├── user/                 # User 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: 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