The official GitLink CLI tool — built for humans and AI Agents. Supports macOS, Linux, and Windows. Covers repository management, issue tracking, pull requests, webhooks, member collaboration, CI/CD, and AI-powered workflows, with 40+ commands and AI Agent Skills.
Agent-Native Design — 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, Webhook, Member, Branch, Release, CI, Pipeline, Org, Search, and User workflows are covered by high-level commands
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)
Run, inspect, enable, disable, delete pipeline workflows and logs
🔔 Webhook
Manage repo webhooks and test deliveries
🔍 Search
Search repositories, users
📊 Dataset
Query research datasets by project
👤 User
View user profiles and info
📊 Profile
User ability, role, major, activity, and contribution statistics
📋 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
From npm (recommended):
# One command: installs CLI binary + AI Agent Skills
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
Usage Examples
Repository Operations
# List repositories
gitlink-cli repo +list
# View repository info
gitlink-cli repo +info --owner Gitlink --repo forgeplus
# Read repository README
gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master
# List repository files at root or a directory
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main
# Show language breakdown
gitlink-cli repo +languages --owner Gitlink --repo forgeplus
# List contributors
gitlink-cli repo +contributors --owner Gitlink --repo forgeplus
# Show contributor code-line stats for a branch, tag, or commit
gitlink-cli repo +contributor-stats --owner Gitlink --repo forgeplus --ref master --pass-year 1
# Show repository code stats
gitlink-cli repo +code-stats --owner Gitlink --repo forgeplus --ref master
# List watchers and stargazers in a time range
gitlink-cli repo +watchers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
gitlink-cli repo +stargazers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
# Preview and apply repository interaction actions
gitlink-cli repo +follow --owner Gitlink --repo forgeplus --dry-run
gitlink-cli repo +follow --owner Gitlink --repo forgeplus
gitlink-cli repo +unfollow --owner Gitlink --repo forgeplus --project-id 123
gitlink-cli repo +like --owner Gitlink --repo forgeplus
gitlink-cli repo +unlike --owner Gitlink --repo forgeplus --project-id 123
# Create a repository
gitlink-cli repo +create -n my-project -d "Project description"
# Fork a repository
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
# List repository members
gitlink-cli member +list --owner Gitlink --repo forgeplus
# Add a member
gitlink-cli member +add --owner Gitlink --repo forgeplus --user-id 101
# Preview batch add without changing data
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --user-ids 101,102 --dry-run
# Batch add members from a CSV file
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --from members.csv
# Change a member role
gitlink-cli member +role --owner Gitlink --repo forgeplus --user-id 101 --role Developer
# Create an invite link
gitlink-cli member +invite-link --owner Gitlink --repo forgeplus --role developer --apply true
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..."
# Create an issue with metadata
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" --priority-id 3 --tag-ids 4,5 --assigner-ids 7
# View an issue
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
# Update issue metadata
gitlink-cli issue +update --owner Gitlink --repo forgeplus --number 123 --priority-id 4 --branch bugfix/login --due-date 2026-06-15
# 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
# Preview batch metadata update by API issue IDs
# Note: --ids uses API issue IDs, not web URL issue numbers.
gitlink-cli issue +batch-update --owner Gitlink --repo forgeplus --ids 101,102 --status-id 3 --priority-id 2 --dry-run
# Destructive batch delete requires both dry-run first and --yes for real execution
gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --dry-run
gitlink-cli issue +batch-delete --owner Gitlink --repo forgeplus --ids 101,102 --yes
# Add a comment
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed"
# List issue assigners
gitlink-cli issue +assigners --owner Gitlink --repo forgeplus
# List issue authors
gitlink-cli issue +authors --owner Gitlink --repo forgeplus
# List issue priorities
gitlink-cli issue +priorities --owner Gitlink --repo forgeplus
# List issue tags
gitlink-cli issue +tags --owner Gitlink --repo forgeplus --only-name
# List issue statuses
gitlink-cli issue +statuses --owner Gitlink --repo forgeplus
issue +view, issue +update, issue +close, and issue +comment prefer
--number / -n for the issue number shown in the web URL. --id / -i
is accepted as a compatibility alias for the same web issue number, not the
global database ID.
Label Management
# List issue labels
gitlink-cli label +list --owner Gitlink --repo forgeplus
# Filter labels by keyword
gitlink-cli label +list --owner Gitlink --repo forgeplus -k bug
# Create a label (color defaults to #1E90FF)
gitlink-cli label +create --owner Gitlink --repo forgeplus -n bug -d "Something is broken" -c "#FF0000"
# Update a label (unspecified fields are preserved)
gitlink-cli label +update --owner Gitlink --repo forgeplus -i 42 -c "#00FF00"
# Delete a label
gitlink-cli label +delete --owner Gitlink --repo forgeplus -i 42
profile surfaces GitLink’s native user statistics (ability, role, major, activity,
contribution). When --user is omitted it defaults to the authenticated user.
# Development ability scores + language breakdown
gitlink-cli profile +ability --user zhangsan
# Role positioning / major (discipline) categories
gitlink-cli profile +role --user zhangsan
gitlink-cli profile +major --user zhangsan
# Ability within a time window (Unix timestamps)
gitlink-cli profile +ability --user zhangsan --start-time 1704067200 --end-time 1735689600
# Recent activity (issues / PRs / commits per day) for the current user
gitlink-cli profile +activity
# Contribution heatmap for a given year
gitlink-cli profile +contribution --user zhangsan --year 2025
Workflow Agent Commands
workflow provides rule-based repository analysis for maintainers and AI Agents. It currently supports:
workflow +triage
workflow +health
workflow +pr-summary
workflow +repo-report
workflow +pr-summary defaults to table when --format is omitted.
workflow +repo-report defaults to markdown when --format is omitted.
Examples:
# Triage with local parameters
gitlink-cli workflow +triage --title "Install failed on Windows" --body "go install failed with error" --format table
# Triage with JSON output
gitlink-cli workflow +triage --title "Token leaked in logs" --body "The access token appears in command output" --format json
# Triage with Chinese markdown output
gitlink-cli workflow +triage \
--title "安装失败,无法登录" \
--body "运行命令时报错" \
--lang zh-CN \
--format markdown
# Triage from a local JSON file
gitlink-cli workflow +triage --from shortcuts/workflow/testdata/issue_bug.json --format json
# Triage by read-only GitLink fetch
gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open --limit 5 --format table
# Health for a healthy repository
gitlink-cli workflow +health \
--repository Gitlink/gitlink-cli \
--open-issues 3 \
--open-prs 1 \
--has-readme \
--has-license \
--has-contributing \
--agent-readiness-known \
--agent-readiness-score 9 \
--format table
# Health for a risky repository
gitlink-cli workflow +health \
--repository demo/repo \
--open-issues 60 \
--stale-issues 25 \
--open-prs 12 \
--stale-prs 6 \
--recent-activity-known \
--recent-activity-days 120 \
--release-known=false \
--format json
# Health with Chinese markdown output
gitlink-cli workflow +health \
--repository Gitlink/gitlink-cli \
--open-issues 3 \
--open-prs 1 \
--has-readme \
--has-license \
--has-contributing \
--lang zh-CN \
--format markdown
# Health by read-only GitLink fetch
gitlink-cli workflow +health --owner Gitlink --repo gitlink-cli --stale-days 30 --format table
# PR review summary by read-only GitLink fetch
gitlink-cli workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 1 --format markdown
# PR review summary from a local JSON file
gitlink-cli workflow +pr-summary --from shortcuts/workflow/testdata/pr_summary.json --format json
# Repository workflow report by read-only GitLink fetch
gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --format markdown
# Repository workflow report from a local JSON file
gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format json
Output formats:
json for scripts and AI Agents
table for terminal review
markdown for Issue comments, PR comments, release notes, and competition write-ups
Safety:
Current workflow commands use local analysis by default and can also read GitLink data in read-only fetch mode.
They do not modify remote GitLink data.
They do not depend on LLM APIs.
workflow +pr-summary does not comment, approve, reject, or merge pull requests.
workflow +repo-report aggregates health, issue triage, and PR review summary signals without remote writes.
Dataset
dataset manages and queries GitLink research datasets (title, description,
paper content, license, owning project).
# List datasets for one or more projects (by numeric project ID)
gitlink-cli dataset +list --ids 5988
# View a repository's dataset and attachments
gitlink-cli dataset +view --owner Gitlink --repo forgeplus
# Create / update a repository's dataset (preview first with --dry-run)
gitlink-cli dataset +create --owner me --repo proj -t "My dataset" -d "..." --license-id 359 --dry-run
gitlink-cli dataset +update --owner me --repo proj -t "My dataset" -d "updated"
# Delete a dataset attachment (destructive: preview, then confirm with --yes)
gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid <uuid> --dry-run
gitlink-cli dataset +delete-attachment --owner me --repo proj --uuid <uuid> --yes
Note: dataset +list (platform dataset query) is verified on production
gitlink.org.cn. The per-repo +view/+create/+update routes follow the
published OpenAPI contract but are not yet deployed on production (they return
404 there); they will work once the platform enables them.
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":"..."}'
# POST request with body from a file
gitlink-cli api POST /Gitlink/forgeplus/issues --body-file issue.json
# POST request with body from stdin
Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-stdin
# 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; workflow also supports markdown)
--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:
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).
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, webhooks, member collaboration, CI/CD, and AI-powered workflows, with 40+ commands and AI Agent Skills.
中文文档
Install · AI Agent Skills · Auth · Commands · Contributing
Contributors
wangyue111
wbtiger
Mengz
yangsai
mengcheng
muel
Leo77
yingjie
topshare
dtwdtw
recorder
puygob236
co63oc
lindiwen23
ohanabi
jiangtx
luwanzhou
whale_hihihi
Why gitlink-cli?
npm install -g @gitlink-ai/cliin one command, binary auto-downloadednpm installGITLINK_TOKENenv var, from install to first API call in just 3 stepsGITLINK_TOKENenv var for CI/CD & non-interactive environments, auto git remote context resolutionFeatures
Installation & Quick Start
Requirements
npm/npx) — for npm installationQuick Start (Human Users)
Install
From npm (recommended):
The binary is auto-downloaded for your platform during
postinstall. No extra steps needed.From source:
Requires Go 1.26+.
Configure & Use
Quick Start (AI Agent)
Step 1 — Install
Step 2 — Configure
Step 3 — Login
For interactive environments:
For non-interactive environments (CI/CD, Trae sandbox, MCP, etc.):
Step 4 — Verify
Usage Examples
Repository Operations
Webhook Management
Member Management
Issue Management
issue +view,issue +update,issue +close, andissue +commentprefer--number/-nfor the issue number shown in the web URL.--id/-iis accepted as a compatibility alias for the same web issue number, not the global database ID.Label Management
Pull Requests
Branch Management
Release Management
CI/CD Operations
Pipeline Operations
Ignore File Templates
Search
User Profile
profilesurfaces GitLink’s native user statistics (ability, role, major, activity, contribution). When--useris omitted it defaults to the authenticated user.Workflow Agent Commands
workflowprovides rule-based repository analysis for maintainers and AI Agents. It currently supports:workflow +triageworkflow +healthworkflow +pr-summaryworkflow +repo-reportworkflow +pr-summarydefaults totablewhen--formatis omitted.workflow +repo-reportdefaults tomarkdownwhen--formatis omitted.Examples:
Output formats:
jsonfor scripts and AI Agentstablefor terminal reviewmarkdownfor Issue comments, PR comments, release notes, and competition write-upsSafety:
workflow +pr-summarydoes not comment, approve, reject, or merge pull requests.workflow +repo-reportaggregates health, issue triage, and PR review summary signals without remote writes.Dataset
datasetmanages and queries GitLink research datasets (title, description, paper content, license, owning project).Raw API
For endpoints not covered by shortcuts, use the Raw API directly:
Global Parameters
--owner--owner Gitlink--repo--repo forgeplus--format--format json--debug--debugAutomatic context resolution: When running inside a git repository,
--ownerand--repoare automatically resolved fromgit remote origin.Branch Conventions
gitlink-cli supports bidirectional code sync between GitHub and GitLink:
mainmasterPush to GitLink from local:
AI Agent Skills
The
skills/directory contains Agent Skill files for AI-automated GitLink operations.See skills/README.md for details.
gitlink-sharedgitlink-repogitlink-issuegitlink-prgitlink-membergitlink-branchgitlink-releasegitlink-cigitlink-pipelinegitlink-searchgitlink-orggitlink-usergitlink-pmgitlink-workflowgitlink-healthProject Structure
Documentation
FAQ
Q: How do I use gitlink-cli in scripts?
Use the
GITLINK_TOKENenvironment variable +--format jsonfor structured output:Q: How does automatic owner/repo resolution work?
When running inside a git repository, the CLI automatically resolves
--ownerand--repofromgit remote origin:Q: What if my token expires?
Re-authenticate:
Q: How do I use gitlink-cli in CI/CD or non-interactive environments (e.g. Trae sandbox)?
Set the
GITLINK_TOKENenvironment variable — noauth loginneeded:Priority:
GITLINK_TOKENenv 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-clireports a missing binary?Reinstall first:
If the error persists, check whether the release page contains the asset for your platform, for example
gitlink-cli_<version>_windows_amd64.zipon Windows x64. You can also download the binary manually from the release page or build from source withgo 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/references/api-reference.md.
License
MulanPSL-2.0