ffj - A CLI for Forgejo and Codeberg

A Go CLI client for Forgejo and Codeberg, rewritten from the Rust forgejo-cli (fj) with improvements to debuggability, help text, configuration, and testability.

Features

• Comprehensive commands: Full coverage of Forgejo API with subcommands for repos, issues, PRs, releases, wiki, and more
• OAuth2 authentication: Secure browser-based login with PKCE flow
• Flexible configuration: TOML config file, environment variables, and command-line flags
• Debug modes: --verbose and --debug flags for troubleshooting
• Shell completion: Bash, Zsh, Fish, and PowerShell support
• Pure Go: No C dependencies, uses go-git for Git operations

Installation

From source

git clone https://codeberg.org/mutablecc/ffj-cli.git
cd ffj-cli
make install

Using Go

go install codeberg.org/mutablecc/ffj-cli@latest

Quick Start

1. Login to your instance:

   ffj auth login
   # or with explicit host
   ffj auth login https://codeberg.org
   

2. View your profile:

   ffj whoami
   

3. List repositories:

   ffj repo list owner/repo
   

4. Create an issue:

   ffj issue create owner/repo --title "Bug: something is broken"
   

Configuration

Configuration is loaded from (in order, later takes precedence):

1. Config file: ~/.config/ffj/config.toml
2. Environment variables: FJ_HOST, FJ_REMOTE, etc.
3. Command-line flags

Example ~/.config/ffj/config.toml:

[defaults]
host = "https://codeberg.org"
remote = "origin"
style = "auto"
[instances."codeberg.org"]
default-ssh = true

Authentication

• OAuth2 (recommended): ffj auth login - opens browser for authentication
• API token: ffj auth add-key <host> - enter token manually

Auth data is stored in ~/.local/share/ffj/keys.json (mode 0600).

Commands

Global Flags

Debugging

Use --verbose (-v) for human-friendly debugging:

• Elapsed time per operation
• Which host/remote/repo was resolved
• Authentication method used

Use --debug for full details:

• Full HTTP requests/responses
• Stack traces on errors

License

MIT