Metadata-Version: 2.4
Name: codeberg-cli
Version: 0.1.0
Summary: A Codeberg CLI
Project-URL: Homepage, https://codeberg.org/ThatXliner/codeberg-cli
Project-URL: Repository, https://codeberg.org/ThatXliner/codeberg-cli
Project-URL: Issues, https://codeberg.org/ThatXliner/codeberg-cli/issues
Author-email: Bryan Hu <thatxliner@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,codeberg,forgejo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.12
Requires-Dist: httpx
Requires-Dist: platformdirs
Requires-Dist: tomlkit
Requires-Dist: xclif>=0.4.3
Description-Content-Type: text/markdown

# cb — A Codeberg CLI

[![CI](https://github.com/ThatXliner/cb/actions/workflows/ci.yml/badge.svg)](https://github.com/ThatXliner/cb/actions/workflows/ci.yml) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/codeberg-cli)](https://pypi.org/project/codeberg-cli)
[![PyPI](https://img.shields.io/pypi/v/codeberg-cli)](https://pypi.org/project/codeberg-cli)
[![PyPI - License](https://img.shields.io/pypi/l/codeberg-cli)](#license)

`cb` is a native CLI for [Codeberg](https://codeberg.org) (a [Forgejo](https://forgejo.org) instance) — think `gh` for Codeberg. Built with [Xclif](https://xclif.readthedocs.io).

```text
# One-time setup
cb auth login

# Work with repos, issues, PRs, releases
cb repo list
cb issue create --title "Fix the thing"
cb pr create --base main --head fix
cb release create v0.2.0
```

## Install

```bash
pip install codeberg-cli  # or: uv tool install codeberg-cli
```

Or from source:

```bash
git clone https://codeberg.org/ThatXliner/codeberg-cli
cd cb
uv tool install .
```

## Quickstart

```bash
# Authenticate (tokens at https://codeberg.org/user/settings/applications)
cb auth login

# Who am I?
cb auth whoami

# List your repos
cb repo list

# Clone one
cb repo clone ThatXliner/cb

# Open an issue
cb issue create --title "suggestion" --body "what about..."
```

## Commands

### `cb auth` — authentication

| Command | Description |
|---------|-------------|
| `login` | Store a Codeberg access token |
| `logout` | Remove stored credentials |
| `status` | Show login state |
| `whoami` | Print current username |

### `cb repo` — repositories

Infer `owner/repo` from `git remote origin`. Override with `--repo`.

| Command | Description |
|---------|-------------|
| `create` | Create a repo (`--org`, `--private`, `--description`) |
| `list` | List repos for a user or org |
| `clone` | Clone via `git clone` |
| `view` | Show repo details (`--web` to open browser) |
| `fork` | Fork a repo |
| `delete` | Delete a repo (requires confirmation) |

### `cb label` — labels

| Command | Description |
|---------|-------------|
| `list` (alias: `ls`) | List repo labels |
| `create` | Create a label (`--color`, `--description`) |
| `delete` | Delete a label by ID |

### `cb milestone` — milestones

| Command | Description |
|---------|-------------|
| `list` (alias: `ls`) | List milestones (`--state`) |
| `create` | Create a milestone (`--description`, `--due-on`) |

### `cb issue` — issues

| Command | Description |
|---------|-------------|
| `create` | Create an issue (`--labels`, omit `--body` to open stdin) |
| `list` | List issues (`--state`, `--label`, `--limit`) |
| `view` | View an issue with comments (`--web`) |
| `close` | Close an issue |
| `reopen` | Reopen a closed issue |

### `cb pr` — pull requests

| Command | Description |
|---------|-------------|
| `create` | Open a PR (omit `--body` to open `$EDITOR`) |
| `list` | List PRs (alias: `ls`) |
| `view` | View a PR (`--web`) |
| `merge` | Merge with `--style merge|rebase|squash` |
| `checkout` | Fetch and checkout a PR locally (alias: `co`) |
| `close` | Close without merging |

### `cb release` — releases

| Command | Description |
|---------|-------------|
| `create` | Tag a release (`--prerelease`, `--draft`) |
| `list` | List releases |
| `view` | View a release (`--web`) |
| `upload` | Attach a file to a release |

### `cb api` — raw API access

```bash
cb api GET /version
cb api POST /repos/owner/repo/issues --data '{"title": "hi"}'
```

## Config

Token stored in `$XDG_CONFIG_HOME/cb/config.toml` (managed by `cb auth login` / `cb auth logout`).

## Comparison

There are two other CLI tools you can use with Codeberg:

| | **cb** | **fj** (forgejo-cli) | **berg** (codeberg-cli) |
|---|---|---|---|
| Language | Python | Rust | Rust |
| Codeberg-native | Yes (targets `codeberg.org/api/v1`) | Generic (any Forgejo instance) | Yes |
| Issues | create, list, view, close, reopen | open, edit, comment, close | yes |
| Pull requests | create, list, view, merge, checkout, close | create, merge | yes |
| Releases | create, list, view, upload | publish | — |
| Repos | create, list, clone, view, fork, delete | create, edit, star, watch | yes |
| Labels | create, list, delete | — | yes |
| Milestones | create, list | — | yes |
| Raw API | `cb api GET /path` | — | — |
| AGit PRs (no-fork) | — | yes | — |
| Org/team mgmt | — | yes | — |
| Install | `pip install codeberg-cli` | prebuilt binaries | `cargo install codeberg-cli` |
| Size | ~300 lines | Rust binary | Rust binary |

**Choose `fj`** if you self-host Forgejo or need org/team management. **Choose `berg`** if you want labels and milestones from a Rust binary. **Choose `cb`** if you want a minimal, readable Python CLI with release management and raw API access — `cb` is also the only one that uploads release assets.

## License

MIT
