Claude Skill

forgejo-cli

Use when managing a Forgejo or Gitea server from the terminal: issues, pull requests, repositories, file contents, labels, milestones, releases, webhooks, user settings, or any /api/v1 endpoint through a safe generic API command. Do not use this skill for unrelated requests; rout

LLM Mart · 0 points · 25 views 92 listing impressions 0 install-command copies

#code-review #git

Download magnus919-agent-skills-forgejo-cli-addad86.zip · 16 KB

Install

skills CLI npx skills add https://github.com/magnus919/agent-skills/tree/main/forgejo-cli
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install magnus919-agent-skills@llmmart
Git git clone https://github.com/magnus919/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole magnus919/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Forgejo CLI v2 — safe repository automation

Manage a Forgejo server from the terminal without hand-written curl or accidental mutations. It covers daily repository work—issues, pull requests, repositories, contents, metadata, webhooks, and settings—and has a guarded API escape hatch for the rest.

Why Install This Skill

The CLI gives agents one predictable safety contract: JSON is machine-readable, diagnostics stay off stdout, mutations require confirmation, and dry runs never need a token or network access. For version-specific features such as Actions runners and variables, packages, organizations, teams, admin APIs, notifications, and permissions, use the generic API command with your server's Swagger schema.

It deliberately does not try to duplicate every API endpoint. Instead, it offers guarded first-class commands for common repository work and a generic client for the rest. The references explain when to use each, how to select a compatible schema, and how to handle pagination and token scopes.

What You Get

Contents Purpose
scripts/forgejo-cli Argparse Forgejo API v1 client
references/command-reference.md Endpoint and payload guide
references/api-usage.md Authentication, pagination, versioning, and schema-discovery procedure
references/endpoint-routing.md Decision guide for first-class commands versus generic API calls
references/troubleshooting.md Safe diagnosis of API and transport failures
V2-SPEC.md v2 acceptance criteria
tests/ Offline stdlib contract tests

Quick Start

Set FORGEJO_AGENT_TOKEN (default) or FORGEJO_USER_TOKEN, then run:

python3 scripts/forgejo-cli --dry-run --json repo create --name demo --private
python3 scripts/forgejo-cli --server https://forge.example api --method GET --path /api/v1/user --json
python3 scripts/forgejo-cli --server https://forge.example --page 1 --limit 50 --include-response issue list --owner acme --repo app --json

Triggers

  • Managing Forgejo/Gitea issues, PRs, repos, file contents, releases, or hooks.
  • Calling a version-specific /api/v1/ endpoint safely.
  • Previewing a Forgejo mutation.

Requirements

Python 3.8+ and requests for live API calls. --help and --dry-run need no token or dependency. Set FORGEJO_AGENT_TOKEN or FORGEJO_USER_TOKEN for token authentication. A deliberate Authorization header supports other documented schemes, but avoid putting secrets directly in shell history. Consult your Forgejo server's /api/swagger or /swagger.v1.json for exact schemas.

Skill manifest

Forgejo CLI v2

Run python3 scripts/forgejo-cli. --agent (default) uses FORGEJO_AGENT_TOKEN; --user uses FORGEJO_USER_TOKEN; --server URL selects an installation. Set FORGEJO_SERVER in your shell if your wrapper supplies it, otherwise pass --server explicitly.

Safety

  • Mutations require --force/--yes/-y, or --dry-run.
  • --dry-run --json emits one plan with method, path, query, and body; it makes no network request.
  • --json writes exactly one JSON value to stdout; diagnostics go to stderr.
  • --page and --limit work for any list/search request. Add --include-response to receive the HTTP status plus link and x-total-count pagination headers.
  • --help does not read credentials or contact a server. Path segments are encoded.

Common workflows

python3 scripts/forgejo-cli issue list --owner acme --repo app --json
python3 scripts/forgejo-cli --dry-run --json repo create --name demo --private
python3 scripts/forgejo-cli --dry-run --json api --method POST \
  --path /api/v1/repos/acme/app/actions/variables --data '{"name":"KEY","value":"value"}'

First-class groups: issue, pr, repo, content, label, milestone, release, hook, and user. content expects base64 and update/delete require the current SHA. Use api for any other /api/v1/ endpoint; it supports JSON, raw files, multipart uploads/forms, and custom headers. Consult /api/swagger or /swagger.v1.json on the selected server. See command reference.

Choosing a command

Use a first-class command for its covered daily workflow. Use api when the operation is absent, requires version-specific fields, or needs a schema not represented by a simple flag. Before using api, read endpoint routing; read API usage for authentication, pagination, compatibility, and safe schema discovery. Read troubleshooting for 401/403/422 responses and transport failures.

