From bddb3309bd082afe3d989e440d3ca1f2b211a9ab Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 20 Jul 2026 20:44:55 +0000 Subject: [PATCH] docs: rewrite README for users and add CONTRIBUTING.md Split end-user install, auth, and command examples from contributor tooling. Closes #72. Co-authored-by: akae --- CONTRIBUTING.md | 126 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 126 +++++++++++++++++++++++++++++++++++++----------- 2 files changed, 223 insertions(+), 29 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e207f40 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,126 @@ +# Contributing + +Thanks for helping improve `github-rest-cli`. This guide covers local development, configuration, and quality tooling. + +## Prerequisites + +- Python 3.11.5+ +- [uv](https://docs.astral.sh/uv/) +- [just](https://github.com/casey/just) (optional, wraps common tasks) +- [Ruff](https://docs.astral.sh/ruff/) +- [pre-commit](https://pre-commit.com/) (optional) + +## Setup + +Clone the repository, sync dependencies, and activate the virtualenv: + +```shell +git clone https://github.com/lbrealdev/github-rest-cli.git +cd github-rest-cli +uv sync +source .venv/bin/activate +``` + +Install pre-commit hooks and Ruff (via just, if available): + +```shell +just setup-pre-commit +just setup-ruff +``` + +Or install them yourself: + +```shell +pre-commit install +uv tool install ruff +``` + +List installed packages: + +```shell +uv pip list +``` + +## Authentication for local runs + +Export a GitHub PAT the same way end users do: + +```shell +export GITHUB_AUTH_TOKEN="" +``` + +Run the CLI entrypoint: + +```shell +github-rest-cli --version +github-rest-cli --help +``` + +You can also profile a command: + +```shell +just profile --help +# or with arguments, e.g.: +just profile list-repo --format json +``` + +## Configuration (Dynaconf) + +The app uses [Dynaconf](https://www.dynaconf.com/) with `envvar_prefix="GITHUB"`. Settings can come from environment variables or from `settings.toml` / `.secrets.toml` (see `src/github_rest_cli/config.py`). + +List defined parameters: + +```shell +just dl +# equivalent: just dynaconf-list +``` + +Validate parameters: + +```shell +just dv +# equivalent: just dynaconf-validate +``` + +**Note:** Dynaconf validation expects `dynaconf_validators.toml` to exist at the project root. + +## Lint and format + +```shell +just lint +just fmt +``` + +Equivalent: + +```shell +ruff check . +ruff format . +``` + +## Tests + +```shell +just test +# equivalent: pytest -v +``` + +## Build and publish (maintainers) + +```shell +just build-local +just publish-local # requires PYPI_TOKEN +``` + +Clean the uv cache: + +```shell +just cache +``` + +## Pull requests + +1. Create a branch from `main` +2. Keep changes focused +3. Run lint and tests before opening a PR +4. Link related issues (for example, `Fixes #72`) diff --git a/README.md b/README.md index 5cddf0d..7a679d0 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,138 @@ -# GitHub REST API +# github-rest-cli + +[![PyPI](https://img.shields.io/pypi/v/github-rest-cli.svg)](https://pypi.org/project/github-rest-cli/) +[![Python CI](https://github.com/lbrealdev/github-rest-cli/actions/workflows/python-ci.yml/badge.svg)](https://github.com/lbrealdev/github-rest-cli/actions/workflows/python-ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +A Python CLI for common [GitHub REST API](https://docs.github.com/en/rest) operations—list and inspect repositories, create or delete them, manage Dependabot security settings, and create deployment environments. + +## Features + +- Get repository details (`get-repo`) +- List repositories for the authenticated user (`list-repo`) +- Create and delete repositories (`create-repo`, `delete-repo`) +- Enable or disable Dependabot security updates (`dependabot`) +- Create deployment environments (`environment`) +- Table or JSON output for repository listings (`--format`) ## Installation -Install using `pip`: +With `pip`: + ```shell pip install github-rest-cli ``` -Install using `uv`: +With `uv`: + ```shell uv pip install github-rest-cli ``` -## Usage +Requires Python 3.11.5 or newer. + +## Authentication + +Create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) and export it: -Set up python package dependencies in `pyproject.toml`: ```shell -uv sync +export GITHUB_AUTH_TOKEN="" ``` -After sync the project, activate virtualenv in `.venv` directory: +Suggested classic PAT scopes: + +| Scope | Used for | +| --- | --- | +| `repo` | Private repos, create/delete, environments, Dependabot settings | +| `public_repo` | Public repositories only (subset of `repo`) | +| `delete_repo` | Deleting repositories (included in full `repo` on classic tokens) | + +Fine-grained tokens need repository access with permissions for Contents, Administration (create/delete), Environments, and Dependabot/security alerts as needed. + +The CLI reads configuration via Dynaconf using the `GITHUB_` environment variable prefix (`GITHUB_AUTH_TOKEN` maps to `AUTH_TOKEN`). + +## Quick start + ```shell -source .venv/bin/activate +github-rest-cli --version +github-rest-cli --help ``` -To list all installed packages, run: +## Commands + +### Get a repository + ```shell -uv pip list +github-rest-cli get-repo --name my-repo +github-rest-cli get-repo --name my-repo --org my-org +github-rest-cli get-repo --name my-repo --format json ``` -Export your **GitHub PAT** as environment variable: +### List repositories + ```shell -export GITHUB_AUTH_TOKEN="" +github-rest-cli list-repo +github-rest-cli list-repo --page 50 --sort pushed +github-rest-cli list-repo --role owner --format json ``` -Run cli: +| Flag | Description | Default | +| --- | --- | --- | +| `-p` / `--page` | Number of results (`per_page`) | `20` | +| `-s` / `--sort` | Sort field (e.g. `pushed`, `updated`, `created`) | `pushed` | +| `-r` / `--role` | Filter by affiliation/role | unset | +| `-f` / `--format` | Output format: `table` or `json` | `table` | + +### Create a repository + ```shell -github-rest-cli -v +github-rest-cli create-repo --name my-new-repo +github-rest-cli create-repo --name my-new-repo --visibility private +github-rest-cli create-repo --name my-new-repo --org my-org +github-rest-cli create-repo --name my-new-repo --empty ``` -### Dynaconf +### Delete a repository -This python cli app uses dynaconf to manage secrets and environment variables. +```shell +github-rest-cli delete-repo --name my-repo +github-rest-cli delete-repo --name my-repo --org my-org +``` -So that you can use your secrets and environment variables declared in `settings.toml` or `.settings.toml`, use the `GITHUB` prefix value of `envvar_prefix` declared in config.py. +### Dependabot security updates -List all defined parameters: ```shell -just dl +github-rest-cli dependabot --name my-repo --enable +github-rest-cli dependabot --name my-repo --disable +github-rest-cli dependabot --name my-repo --org my-org --enable ``` -Validate all defined parameters: +### Deployment environments + ```shell -just dv +github-rest-cli environment --name my-repo --env production +github-rest-cli environment --name my-repo --env staging --org my-org ``` -**NOTE:** To run dynaconf validate `dynaconf_validators.toml` should exist. +## Output format -### Ruff +`get-repo` and `list-repo` support: -Run lint: -```shell -just lint -``` +- `table` (default) — PrettyTable display +- `json` — JSON string suitable for piping or scripting -Run format: ```shell -just fmt +github-rest-cli list-repo --format json +github-rest-cli get-repo --name my-repo --format table ``` + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, linting, and Dynaconf tooling. + +## Links + +- [PyPI](https://pypi.org/project/github-rest-cli/) +- [Source](https://github.com/lbrealdev/github-rest-cli) +- [Issues](https://github.com/lbrealdev/github-rest-cli/issues) +- [License](LICENSE)