gitea-cli-skill 0.1.0

package/assets/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: gitea-cli
+description: Use when needing to interact with Gitea repositories, branches, issues, pull requests, releases, actions CI/CD, webhooks, labels, milestones, tags, or file content via the gitea-cli command-line tool. Triggers on Gitea API operations, repository management, CI/CD pipeline management, or any task requiring gitea-cli commands.
+---
+
+# gitea-cli
+
+## Binary Location
+
+Binaries for all platforms are bundled under the `scripts/` directory relative to this skill:
+
+| Platform | Relative Path |
+|----------|------|
+| Linux amd64 | `scripts/linux-amd64/gitea-cli` |
+| Linux arm64 | `scripts/linux-arm64/gitea-cli` |
+| macOS amd64 | `scripts/darwin-amd64/gitea-cli` |
+| macOS arm64 | `scripts/darwin-arm64/gitea-cli` |
+| Windows amd64 | `scripts/windows-amd64/gitea-cli.exe` |
+| Windows arm64 | `scripts/windows-arm64/gitea-cli.exe` |
+
+**Skill directory is `~/.claude/skills/gitea-cli/`.** Before executing commands, resolve `gitea-cli` to the platform-appropriate binary. Auto-detect with:
+
+```bash
+SKILL_DIR="$HOME/.claude/skills/gitea-cli"
+
+# Linux / macOS
+OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
+ARCH="$(uname -m)"
+[[ "$ARCH" == "x86_64" ]] && ARCH="amd64"
+[[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]] && ARCH="arm64"
+GITEA_CLI="$SKILL_DIR/scripts/${OS}-${ARCH}/gitea-cli"
+
+# Windows (PowerShell)
+# $GITEA_CLI = "$env:USERPROFILE\.claude\skills\gitea-cli\scripts\windows-amd64\gitea-cli.exe"
+```
+
+If the tool is also available in PATH (e.g. installed globally), `gitea-cli` can be used directly.
+
+## Overview
+
+`gitea-cli` is a stateless CLI tool that manages Gitea repositories through the HTTP API. Each call is an independent API request, making it safe for concurrent use. It supports both human-friendly table output and machine-friendly JSON output (`--output json`).
+
+## Agent Rules
+
+### 1. Always use JSON output
+
+```bash
+gitea-cli <command> --output json --owner <owner> --repo <repo>
+```
+
+### 2. Never switch context autonomously
+
+Use `--owner`/`--repo` flags to target different repos. Do NOT call `config use` without user supervision.
+
+### 3. Destructive operations require confirmation
+
+Always run a list/get command first to verify the target exists before deleting.
+
+### 4. Branch/ref auto-detection
+
+When inside a git repo, `--branch` and `--ref` default to the current branch. `--owner`/`--repo` auto-detect from git remote.
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--output` | `-o` | `json` or `table` (agents: always use `json`) |
+| `--owner` | | Repository owner |
+| `--repo` | `-r` | Repository name |
+| `--context` | `-c` | Context name (override, no save) |
+| `--config` | | Config file path |
+| `--host` | | Gitea host URL |
+| `--token` | | API token |
+
+**Env vars:** `GITEA_HOST`, `GITEA_TOKEN`, `GITEA_OWNER`, `GITEA_REPO`, `GITEA_OUTPUT`
+
+## Command Quick Reference
+
+### Config
+
+```bash
+gitea-cli config list                                        # List all contexts
+gitea-cli config get <name>                                  # Get context details
+gitea-cli config set --name <ctx> --host <url> --token <tok> # Create/update context
+```
+
+### Repository
+
+```bash
+gitea-cli repo list --owner <org> --output json
+gitea-cli repo get --owner <org> --repo <repo> --output json
+```
+
+### Branch
+
+```bash
+gitea-cli branch list --output json
+gitea-cli branch get <name> --output json
+gitea-cli branch create <name> --from <base>
+gitea-cli branch delete <name> --force
+gitea-cli branch protect list --output json
+gitea-cli branch protect create <name> --enable-push --required-approvals 2
+gitea-cli branch protect delete <name> --force
+```
+
+### File Content
+
+```bash
+gitea-cli content list [--path] --ref <branch> --output json
+gitea-cli content get <path> --ref <branch> --output json       # --raw for decoded content in json
+gitea-cli content create <path> --content "text" -m "msg"       # or --file <local>
+gitea-cli content update <path> --content "text" -m "msg"       # --sha auto-fetched
+gitea-cli content delete <path> -m "msg" --force
+```
+
+### Commit
+
+```bash
+gitea-cli commit list --branch <ref> --limit 10 --output json
+gitea-cli commit get <sha> --output json
+```
+
+### Issue
+
+```bash
+gitea-cli issue list --state open --output json
+gitea-cli issue get <number> --output json
+gitea-cli issue create -t "Title" -b "Body" --label <id> --milestone <id>
+gitea-cli issue update <number> -t "New Title" --state closed
+gitea-cli issue close <number>
+
+# Comments
+gitea-cli issue comment list <number> --output json
+gitea-cli issue comment create <number> -b "Comment text"
+gitea-cli issue comment update <comment-id> -b "Updated text"
+gitea-cli issue comment delete <comment-id> --force
+
+# Attachments
+gitea-cli issue attachment list <number> --output json
+gitea-cli issue attachment upload <number> <file> --name <filename>
+gitea-cli issue attachment download <number> <attach-id> -o ./save/
+gitea-cli issue attachment delete <number> <attach-id> --force
+```
+
+### Pull Request
+
+```bash
+gitea-cli pr list --state open --output json
+gitea-cli pr get <index> --output json
+gitea-cli pr create --title "Title" --head <src> --base <target> --body "Desc"
+gitea-cli pr close <index>
+gitea-cli pr reopen <index>
+gitea-cli pr merge <index> --strategy merge --delete-branch
+```
+
+### Label
+
+```bash
+gitea-cli label list --output json
+gitea-cli label get <id> --output json
+gitea-cli label create --name "bug" --color "#ff0000" --description "Bug report"
+gitea-cli label delete <id> --force
+```
+
+### Milestone
+
+```bash
+gitea-cli milestone list --state open --output json
+gitea-cli milestone get <id> --output json
+gitea-cli milestone create --title "v1.0" --description "First release" --due-on 2025-12-31T00:00:00Z
+gitea-cli milestone close <id>
+gitea-cli milestone delete <id> --force
+```
+
+### Tag
+
+```bash
+gitea-cli tag list --output json
+gitea-cli tag get <name> --output json
+gitea-cli tag create <name> --target <ref> -m "Annotated tag message"
+gitea-cli tag delete <name> --force
+```
+
+### Actions (CI/CD)
+
+```bash
+# Workflows
+gitea-cli actions workflow list --output json
+gitea-cli actions workflow get <id-or-filename> --output json
+gitea-cli actions workflow enable <id-or-filename>
+gitea-cli actions workflow disable <id-or-filename>
+gitea-cli actions workflow dispatch <id-or-filename> --ref main --input key=value
+
+# Runs
+gitea-cli actions run list --status completed --output json
+gitea-cli actions run get <run-id> --output json
+gitea-cli actions run jobs <run-id> --output json
+gitea-cli actions run artifacts <run-id> --output json
+gitea-cli actions run delete <run-id> --force
+
+# Jobs
+gitea-cli actions job get <job-id> --output json
+gitea-cli actions job logs <job-id> -o ./logs/
+
+# Artifacts
+gitea-cli actions artifact list --output json
+gitea-cli actions artifact download <id> -o ./dist/
+gitea-cli actions artifact delete <id> --force
+```
+
+### Webhook
+
+```bash
+gitea-cli webhook list --output json
+gitea-cli webhook get <id> --output json
+gitea-cli webhook create --url <endpoint> --secret <secret> --event push --event issues --active
+gitea-cli webhook update <id> --url <new-url> --active false
+gitea-cli webhook delete <id> --force
+gitea-cli webhook test <id>
+```
+
+### Release
+
+```bash
+gitea-cli release list --output json
+gitea-cli release get <tag> --output json
+gitea-cli release create --tag <tag> --name "Title" --body "Notes" --target <ref> --draft --prerelease
+gitea-cli release delete <tag> --force
+
+# Assets
+gitea-cli release asset list <tag> --output json
+gitea-cli release asset upload <tag> <file> --name <asset-name>
+gitea-cli release asset download <tag> <asset-id> -o ./downloads/
+gitea-cli release asset delete <tag> <asset-id> --force
+```
+
+## Common Patterns
+
+### Read file from repo, modify, write back
+
+```bash
+# 1. Get current content (captures SHA for update)
+gitea-cli content get src/config.yaml --output json --owner myorg --repo myrepo
+
+# 2. Update with new content (SHA auto-fetched if omitted)
+gitea-cli content update src/config.yaml --content "new: value" -m "update config" --owner myorg --repo myrepo
+```
+
+### Create issue with labels and milestone
+
+```bash
+# 1. Find label IDs
+gitea-cli label list --output json --owner myorg --repo myrepo
+
+# 2. Find milestone ID
+gitea-cli milestone list --output json --owner myorg --repo myrepo
+
+# 3. Create issue
+gitea-cli issue create -t "Fix login bug" -b "Description" --label 3 --label 7 --milestone 2 --owner myorg --repo myrepo
+```
+
+### Monitor CI/CD pipeline
+
+```bash
+# 1. Find latest run
+gitea-cli actions run list --limit 5 --output json
+
+# 2. Check job status
+gitea-cli actions run jobs <run-id> --output json
+
+# 3. Get logs for failed job
+gitea-cli actions job logs <job-id> -o ./logs/
+```
+
+## Error Handling
+
+| Exit Code | Meaning |
+|-----------|---------|
+| `0` | Success |
+| `1` | Error (see stderr) |
+
+JSON errors on stderr: `{"error": "API 404: repository not found"}`
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `host is required` | No context configured | Run `config set` |
+| `API 404` | Resource not found | Verify owner/repo/index |
+| `API 409` | Resource already exists | Skip duplicate creation |
+| `API 401` | Invalid/expired token | Check context token |
+
+## Destructive Operations Checklist
+
+Before running any delete, always verify:
+
+1. Run the corresponding `list` or `get` command first
+2. Confirm the resource ID/name matches the intended target
+3. Use `--force` flag to skip interactive prompts (required for agent use)
+4. Consider irreversibility — deleted resources cannot be recovered

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "gitea-cli-skill",
+  "version": "0.1.0",
+  "description": "Install gitea-cli as a Claude Code skill",
+  "bin": {
+    "gitea-cli-skill": "src/index.js"
+  },
+  "files": [
+    "src",
+    "assets"
+  ],
+  "keywords": [
+    "claude-code",
+    "skill",
+    "gitea",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+const GITEA_HOST = 'https://x.xgit.pro';
+const GITEA_OWNER = 'chenqi';
+const GITEA_REPO = 'git-cli';
+const SKILL_NAME = 'gitea-cli';
+
+// ── Platform definitions ────────────────────────────────────────────────────
+
+const PLATFORMS = {
+  claude:   { dir: '.claude/skills',   file: 'SKILL.md', desc: 'Claude Code' },
+  cursor:   { dir: '.cursor/skills',   file: 'SKILL.md', desc: 'Cursor' },
+  windsurf: { dir: '.windsurf/skills', file: 'SKILL.md', desc: 'Windsurf' },
+  copilot:  { dir: '.copilot/skills',  file: 'SKILL.md', desc: 'GitHub Copilot CLI' },
+  codex:    { dir: '.codex/skills',    file: 'SKILL.md', desc: 'OpenAI Codex CLI' },
+  gemini:   { dir: '.gemini/skills',   file: 'SKILL.md', desc: 'Gemini CLI' },
+  trae:     { dir: '.trae/skills',     file: 'SKILL.md', desc: 'Trae' },
+  roo:      { dir: '.roo/skills',      file: 'SKILL.md', desc: 'Roo Code' },
+  kiro:     { dir: '.kiro/skills',     file: 'SKILL.md', desc: 'Kiro' },
+  continue: { dir: '.continue/skills', file: 'SKILL.md', desc: 'Continue' },
+};
+
+// ── OS/Arch detection ───────────────────────────────────────────────────────
+
+function detectOSArch() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let osName;
+  switch (platform) {
+    case 'darwin': osName = 'darwin'; break;
+    case 'linux': osName = 'linux'; break;
+    case 'win32': osName = 'windows'; break;
+    default: throw new Error(`Unsupported OS: ${platform}`);
+  }
+
+  let archName;
+  switch (arch) {
+    case 'x64': archName = 'amd64'; break;
+    case 'arm64': archName = 'arm64'; break;
+    default: throw new Error(`Unsupported arch: ${arch}`);
+  }
+
+  return { os: osName, arch: archName };
+}
+
+// ── Resolve skill install directory ─────────────────────────────────────────
+
+function resolveSkillDir(platformName, targetPath) {
+  if (targetPath) {
+    return targetPath.replace(/^~/, os.homedir());
+  }
+  if (platformName && PLATFORMS[platformName]) {
+    return path.join(os.homedir(), PLATFORMS[platformName].dir, SKILL_NAME);
+  }
+  // Default: claude
+  return path.join(os.homedir(), PLATFORMS.claude.dir, SKILL_NAME);
+}
+
+// ── HTTP via curl (robust cross-platform) ───────────────────────────────────
+
+function curlGet(url, token) {
+  const args = ['-sS', '-f', '-k', '-H', 'User-Agent: gitea-cli-skill-installer'];
+  if (token) {
+    args.push('-H', `Authorization: token ${token}`);
+  }
+  args.push(url);
+  return execSync(`curl ${args.map((a) => `"${a}"`).join(' ')}`, { encoding: 'utf-8', timeout: 30000 });
+}
+
+function curlDownload(url, destPath, token) {
+  const args = ['-sS', '-f', '-k', '-L', '-o', destPath, '-H', 'User-Agent: gitea-cli-skill-installer'];
+  if (token) {
+    args.push('-H', `Authorization: token ${token}`);
+  }
+  args.push(url);
+  execSync(`curl ${args.map((a) => `"${a}"`).join(' ')}`, { encoding: 'utf-8', timeout: 120000 });
+}
+
+// ── Gitea API ────────────────────────────────────────────────────────────────
+
+function getLatestRelease(host, owner, repo, token) {
+  // Try /latest first
+  try {
+    const data = curlGet(`${host}/api/v1/repos/${owner}/${repo}/releases/latest`, token);
+    const release = JSON.parse(data);
+    if (release.assets && release.assets.length > 0) return release;
+  } catch { /* fall through */ }
+
+  // List all releases, find latest with assets
+  const data = curlGet(`${host}/api/v1/repos/${owner}/${repo}/releases?limit=10`, token);
+  const releases = JSON.parse(data);
+  for (const r of releases) {
+    if (r.assets && r.assets.length > 0) return r;
+  }
+  throw new Error('No releases with assets found');
+}
+
+function findAsset(release, osArch) {
+  const ext = osArch.os === 'windows' ? 'zip' : 'tar.gz';
+  const pattern = `_${osArch.os}_${osArch.arch}.${ext}`;
+  return release.assets.find((a) => a.name.endsWith(pattern) && !a.name.includes('checksum'));
+}
+
+// ── Archive extraction ──────────────────────────────────────────────────────
+
+function extractArchive(archivePath, destDir, osArch) {
+  fs.mkdirSync(destDir, { recursive: true });
+  if (osArch.os === 'windows') {
+    execSync(`powershell -Command "Expand-Archive -Path '${archivePath}' -DestinationPath '${destDir}' -Force"`, { stdio: 'pipe' });
+  } else {
+    execSync(`tar -xzf "${archivePath}" -C "${destDir}"`, { stdio: 'pipe' });
+  }
+
+  const binaryName = osArch.os === 'windows' ? 'gitea-cli.exe' : 'gitea-cli';
+  const entries = fs.readdirSync(destDir, { recursive: true });
+  for (const entry of entries) {
+    if (path.basename(entry) === binaryName) {
+      const fullPath = path.join(destDir, entry);
+      if (osArch.os !== 'windows') fs.chmodSync(fullPath, 0o755);
+      return fullPath;
+    }
+  }
+  throw new Error(`Binary ${binaryName} not found in extracted archive`);
+}
+
+// ── Config generation ───────────────────────────────────────────────────────
+
+function writeGiteaCliConfig(host, token) {
+  const configDir = path.join(os.homedir(), '.config', 'gitea-cli');
+  const configPath = path.join(configDir, 'config.yaml');
+  const contextName = 'default';
+
+  // Read existing config if present
+  let existing = '';
+  if (fs.existsSync(configPath)) {
+    existing = fs.readFileSync(configPath, 'utf-8');
+    if (existing.includes(contextName)) {
+      console.log(`  Config already exists: ${configPath} (skipped)`);
+      return;
+    }
+  }
+
+  const newConfig = `${existing}contexts:
+- name: ${contextName}
+  host: ${host.replace(/\/$/, '')}
+  token: ${token}
+current-context: ${contextName}
+`;
+
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(configPath, newConfig, 'utf-8');
+  console.log(`  Config -> ${configPath}`);
+}
+
+// ── Install command ─────────────────────────────────────────────────────────
+
+async function install(args) {
+  const { token: explicitToken, host: explicitHost, platform: platformName, target: targetPath, local: localDir, force } = args;
+  const giteaHost = explicitHost || GITEA_HOST;
+  const token = explicitToken || process.env.GITEA_TOKEN || null;
+  const osArch = detectOSArch();
+  const skillDir = resolveSkillDir(platformName, targetPath);
+  const scriptsDir = path.join(skillDir, 'scripts', `${osArch.os}-${osArch.arch}`);
+
+  console.log(`Installing gitea-cli skill (${osArch.os}-${osArch.arch}) to ${skillDir}...`);
+
+  // 1. Copy SKILL.md
+  fs.mkdirSync(skillDir, { recursive: true });
+  const srcSkill = path.resolve(__dirname, '..', 'assets', 'SKILL.md');
+  const destSkill = path.join(skillDir, 'SKILL.md');
+  fs.copyFileSync(srcSkill, destSkill);
+  console.log(`  SKILL.md -> ${destSkill}`);
+
+  // 2. Check existing binary
+  const binaryName = osArch.os === 'windows' ? 'gitea-cli.exe' : 'gitea-cli';
+  const destBinary = path.join(scriptsDir, binaryName);
+
+  if (fs.existsSync(destBinary) && !force) {
+    console.log(`  Binary already exists: ${destBinary} (use --force to overwrite)`);
+  } else if (localDir) {
+    // --local: copy from local directory
+    await installFromLocal(localDir, scriptsDir, destBinary, osArch);
+  } else {
+    // Download from Gitea releases
+    await installFromRelease(giteaHost, token, scriptsDir, destBinary, osArch);
+  }
+
+  // 4. Write gitea-cli config if token provided
+  if (token) {
+    writeGiteaCliConfig(giteaHost, token);
+  }
+
+  console.log(`\nDone!`);
+}
+
+// ── Install from local goreleaser dist ───────────────────────────────────────
+
+function installFromLocal(localDir, scriptsDir, destBinary, osArch) {
+  // Goreleaser dist structure: dist/gitea-cli_<version>_<os>_<arch>/gitea-cli[.exe]
+  const ext = osArch.os === 'windows' ? 'zip' : 'tar.gz';
+  const archiveName = `gitea-cli_*_${osArch.os}_${osArch.arch}.${ext}`;
+
+  const resolvedDir = localDir.replace(/^~/, os.homedir());
+
+  // Try to find archive in dist/
+  const files = fs.readdirSync(resolvedDir);
+  const extRe = ext === 'tar.gz' ? 'tar\\.gz' : 'zip';
+  const pattern = new RegExp('gitea-cli_\\d+\\.\\d+\\.\\d+(-\\w+)?_' + osArch.os + '_' + osArch.arch + '\\.' + extRe + '$');
+  const match = files.find((f) => pattern.test(f));
+  if (!match) {
+    // Try finding extracted binary directly
+    const binaryName = osArch.os === 'windows' ? 'gitea-cli.exe' : 'gitea-cli';
+    const subDirs = files.filter((f) => f.includes(`${osArch.os}_${osArch.arch}`) && fs.statSync(path.join(resolvedDir, f)).isDirectory());
+    for (const d of subDirs) {
+      const candidate = path.join(resolvedDir, d, binaryName);
+      if (fs.existsSync(candidate)) {
+        fs.mkdirSync(scriptsDir, { recursive: true });
+        fs.copyFileSync(candidate, destBinary);
+        if (osArch.os !== 'windows') fs.chmodSync(destBinary, 0o755);
+        console.log(`  Binary -> ${destBinary} (from ${candidate})`);
+        return;
+      }
+    }
+    throw new Error(`No binary found for ${osArch.os}-${osArch.arch} in ${resolvedDir}`);
+  }
+
+  const archivePath = path.join(resolvedDir, match);
+  console.log(`  Extracting ${match}...`);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitea-cli-'));
+  try {
+    const binaryPath = extractArchive(archivePath, path.join(tmpDir, 'extracted'), osArch);
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    fs.copyFileSync(binaryPath, destBinary);
+    if (osArch.os !== 'windows') fs.chmodSync(destBinary, 0o755);
+    console.log(`  Binary -> ${destBinary}`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ── Install from Gitea release ───────────────────────────────────────────────
+
+async function installFromRelease(giteaHost, token, scriptsDir, destBinary, osArch) {
+  console.log(`  Fetching latest release from ${giteaHost}...`);
+  if (!token) {
+    console.error('  Error: Gitea API token is required.');
+    console.error('  Provide via --token <token> or GITEA_TOKEN env var.');
+    console.error('  Or use --local <dir> to install from a local build.');
+    process.exit(1);
+  }
+
+  let release;
+  try {
+    release = getLatestRelease(giteaHost, GITEA_OWNER, GITEA_REPO, token);
+  } catch (err) {
+    console.error(`  Failed to fetch release: ${err.message}`);
+    console.error('  Use --local <dir> to install from a local build instead.');
+    process.exit(1);
+  }
+
+  const asset = findAsset(release, osArch);
+  if (!asset) {
+    console.error(`  No binary for ${osArch.os}-${osArch.arch} in release ${release.tag_name}.`);
+    console.error(`  Assets: ${release.assets.map((a) => a.name).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`  Downloading ${asset.name} (${(asset.size / 1024 / 1024).toFixed(1)} MB)...`);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitea-cli-'));
+  const tmpArchive = path.join(tmpDir, asset.name);
+
+  try {
+    curlDownload(asset.browser_download_url, tmpArchive, token);
+    console.log('  Extracting...');
+    const binaryPath = extractArchive(tmpArchive, path.join(tmpDir, 'extracted'), osArch);
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    fs.copyFileSync(binaryPath, destBinary);
+    if (osArch.os !== 'windows') fs.chmodSync(destBinary, 0o755);
+    console.log(`  Binary -> ${destBinary}`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { token: null, host: null, platform: null, target: null, local: null, force: false, command: null };
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--token' && i + 1 < argv.length) args.token = argv[++i];
+    else if (arg === '--host' && i + 1 < argv.length) args.host = argv[++i];
+    else if (arg === '--platform' && i + 1 < argv.length) args.platform = argv[++i];
+    else if (arg === '--target' && i + 1 < argv.length) args.target = argv[++i];
+    else if (arg === '--local' && i + 1 < argv.length) args.local = argv[++i];
+    else if (arg === '--force' || arg === '-f') args.force = true;
+    else if (arg === '--help' || arg === '-h') { printHelp(); process.exit(0); }
+    else if (!arg.startsWith('-')) args.command = arg;
+  }
+  return args;
+}
+
+function printHelp() {
+  const platformList = Object.entries(PLATFORMS)
+    .map(([k, v]) => `    ${k.padEnd(10)} ${v.desc}`)
+    .join('\n');
+
+  console.log(`gitea-cli-skill - Install gitea-cli as an AI agent skill
+
+Usage:
+  npx gitea-cli-skill init [flags]
+
+Commands:
+  init              Install skill
+
+Flags:
+  --token <t>       Gitea API token (or set GITEA_TOKEN env var)
+  --host <url>      Gitea host URL (default: ${GITEA_HOST})
+  --local <dir>     Install from local goreleaser dist directory (skip download)
+  --platform <name> Target AI platform (default: claude)
+  --target <path>   Custom install directory (overrides --platform)
+  --force           Overwrite existing binary
+  -h, --help        Show this help
+
+Platforms:
+${platformList}
+
+Examples:
+  npx gitea-cli-skill init --local ../dist                     # from local build
+  npx gitea-cli-skill init --token abc123                      # from Gitea release
+  npx gitea-cli-skill init --token abc123 --platform cursor    # for Cursor
+  npx gitea-cli-skill init --local ../dist --target ~/custom   # custom dir
+`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  if (!args.command) { printHelp(); process.exit(0); }
+  if (args.command !== 'init') {
+    console.error(`Unknown command: ${args.command}`);
+    console.error('Run with --help for usage.');
+    process.exit(1);
+  }
+
+  // Validate platform name
+  if (args.platform && !PLATFORMS[args.platform] && !args.target) {
+    console.error(`Unknown platform: ${args.platform}`);
+    console.error(`Available: ${Object.keys(PLATFORMS).join(', ')}, or use --target for custom path.`);
+    process.exit(1);
+  }
+
+  await install(args);
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});