214 lines
4.4 KiB
Markdown
214 lines
4.4 KiB
Markdown
# fgj - Forgejo CLI Tool
|
|
|
|
`fgj` is a command-line tool for working with Forgejo instances (including Codeberg.org). It brings pull requests, issues, and other Forgejo concepts to the terminal, similar to what `gh` does for GitHub.
|
|
|
|
## Features
|
|
|
|
- Multi-instance support (works with any Forgejo instance)
|
|
- Pull request management (create, list, view, merge)
|
|
- Issue tracking (create, list, view, comment, close)
|
|
- Repository operations (view, list, clone, fork)
|
|
- Secure authentication with personal access tokens
|
|
- AI coding agent friendly
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone https://codeberg.org/romaintb/fgj.git
|
|
cd fgj
|
|
go build -o fgj
|
|
sudo mv fgj /usr/local/bin/
|
|
```
|
|
|
|
### Using Go Install
|
|
|
|
```bash
|
|
go install codeberg.org/romaintb/fgj@latest
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### 1. Authenticate
|
|
|
|
First, authenticate with your Forgejo instance:
|
|
|
|
```bash
|
|
fgj auth login
|
|
```
|
|
|
|
You'll be prompted for:
|
|
- Forgejo instance hostname (default: codeberg.org)
|
|
- Personal access token
|
|
|
|
To create a personal access token:
|
|
1. Go to your Forgejo instance (e.g., https://codeberg.org)
|
|
2. Navigate to Settings > Applications > Generate New Token
|
|
3. Give it appropriate permissions (repo, issue, etc.)
|
|
4. Copy the token and paste it when prompted
|
|
|
|
### 2. Check Authentication Status
|
|
|
|
```bash
|
|
fgj auth status
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Pull Requests
|
|
|
|
```bash
|
|
# List pull requests
|
|
fgj pr list -R owner/repo
|
|
|
|
# View a specific pull request
|
|
fgj pr view 123 -R owner/repo
|
|
|
|
# Create a pull request
|
|
fgj pr create -R owner/repo -t "PR Title" -b "PR Description" -H feature-branch -B main
|
|
|
|
# Merge a pull request
|
|
fgj pr merge 123 -R owner/repo --merge-method squash
|
|
```
|
|
|
|
### Issues
|
|
|
|
```bash
|
|
# List issues
|
|
fgj issue list -R owner/repo
|
|
|
|
# View an issue
|
|
fgj issue view 456 -R owner/repo
|
|
|
|
# Create an issue
|
|
fgj issue create -R owner/repo -t "Issue Title" -b "Issue Description"
|
|
|
|
# Comment on an issue
|
|
fgj issue comment 456 -R owner/repo -b "My comment"
|
|
|
|
# Close an issue
|
|
fgj issue close 456 -R owner/repo
|
|
```
|
|
|
|
### Repositories
|
|
|
|
```bash
|
|
# View repository details
|
|
fgj repo view owner/repo
|
|
|
|
# List your repositories
|
|
fgj repo list
|
|
|
|
# Clone a repository
|
|
fgj repo clone owner/repo
|
|
|
|
# Clone via SSH
|
|
fgj repo clone owner/repo -p ssh
|
|
|
|
# Fork a repository
|
|
fgj repo fork owner/repo
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Configuration is stored in `~/.config/fgj/config.yaml`:
|
|
|
|
```yaml
|
|
hosts:
|
|
codeberg.org:
|
|
hostname: codeberg.org
|
|
token: your_token_here
|
|
user: your_username
|
|
git_protocol: https
|
|
my-forgejo.com:
|
|
hostname: my-forgejo.com
|
|
token: another_token
|
|
user: another_username
|
|
git_protocol: ssh
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
- `FGJ_HOST`: Override the default Forgejo instance
|
|
- `FGJ_TOKEN`: Provide authentication token
|
|
|
|
### Command-line Flags
|
|
|
|
- `--hostname`: Specify Forgejo instance for a command
|
|
- `--config`: Use a custom config file
|
|
|
|
## Use with AI Coding Agents
|
|
|
|
`fgj` is designed to work seamlessly with AI coding agents like Claude Code. Common patterns:
|
|
|
|
```bash
|
|
# Create PR from agent's changes
|
|
fgj pr create -R owner/repo -t "feat: add new feature" -b "$(cat <<EOF
|
|
## Summary
|
|
- Added new feature X
|
|
- Fixed bug Y
|
|
|
|
Generated with AI assistance
|
|
EOF
|
|
)"
|
|
|
|
# Check PR status during development
|
|
fgj pr list -R owner/repo --state open
|
|
|
|
# View PR details for review
|
|
fgj pr view 123 -R owner/repo
|
|
```
|
|
|
|
## Supported Forgejo Instances
|
|
|
|
`fgj` works with any Forgejo instance, including:
|
|
|
|
- [Codeberg.org](https://codeberg.org) (default)
|
|
- Self-hosted Forgejo instances
|
|
- Gitea instances (compatible API)
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
go build -o fgj
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
go test ./...
|
|
```
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
fgj/
|
|
├── cmd/ # Command implementations
|
|
│ ├── root.go # Root command and config
|
|
│ ├── auth.go # Authentication commands
|
|
│ ├── pr.go # Pull request commands
|
|
│ ├── issue.go # Issue commands
|
|
│ └── repo.go # Repository commands
|
|
├── internal/
|
|
│ ├── api/ # API client wrapper
|
|
│ └── config/ # Configuration management
|
|
├── main.go # Entry point
|
|
└── go.mod # Dependencies
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Acknowledgments
|
|
|
|
- Inspired by GitHub's `gh` CLI tool
|
|
- Built using the [Gitea SDK](https://code.gitea.io/sdk) (compatible with Forgejo)
|
|
- Uses [Cobra](https://github.com/spf13/cobra) for CLI framework
|