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
#code-review #git
Install
npx skills add https://github.com/magnus919/agent-skills/tree/main/forgejo-cli
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install magnus919-agent-skills@llmmart
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 --jsonemits one plan withmethod,path,query, andbody; it makes no network request.--jsonwrites exactly one JSON value to stdout; diagnostics go to stderr.--pageand--limitwork for any list/search request. Add--include-responseto receive the HTTP status pluslinkandx-total-countpagination headers.--helpdoes 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.
Reviews (0)
No reviews yet.
No comments yet.