- TypeScript 90.9%
- JavaScript 8.2%
- Shell 0.5%
- PowerShell 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .github/workflows | ||
| src | ||
| tests | ||
| .gitignore | ||
| install.ps1 | ||
| install.sh | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
Forgejo Desktop CLI
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 statusfjd auth logout- Sign out of a hostfjd 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:
↑/↓orj/k- Move through itemsTab- Switch between sectionsEnter- Open selected itemEscape- Go backr- Refresh?- Show all shortcutsq- Quit
Dashboard (Git operations):
f- Fetchp- PullP- Pushc- Commits- Stage/unstage selected fileS- 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:
-
Install and authenticate Copilot CLI:
copilot loginOr use the TUI Settings section to run the interactive login.
-
In the TUI Dashboard, press
gto generate a commit message from staged changes. -
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 pushuses 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
--yeswhen 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.