No description
  • TypeScript 90.9%
  • JavaScript 8.2%
  • Shell 0.5%
  • PowerShell 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Forgejo Desktop Bot 9f4dc6c545 chore: prepare release
2026-10-20 23:02:14 +00:00
.github/workflows fix: resolve nested quote issues in YAML to allow Forgejo to parse workflow 2026-10-20 18:53:44 -04:00
src Update actions 2026-10-20 22:39:26 +00:00
tests Add navigable Dashboard diff preview 2026-10-20 20:52:24 +00:00
.gitignore First Push 2026-10-19 19:43:00 +00:00
install.ps1 Updated installers to support Bun 2026-10-20 21:28:33 +00:00
install.sh Updated installers to support Bun 2026-10-20 21:28:33 +00:00
package-lock.json chore: prepare release 2026-10-20 23:02:14 +00:00
package.json chore: prepare release 2026-10-20 23:02:14 +00:00
README.md docs: restructure and improve README with better organization, badges, and clearer sections 2026-10-20 19:01:35 -04:00
tsconfig.json First Push 2026-10-19 19:43:00 +00:00

Forgejo Desktop CLI

License: MIT Node.js Version Platform

fjd is a terminal-first companion for Git repositories hosted on Forgejo and Gitea-compatible servers. It provides a full-screen, keyboard-driven TUI for managing your repositories alongside Forgejo pull requests, issues, releases, Actions, notifications, and more.

Features

  • Interactive TUI: Full-screen terminal interface with keyboard navigation
  • Git Operations: Clone, status, stage, commit, push, pull, sync, and more
  • Forgejo Integration: Browse repositories, PRs, issues, releases, and Actions
  • Authentication: Support for personal access tokens and username/password login
  • GitHub Copilot: AI-powered commit message generation (optional)
  • Themes: Multiple color themes (Ocean, Forest, Sunset, Violet)
  • Auto-updates: Built-in update checking and self-update capability
  • Secure: Credentials stored with restrictive permissions; passwords never saved

Requirements

  • Node.js 20 or newer
  • Bun 1.3.14 or newer (for TUI)
  • Git
  • curl (for Linux one-line installer)
  • A Forgejo/Gitea account and personal access token for API features

Installation

Quick Install

Install the latest version with a single command:

Linux/macOS:

curl -fsSL https://forgejo.hexium.cc/WilliamTheFatMan/Forgejo-Desktop/raw/branch/main/install.sh | sh

Windows (PowerShell):

irm https://forgejo.hexium.cc/WilliamTheFatMan/Forgejo-Desktop/raw/branch/main/install.ps1 | iex

Both installers require Git, Node.js 20+ with npm, and Bun 1.3.14+. They build the CLI and install fjd globally.

From Source

git clone https://forgejo.hexium.cc/WilliamTheFatMan/Forgejo-Desktop.git
cd Forgejo-Desktop
npm install
npm run build
npm link

Uninstall

Remove fjd and all its data:

fjd uninstall

Add --yes to skip confirmation.

Authentication

Interactive Login

Configure a host interactively. Choose either a personal access token or username/password:

fjd auth login --host https://codeberg.org

Username/password: Asks Forgejo to mint a personal access token for fjd. The password itself is never saved. This requires the host to allow password-based API authentication and token creation.

Personal access token: If password authentication is disabled, create a token in the web interface and select the token option.

Pre-select Username

fjd auth login --host https://forge.example --username alice

Environment Variable

Provide a token from the environment without saving it:

FJD_TOKEN=your-token fjd --host https://forge.example repo list

Managing Credentials

  • fjd auth status - View authentication status
  • fjd auth logout - Sign out of a host
  • fjd config path - Show configuration file location

Tokens are saved with restrictive permissions. FORGEJO_TOKEN and GITEA_TOKEN environment variables are also accepted.

Usage

Interactive TUI

Launch the full-screen interface:

fjd
# or
fjd ui

Start directly in a specific section:

fjd ui --screen "Pull requests"

TUI Keyboard Shortcuts

Navigation:

  • ↑/↓ or j/k - Move through items
  • Tab - Switch between sections
  • Enter - Open selected item
  • Escape - Go back
  • r - Refresh
  • ? - Show all shortcuts
  • q - Quit

Dashboard (Git operations):

  • f - Fetch
  • p - Pull
  • P - Push
  • c - Commit
  • s - Stage/unstage selected file
  • S - Stage all changes (or unstage all if files are staged)
  • g - Generate commit message with GitHub Copilot

Settings:

  • t - Cycle color themes (Ocean, Forest, Sunset, Violet)
  • l - Login to Copilot CLI

Git Workflow

Run fjd inside a Git checkout, or specify a directory with -C <directory>:

fjd clone owner/project
fjd status
fjd stage src/
fjd commit -m "Describe the change"
fjd push --set-upstream
fjd sync

Forgejo Commands

After authenticating, you can browse and manage:

fjd repo list                    # List repositories
fjd pr list                      # List pull requests
fjd issue list                   # List issues
fjd release list                 # List releases
fjd actions list                 # List workflow runs
fjd notification list            # List notifications

Most commands accept --json for structured output and --web to open in the browser.

Linking a Repository

Associate an existing checkout with a Forgejo repository:

fjd link --host https://forge.example --owner OWNER --repo REPO

Git remotes remain ordinary Git remotes, so Git's configured credential helpers and SSH agent are respected.

Command Groups

fjd auth           Authentication and token management
fjd repo           Repository browsing and management
fjd pr             Pull requests, reviews, and checkout
fjd issue          Issue management
fjd release        Releases and assets
fjd actions        Workflow runs and tasks
fjd notification   Notification management
fjd branch         Branch management
fjd --help         All top-level commands

Updates

fjd checks for updates at each TUI launch and at most once daily for regular commands. When an update is available:

fjd self-update

Disable update checking:

export FJD_NO_UPDATE_CHECK=1

Development

# Install dependencies
npm install

# Type checking
npm run typecheck

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev

Configuration

The configuration file is stored in your user directory. View its location:

fjd config path

Color Themes

Available themes:

  • Ocean (default)
  • Forest
  • Sunset
  • Violet

Change themes in the TUI Settings section by selecting Color theme and pressing t.

GitHub Copilot Integration

Generate commit messages with AI using GitHub Copilot CLI:

  1. Install and authenticate Copilot CLI:

    copilot login
    

    Or use the TUI Settings section to run the interactive login.

  2. In the TUI Dashboard, press g to generate a commit message from staged changes.

  3. Review the suggestion, then confirm, edit, or cancel.

The staged diff is sent to GitHub Copilot to generate the suggestion. You can enable/disable Copilot commit drafts in Settings.

Security

  • Passwords are never saved; only Forgejo-issued access tokens are stored
  • Tokens are saved with restrictive file permissions
  • For HTTPS remotes on configured hosts, fjd push uses the saved token through a temporary Git credential helper
  • SSH remotes continue to use your SSH agent and keys
  • Destructive TUI actions require confirmation
  • Destructive CLI commands prompt in interactive use and require --yes when run without a terminal

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues, questions, or feature requests, please open an issue on the Forgejo repository.