OpenCommit CLI

mvdkleijn commented

2026-04-11 22:04:41 +02:00

Owner

1. What

The development of OpenCommit CLI, a command-line interface designed to provide a seamless transition for developers migrating from GitHub to our instance. The tool will replicate the core user experience and command structure of the gh (GitHub CLI), allowing users to perform essential repository operations (e.g., viewing issues, managing PRs, checking status) through a familiar syntax.

The technical approach involves utilizing the open source GitHub CLI (gh) as a functional foundation. Forking or refactoring its core architecture and re-implementing the API communication layer using the forgejo-sdk to interact with our OpenCommit API/Forgejo instance.

2. Why

The primary barrier to migrating from GitHub to an independent Forgejo-based instance is often "workflow friction". The loss of familiar tooling and command-line automation. By providing a CLI that mirrors the gh experience, we significantly lower the cognitive load and operational cost for developers moving their projects to our platform. This tool hopefully transforms the migration from a disruptive change into a simple reconfiguration of an existing, trusted workflow.

3. Boundaries

In-Scope:
- Forking/refactoring the GitHub CLI codebase to adapt its command structure for OpenCommit.
- Implementing authentication and configuration management (e.g., oc auth login) via forgejo-sdk.
- Mapping core gh commands (like gh issue list, gh pr create, gh repo view) to their equivalent Forgejo/OpenCommit API endpoints.
- Providing a "transition guide" specifically for users replacing gh with oc.
Out-of-Scope:
- Replicating the entirety of the GitHub CLI feature set (we will focus only on high-impact, common workflow commands).
- Building a full GUI or Web-based alternative to the CLI.
- Modifying the underlying Forgejo/OpenCommit API architecture itself (the CLI is a consumer, not a provider).

4. Definition of Done

Functional MVP: A working binary that allows users to authenticate and perform at least three core operations: viewing repository info, listing issues, and checking pull request status.
SDK Integration: Successful implementation of all API interactions using the forgejo-sdk to ensure native compatibility with our infrastructure.
Command Parity: Documentation exists showing a direct "translation table" (e.g., If you used gh issue list, now use oc issue list).
Seamless Authentication: A user can go from zero-config to an authenticated state using only the CLI, without needing manual browser-based token copying if possible.
Automated Testing: A suite of integration tests that verify command outputs match the expected API responses from the OpenCommit instance.

## 1. What The development of **OpenCommit CLI**, a command-line interface designed to provide a seamless transition for developers migrating from GitHub to our instance. The tool will replicate the core user experience and command structure of the `gh` (GitHub CLI), allowing users to perform essential repository operations (e.g., viewing issues, managing PRs, checking status) through a familiar syntax. The technical approach involves utilizing the open source **GitHub CLI (`gh`)** as a functional foundation. Forking or refactoring its core architecture and re-implementing the API communication layer using the `forgejo-sdk` to interact with our OpenCommit API/Forgejo instance. ## 2. Why The primary barrier to migrating from GitHub to an independent Forgejo-based instance is often "workflow friction". The loss of familiar tooling and command-line automation. By providing a CLI that mirrors the `gh` experience, we significantly lower the cognitive load and operational cost for developers moving their projects to our platform. This tool hopefully transforms the migration from a disruptive change into a simple reconfiguration of an existing, trusted workflow. ## 3. Boundaries * **In-Scope:** * Forking/refactoring the GitHub CLI codebase to adapt its command structure for OpenCommit. * Implementing authentication and configuration management (e.g., `oc auth login`) via `forgejo-sdk`. * Mapping core `gh` commands (like `gh issue list`, `gh pr create`, `gh repo view`) to their equivalent Forgejo/OpenCommit API endpoints. * Providing a "transition guide" specifically for users replacing `gh` with `oc`. * **Out-of-Scope:** * Replicating the *entirety* of the GitHub CLI feature set (we will focus only on high-impact, common workflow commands). * Building a full GUI or Web-based alternative to the CLI. * Modifying the underlying Forgejo/OpenCommit API architecture itself (the CLI is a consumer, not a provider). ## 4. Definition of Done * [x] **Functional MVP:** A working binary that allows users to authenticate and perform at least three core operations: viewing repository info, listing issues, and checking pull request status. * [x] **SDK Integration:** Successful implementation of all API interactions using the `forgejo-sdk` to ensure native compatibility with our infrastructure. * [ ] **Command Parity:** Documentation exists showing a direct "translation table" (e.g., *If you used `gh issue list`, now use `oc issue list`*). * [x] **Seamless Authentication:** A user can go from zero-config to an authenticated state using only the CLI, without needing manual browser-based token copying if possible. * [ ] **Automated Testing:** A suite of integration tests that verify command outputs match the expected API responses from the OpenCommit instance.

mvdkleijn added this to the Highlevel Roadmap project

2026-04-11 22:04:59 +02:00

mvdkleijn added the

labels

2026-04-11 23:03:21 +02:00

mvdkleijn changed title from ~~CLI~~ to OpenCommit CLI

2026-04-11 23:04:08 +02:00

mvdkleijn self-assigned this

2026-05-17 14:27:37 +02:00

mahlzahn commented

2026-08-04 18:03:18 +02:00

Check out also forgejo-cli, actively developed at https://codeberg.org/forgejo-contrib/forgejo-cli/. Maybe you don't even need to reinvent the wheel, but of course, you can, if you want to!

mvdkleijn commented

2026-08-04 21:33:40 +02:00

Author

Owner

@mahlzahn wrote in #5 (comment):

Check out also forgejo-cli, actively developed at https://codeberg.org/forgejo-contrib/forgejo-cli/. Maybe you don't even need to reinvent the wheel, but of course, you can, if you want to!

Hi @mahlzahn ! Thanks for the feedback. I do believe we looked at this one, together with a couple of other possible alternatives but decided against using these for various reasons. Including wanting room to use the CLI as a dog fooding vehicle for our platform, testing of mvdkleijn/forgejo-sdk and being able to customize the CLI to our platform if needed in some points.

@mahlzahn wrote in https://opencommit.eu/opencommit/roadmap/issues/5#issuecomment-231: > Check out also forgejo-cli, actively developed at https://codeberg.org/forgejo-contrib/forgejo-cli/. Maybe you don't even need to reinvent the wheel, but of course, you can, if you want to! Hi @mahlzahn ! Thanks for the feedback. I do believe we looked at this one, together with a couple of other possible alternatives but decided against using these for various reasons. Including wanting room to use the CLI as a dog fooding vehicle for our platform, testing of mvdkleijn/forgejo-sdk and being able to customize the CLI to our platform if needed in some points.

Rows
Columns

OpenCommit CLI #5

1. What

2. Why

3. Boundaries

4. Definition of Done