293 lines
6.3 KiB
Markdown
293 lines
6.3 KiB
Markdown
# fgj - Forgejo CLI Tool
|
|
|
|
[](https://golang.org)
|
|
[](https://codeberg.org/romaintb/fgj/actions)
|
|
[](LICENSE)
|
|
|
|
`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)
|
|
- Forgejo Actions (workflow runs, secrets, variables)
|
|
- Automatic repository detection from git context
|
|
- 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
|
|
|
|
### Repository Detection
|
|
|
|
`fgj` automatically detects the repository from your git context, similar to `gh`:
|
|
|
|
```bash
|
|
# When inside a git repository, no -R flag needed!
|
|
cd /path/to/your/repo
|
|
fgj pr list # Automatically uses current repo
|
|
fgj issue list # Automatically uses current repo
|
|
fgj pr view 123 # Automatically uses current repo
|
|
|
|
# Or explicitly specify a repository with -R
|
|
fgj pr list -R owner/repo
|
|
```
|
|
|
|
The tool reads `.git/config` to find the origin remote and extract the owner/repo information. If you're not in a git repository, you'll need to use the `-R` flag.
|
|
|
|
### Pull Requests
|
|
|
|
```bash
|
|
# List pull requests (auto-detects repo from git)
|
|
fgj pr list
|
|
|
|
# Or specify explicitly
|
|
fgj pr list -R owner/repo
|
|
|
|
# Filter by state
|
|
fgj pr list --state closed
|
|
|
|
# View a specific pull request
|
|
fgj pr view 123
|
|
|
|
# Create a pull request
|
|
fgj pr create -t "PR Title" -b "PR Description" -H feature-branch -B main
|
|
|
|
# Merge a pull request
|
|
fgj pr merge 123 --merge-method squash
|
|
```
|
|
|
|
### Issues
|
|
|
|
```bash
|
|
# List issues (auto-detects repo from git)
|
|
fgj issue list
|
|
|
|
# Or specify explicitly
|
|
fgj issue list -R owner/repo
|
|
|
|
# Filter by state
|
|
fgj issue list --state all
|
|
|
|
# View an issue
|
|
fgj issue view 456
|
|
|
|
# Create an issue
|
|
fgj issue create -t "Issue Title" -b "Issue Description"
|
|
|
|
# Comment on an issue
|
|
fgj issue comment 456 -b "My comment"
|
|
|
|
# Close an issue
|
|
fgj issue close 456
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
### Forgejo Actions
|
|
|
|
```bash
|
|
# List workflow runs
|
|
fgj actions run list
|
|
|
|
# View a specific run
|
|
fgj actions run view 123
|
|
|
|
# View run with job details
|
|
fgj actions run view 123 --verbose
|
|
|
|
# View run logs
|
|
fgj actions run view 123 --log
|
|
|
|
# View specific job logs
|
|
fgj actions run view 123 --job 456 --log
|
|
|
|
# List secrets
|
|
fgj actions secret list
|
|
|
|
# Create a secret
|
|
fgj actions secret create MY_SECRET
|
|
|
|
# Delete a secret
|
|
fgj actions secret delete MY_SECRET
|
|
|
|
# List variables
|
|
fgj actions variable list
|
|
|
|
# Get a variable
|
|
fgj actions variable get MY_VAR
|
|
|
|
# Create a variable
|
|
fgj actions variable create MY_VAR "value"
|
|
|
|
# Update a variable
|
|
fgj actions variable update MY_VAR "new value"
|
|
|
|
# Delete a variable
|
|
fgj actions variable delete MY_VAR
|
|
```
|
|
|
|
## 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
|
|
│ └── git/ # Git repository detection
|
|
├── 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
|