forgejo-cli is a small command-line client for Forgejo API operations. It is intended for humans at a shell and for AI agents that need predictable command examples, placeholder-safe configuration, and file-based request bodies.

Install the CLI with Go:

go install github.com/oduan/forgejo-cli/cmd/forgejo@latest

Confirm the binary is on your PATH:

forgejo

Prebuilt release binaries are published from the GitHub releases page:

https://github.com/oduan/forgejo-cli/releases

Download the archive for your operating system and architecture. Before running downloaded binaries, verify the archive against the release checksum file, such as checksums-*.txt, from the same GitHub release. After integrity verification, extract the forgejo binary and place it on your PATH.

Set the Forgejo base URL and access token before running resource commands. Use placeholders in shared documentation and scripts; substitute your real values only in your local shell or secret manager.

forgejo config set-url <forgejo-base-url>
forgejo config set-token <access-token>

Useful configuration commands:

forgejo config path
forgejo config get-url
forgejo config token-status
forgejo config get-token
forgejo config unset-token

Use forgejo config token-status for automation and agent checks; it prints only configured or missing and never reveals the token. forgejo config get-token is for a human's explicit secret reveal only.

By default, configuration is stored in the current user's config directory under forgejo-cli/config.json. Set FORGEJO_CLI_CONFIG to use a different config file path for tests, automation, or isolated agent runs.

Resource commands follow this shape:

forgejo <resource> <action> [path-args...] [request-options...]

Examples:

forgejo user current
forgejo repo get <owner> <repo>
forgejo issue list <owner> <repo> --query state=open
forgejo issue create <owner> <repo> --body @issue.json

Run a resource without an action to list available actions for that resource:

forgejo issue

The CLI supports generic request options that map to API path parameters, query parameters, and request bodies.

• Positional arguments fill path parameters in order.
• --query key=value adds one query parameter. Repeat it for multiple query parameters.
• --body @file.json reads the request body from a file.
• --body - reads the request body from standard input.
• --body-json '{"key":"value"}' sends an inline JSON body.
• --fields title,number filters JSON output to only the fields needed by the current task.
• --fields-help shows response fields available for a resource action without making an API request.

Examples:

forgejo issue list <owner> <repo> --query state=open --query page=1 --query limit=50
forgejo issue list <owner> <repo> --query page=1 --query limit=50 --fields title
forgejo issue list --fields-help
forgejo issue create <owner> <repo> --body @issue.json
printf '{"title":"Example"}' | forgejo issue create <owner> <repo> --body -

List and search commands can return many items. Request pages explicitly with --query page=1 --query limit=50, then increment page until the API returns fewer items than the requested limit or otherwise indicates there are no more results.

Use --fields-help before choosing fields when you are not sure what a command returns:

forgejo issue list --fields-help

When exploring large lists, request only the fields needed. For example, get only issue titles with:

forgejo issue list <owner> <repo> --query page=1 --query limit=50 --fields title

For triage, prefer a compact list such as:

forgejo issue list <owner> <repo> --query page=1 --query limit=50 --fields number,title,state,updated_at

Do not fetch issue bodies in list commands unless the body is required for the current task. If a specific issue needs body text, comments, or full metadata, fetch the specific issue detail after identifying it from a paginated minimal list.

This repository includes an agent skill at skills/forgejo-cli. Install it into the skill directory used by your agent so the agent can discover command conventions and safe placeholder usage.

Generic installation guidance:

1. Clone or inspect https://github.com/oduan/forgejo-cli.
2. Copy skills/forgejo-cli into the skill directory supported by your agent.
3. For generic agents, prefer project-local .agents/skills/forgejo-cli when no platform-specific directory is documented.
4. For Craft Agent, install into the workspace skills directory.
5. For Claude Code, Codex, and OpenClaw, follow each tool's documented skill directory, preserving the folder name forgejo-cli and the SKILL.md file.

Notes for common agent tools:

• Craft Agent: install the skills/forgejo-cli folder into the workspace skills directory.
• Claude Code: follow Claude Code's documented skill installation location and keep the folder name forgejo-cli.
• Codex: follow Codex's documented skill installation location and keep the folder name forgejo-cli.
• OpenClaw: follow OpenClaw's documented skill installation location and keep the folder name forgejo-cli.
• Generic or repository-local agents can use .agents/skills/forgejo-cli when no more specific directory is documented.

Do not commit access tokens, generated config files, or real service URLs into agent instructions.

Run the test suite before committing changes:

go test ./...

For isolated manual checks, point the CLI at a temporary config file:

FORGEJO_CLI_CONFIG=/tmp/forgejo-cli-config.json forgejo config set-url <forgejo-base-url>
FORGEJO_CLI_CONFIG=/tmp/forgejo-cli-config.json forgejo config set-token <access-token>

Keep examples placeholder-safe. Documentation should use <forgejo-base-url>, <access-token>, <owner>, and <repo> instead of concrete deployment details. Only document forgejo config set-url examples with <forgejo-base-url>; do not use schemes, hostnames, host:port values, local addresses, or service-specific domains in shared examples.

1. Ensure go test ./... passes.
2. Update release notes with user-facing CLI changes.
3. Tag the release in Git.
4. Publish binaries and notes at https://github.com/oduan/forgejo-cli/releases.
5. Verify installation instructions still reference github.com/oduan/forgejo-cli and do not include concrete Forgejo service addresses.