git-pages-cli
=============
_git-pages-cli_ is a command-line application for publishing sites to [git-pages].
> [!TIP]
> If you want to publish a site from a CI workflow, use the [Forgejo Action][git-pages-action] instead.
[git-pages]: https://codeberg.org/git-pages/git-pages
[git-pages-action]: https://codeberg.org/git-pages/action
Installation
------------
You can install _git-pages-cli_ using one of the following methods:
1. **Downloading a binary**. You can download the [latest build][latest] or pick a [release][releases].
1. **Installing a package**.
[](https://repology.org/project/git-pages-cli/versions)
1. **Using a Docker container**. Choose between the latest build or a [release tag][containers]. Then run:
```console
$ docker run --rm codeberg.org/git-pages/git-pages-cli:latest ...
```
1. **Installing from source**. First, install [Go](https://go.dev/) 1.25 or newer. Then run:
```console
$ go install codeberg.org/git-pages/git-pages-cli@latest
```
[latest]: https://codeberg.org/git-pages/git-pages-cli/releases/tag/latest
[releases]: https://codeberg.org/git-pages/git-pages-cli/releases
[containers]: https://codeberg.org/git-pages/-/packages/container/git-pages-cli/versions
Usage
-----
To prepare a DNS challenge for a given site and password:
```console
$ git-pages-cli https://example.org --challenge # generate a random password
password: 28a616f4-2fbe-456b-8456-056d1f38e815
_git-pages-challenge.example.org. 3600 IN TXT "a59ecb58f7256fc5afb6b96892501007b0b65d64f251b1aca749b0fca61d582c"
$ git-pages-cli https://example.org --password xyz --challenge
_git-pages-challenge.example.org. 3600 IN TXT "6c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8"
$ git-pages-cli https://example.org --password xyz --challenge-bare
6c47172c027b3c79358f9f8c110886baf4826d9bc2a1c7d0f439cc770ed42dc8
```
To publish a site from a git repository available on the internet (`--password` may be omitted if the repository is allowlisted via DNS):
```console
$ git-pages-cli https://example.org --upload-git https://codeberg.org/username/example.org.git
$ git-pages-cli https://example.org --password xyz --upload-git https://codeberg.org/username/example.org.git
```
To publish a site from a directory on your machine:
```console
$ git-pages-cli https://example.org --password xyz --upload-dir site-contents
```
To quickly create a redirect:
```console
$ git-pages-cli https://www.example.org --password xyz --redirect https://example.org
```
To delete a site:
```console
$ git-pages-cli https://example.org --password xyz --delete
```
All of the operations above also accept the `--dry-run` option, which checks authorization only and doesn't perform any destructive operations:
```console
$ git-pages-cli https://example.org --password zyx --delete --dry-run
result: error
unauthorized
```
It is not possible to publish a site to a domain for the first time using HTTPS, since the git-pages server is not allowed to acquire a TLS certificate for a domain before a site is published on that domain. Either use plain HTTP instead, or provide a hostname for which the server *does* have a TLS certificate using the `--server` option:
```console
$ git-pages-cli https://example.org --server grebedoc.dev --password xyz --upload-dir ...
```
If enabled by the server administrator, it is possible to publish ephemeral sites that get automatically removed (e.g. in 14 days in this example):
```console
$ git-pages-cli https://example.org --password xyz --upload-dir site-contents --expires 14
```
Certain hosting platforms, like GitHub Pages and Netlify, provide a built-in "pretty URL" feature, where `*.html` files can be accessed without the extension. For example, `/about.html` can be accessed as `/about` and/or `/about/`. To assist with migration from one of these platforms, a similar feature can be enabled when using `--upload-dir`:
```console
$ git-pages-cli https://example.org --password xyz --upload-dir site-contents --pretty-urls
```
The "pretty URL" feature is implemented entirely within _git-pages-cli_: this tool discovers every `*.html` file and generates appropriate `_redirects` file entries. If a `site-contents/_redirects` file exists, the generated redirect rules will be appended to its contents (so that user-defined rules take priority).
### Forge authorization
> [!IMPORTANT]
> If you are using Forgejo Actions, read the documentation for [git-pages/action](https://codeberg.org/git-pages/action) first.
Uploading a directory to a site on a wildcard domain (e.g. `https://.grebedoc.dev/`) requires the use of an access token with push permissions for the corresponding repository (`https://codeberg.org//.git` in this case).
To create such an access token on Forgejo:
1. Open _Settings_ > _Applications_ > _Access tokens_.
1. Expand _Select permissions_, then pick _Read_ under _user_ and _Read and write_ under _repository_.
1. Set _Token name_ to something informative (e.g. "git-pages publishing").
1. Click _Generate token_.
1. The token will appear in a notification (a long string of hexadecimal numbers all on its own).
To deploy using an access token:
```console
$ git-pages-cli https://username.grebedoc.dev --token --upload-dir ...
```
**Keep the access token safe and secure!** Anyone who has it will be able to change the data in any of your repositories.
### Specifying secrets
While secrets may be specified using the command-line arguments `--password` and `--token`, this is not always desirable. The alternatives to the `--password` flag are the `--password-file` flag and the `GIT_PAGES_PASSWORD` environment variable, and the alternative to the `--token` flag is the `GIT_PAGES_TOKEN` environment variable. When both the environment variable and the command-line argument are provided, the command-line argument takes priority.
Advanced usage
--------------
To retrieve the site manifest (for debugging only: manifest schema is not versioned and **subject to change without notice**, including renaming of existing fields):
```console
$ git-pages-cli https://example.org --password xyz --debug-manifest
{
"comment": "0000000000000000000000000000000000000000",
"contents": {
"": {
"type": "Directory"
},
"index.html": {
"type": "InlineFile",
"size": "5",
"data": "bWVvdwo=",
"contentType": "text/html; charset=utf-8"
}
},
"originalSize": "5",
"compressedSize": "5",
"storedSize": "0",
"redirects": [],
"headers": [],
"problems": []
}
```
To embed a free-form comment in the site manifest, for example to record the exact commit from which a site has been built:
```console
$ git-pages-cli https://example.org --password xyz --upload-dir site-contents --comment "$(git rev-parse HEAD)"
```
License
-------
[0-clause BSD](LICENSE.txt)