Files (agent-skills)
  • evals
    • evals.json 2.8 KB
      Loading…
  • references
    • api-usage.md 2 KB
      Loading…
    • command-reference.md 3.8 KB
      Loading…
    • endpoint-routing.md 1.3 KB
      Loading…
    • troubleshooting.md 1.4 KB
      Loading…
  • scripts
    • forgejo-cli 21.3 KB · in bundle
  • tests
    • test_cli.py 5.5 KB
      Loading…
  • README.md 2.5 KB
    # Forgejo CLI v2 — safe repository automation
    
    Manage a Forgejo server from the terminal without hand-written `curl` or accidental mutations. It covers daily repository work—issues, pull requests, repositories, contents, metadata, webhooks, and settings—and has a guarded API escape hatch for the rest.
    
    ## Why Install This Skill
    
    The CLI gives agents one predictable safety contract: JSON is machine-readable, diagnostics stay off stdout, mutations require confirmation, and dry runs never need a token or network access. For version-specific features such as Actions runners and variables, packages, organizations, teams, admin APIs, notifications, and permissions, use the generic API command with your server's Swagger schema.
    
    It deliberately does not try to duplicate every API endpoint. Instead, it offers guarded first-class commands for common repository work and a generic client for the rest. The references explain when to use each, how to select a compatible schema, and how to handle pagination and token scopes.
    
    ## What You Get
    
    | Contents | Purpose |
    | --- | --- |
    | `scripts/forgejo-cli` | Argparse Forgejo API v1 client |
    | `references/command-reference.md` | Endpoint and payload guide |
    | `references/api-usage.md` | Authentication, pagination, versioning, and schema-discovery procedure |
    | `references/endpoint-routing.md` | Decision guide for first-class commands versus generic API calls |
    | `references/troubleshooting.md` | Safe diagnosis of API and transport failures |
    | `V2-SPEC.md` | v2 acceptance criteria |
    | `tests/` | Offline stdlib contract tests |
    
    ## Quick Start
    
    Set `FORGEJO_AGENT_TOKEN` (default) or `FORGEJO_USER_TOKEN`, then run:
    
    ```bash
    python3 scripts/forgejo-cli --dry-run --json repo create --name demo --private
    python3 scripts/forgejo-cli --server https://forge.example api --method GET --path /api/v1/user --json
    python3 scripts/forgejo-cli --server https://forge.example --page 1 --limit 50 --include-response issue list --owner acme --repo app --json
    ```
    
    ## Triggers
    
    - Managing Forgejo/Gitea issues, PRs, repos, file contents, releases, or hooks.
    - Calling a version-specific `/api/v1/` endpoint safely.
    - Previewing a Forgejo mutation.
    
    ## Requirements
    
    Python 3.8+ and `requests` for live API calls. `--help` and `--dry-run` need no token or dependency. Set `FORGEJO_AGENT_TOKEN` or `FORGEJO_USER_TOKEN` for token authentication. A deliberate `Authorization` header supports other documented schemes, but avoid putting secrets directly in shell history. Consult your Forgejo server's `/api/swagger` or `/swagger.v1.json` for exact schemas.
    
  • SKILL.md 2.5 KB
    ---
    name: forgejo-cli
    description: >-
      Use when managing a Forgejo or Gitea server from the terminal: issues, pull requests,
      repositories, file contents, labels, milestones, releases, webhooks, user settings, or
      any /api/v1 endpoint through a safe generic API command. Do not use this skill for
      unrelated requests; route to the nearest named specialist.
    license: MIT
    compatibility: Python 3.8+; requests is required only for live API calls.
    metadata:
      version: 2.0.0
      tags: forgejo, gitea, git, api, code-review
    ---
    
    # Forgejo CLI v2
    
    Run `python3 scripts/forgejo-cli`. `--agent` (default) uses `FORGEJO_AGENT_TOKEN`; `--user` uses `FORGEJO_USER_TOKEN`; `--server URL` selects an installation. Set `FORGEJO_SERVER` in your shell if your wrapper supplies it, otherwise pass `--server` explicitly.
    
    ## Safety
    
    - Mutations require `--force`/`--yes`/`-y`, or `--dry-run`.
    - `--dry-run --json` emits one plan with `method`, `path`, `query`, and `body`; it makes no network request.
    - `--json` writes exactly one JSON value to stdout; diagnostics go to stderr.
    - `--page` and `--limit` work for any list/search request. Add `--include-response` to receive the HTTP status plus `link` and `x-total-count` pagination headers.
    - `--help` does not read credentials or contact a server. Path segments are encoded.
    
    ## Common workflows
    
    ```bash
    python3 scripts/forgejo-cli issue list --owner acme --repo app --json
    python3 scripts/forgejo-cli --dry-run --json repo create --name demo --private
    python3 scripts/forgejo-cli --dry-run --json api --method POST \
      --path /api/v1/repos/acme/app/actions/variables --data '{"name":"KEY","value":"value"}'
    ```
    
    First-class groups: `issue`, `pr`, `repo`, `content`, `label`, `milestone`, `release`, `hook`, and `user`. `content` expects base64 and update/delete require the current SHA. Use `api` for any other `/api/v1/` endpoint; it supports JSON, raw files, multipart uploads/forms, and custom headers. Consult `/api/swagger` or `/swagger.v1.json` on the selected server. See [command reference](references/command-reference.md).
    
    ## Choosing a command
    
    Use a first-class command for its covered daily workflow. Use `api` when the operation is absent, requires version-specific fields, or needs a schema not represented by a simple flag. Before using `api`, read [endpoint routing](references/endpoint-routing.md); read [API usage](references/api-usage.md) for authentication, pagination, compatibility, and safe schema discovery. Read [troubleshooting](references/troubleshooting.md) for 401/403/422 responses and transport failures.
    
  • V2-SPEC.md 819 B
    Loading…

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.