Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- `gpg-key list` (alias `ls`) and `gpg-key add [<key-file>]` manage the GPG keys of your Copia account, as in `gh`. `list` reads every page of `GET /user/gpg_keys`: the columns EMAIL (the key's emails joined with `, `), KEY ID, PUBLIC KEY (cut in the middle on a terminal), ADDED and EXPIRES (`Never` or the date on a terminal, RFC 3339 without one); `--json` takes `id`, `key_id`, `primary_key_id`, `emails`, `public_key`, `created_at`, `expires_at`, `verified` and `can_sign`, with `--jq` and `--template`. No keys prints `no GPG keys present in the Copia account` on standard error, exit 0. `add` reads the armored key file, or standard input with `-` or without an argument when standard input is not a terminal, and sends it with `POST /user/gpg_keys`, then `GPG key added to your account`. Copia adds only a key whose email is a verified email of the account; its 404 for any other key is shown with a hint to add and verify that email (Copia has no `GET /user/gpg_key_token`, so Gitea's signature route and a `--signature` flag do not apply). A key Copia already has fails with `the key already exists in your account`; only public key blocks are sent: a private or secret key of any armored format (PGP, OpenSSH, PKCS#8, RSA, EC, DSA), also after a public block, is refused, and any other content fails with gh's hint that the key might not be ASCII-armored, both before any request. Copia's refusals are shown with the HTTP status and its message (cut to 512 bytes, read from at most 64 KiB of the response); a message that quotes the key, also re-wrapped or joined, is left out. gh's `-t/--title` is left out, since Gitea's GPG keys have no title (#482)
- `repo sync [-s/--source owner/repo] [-b/--branch branch] [--force]` syncs a branch of the local clone from a git remote, as `gh repo sync` does: the source is `--source` or the default repository (`-R`, `repo set-default`, else `origin`), the branch defaults to the source's default branch, `git fetch` gets the token only for an https remote on the configured host, and the branch is fast-forwarded (`merge --ff-only` when checked out, `branch --force` otherwise, created when missing). Diverging changes fail unless `--force` (`reset --hard`), and a dirty working tree is refused, both with gh's messages; success prints `Synced the "<branch>" branch from "<owner>/<repo>" to local repository`. `repo sync <owner/repo>` syncs a fork from its parent through `POST /repos/{owner}/{repo}/merge-upstream` fast-forward only; app.copia.io has no such route, so there it fails with `Copia does not offer fork sync through its API` (#45)
- `repo archive [<owner/repo>] --yes` and `repo unarchive [<owner/repo>] --yes` archive and unarchive the given repository, the current one or `-R`, as in `gh`: `PATCH /repos/{owner}/{repo}` with `archived`, then `Archived repository <owner>/<repo>` or `Unarchived repository <owner>/<repo>`. A repository already in that state gets `! Repository <owner>/<repo> is already archived` (or `is not archived`) on standard error, no change and exit 0; without `-y/--yes` both fail with `--yes required when not running interactively` before any API call. `repo view --json` gains the `archived` field (#462)
- `repo rename <new-name> --yes` renames the current repository or `-R`, as in `gh`: `PATCH /repos/{owner}/{repo}` with the new name, then `Renamed repository <owner>/<new-name>`. A name with `/` fails with gh's message and makes no API call; without `-y/--yes` it fails with `renaming <owner>/<repo> to <new-name> needs confirmation; use --yes to confirm`. Without `-R` the git remote that points at the old repository on the configured host (the `repo set-default` one first, then `origin`) gets the new name with `git remote set-url`, keeping its scheme, user, host and `.git` suffix, and `Updated the "<remote>" remote` is printed; when no remote matches or git fails, a warning goes to standard error and the command still succeeds (#461)
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,12 +85,12 @@ copia-cli/
Phase 1 (MVP): auth, repo list/view/clone, issue CRUD, pr CRUD, label list/create — **DONE**
Phase 2: release CRUD, repo create/delete/fork, pr review/diff/checkout, issue edit, Homebrew tap — **DONE**
Phase 3: `copia-cli api` escape hatch, search, orgs, notifications, `-R` flag, completion, Jekyll manual, AGPL license — **DONE**
Phase 4: ~~winget~~, ~~COPR~~, ~~AUR~~, ~~Snap~~, ~~OS keyring~~, ~~aliases~~, ~~browse~~, ~~status dashboard~~, ssh-key, pr checks, changelog, collaborators
Phase 4: ~~winget~~, ~~COPR~~, ~~AUR~~, ~~Snap~~, ~~OS keyring~~, ~~aliases~~, ~~browse~~, ~~status dashboard~~, gpg-key (list and add done; ssh-key dropped, Copia has SSH disabled), pr checks, changelog, collaborators

**Out of scope:** workflow/run, codespace, copilot, project, cache, GUI

## Reference Documentation

- `docs/api-reference.md` — Full Gitea API endpoint mapping with request/response examples
- `docs/authentication.md` — Auth methods, token generation, config file format, multi-instance setup
- `docs/parity.md` — Feature parity tracker against the Gitea 1.26 API (84 implementable: 76 implemented, 4 full, 4 partial; 13 impossible)
- `docs/parity.md` — Feature parity tracker against the Gitea 1.26 API (84 implementable: 78 implemented, 2 full, 4 partial; 15 impossible)
29 changes: 22 additions & 7 deletions docs/parity.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Token storage follows gh: `auth login` stores the token in the OS keyring (go-ke
| `gh repo edit` | Full | `copia-cli repo edit` | [x] |
| `gh repo set-default` | n/a | `copia-cli repo set-default` | [x] |
| `gh repo sync` | Partial | `copia-cli repo sync` | [x] |
| `gh repo deploy-key` | Full | `copia-cli repo deploy-key` | [ ] |
| `gh repo deploy-key` | None | n/a, app.copia.io has SSH disabled | — |

`gh repo view --web/-w`: client side, no API call and no token, opened as for the issue commands: `/{owner}/{repo}` of the argument, `-R` or the git remote. gh's `--branch` does not exist in `repo view`.

Expand All @@ -64,7 +64,7 @@ Token storage follows gh: `auth login` stores the token in the OS keyring (go-ke

`gh repo sync`: Partial. Without an argument it syncs the local clone with git, as gh does: the source is `-s/--source owner/repo` or the default repository (`-R`, the remote marked by `repo set-default`, else `origin`) and must be one of the git remotes (owner and name in any case), the branch is `-b/--branch` or the source's `default_branch` from `GET /repos/{owner}/{repo}`. `git fetch` of the branch from that remote gets the token only when the remote's URL is https on the configured host (the scoped credential helper of `repo clone`), then a checked-out branch is fast-forwarded with `merge --ff-only`, another one is moved with `branch --force`, a missing one is created tracking the remote. Diverged branches fail with gh's message unless `--force`, which uses `reset --hard`; a dirty working tree on the checked-out branch is refused with gh's message. With an argument (`owner/repo`) gh syncs a fork from its parent on the server. app.copia.io has no `/repos/{owner}/{repo}/merge-upstream` route: `POST` answers the plain-text `404 page not found` of an unknown path (found by the `integration` job of #45, 2026-11-07), so the remote mode reports `Copia does not offer fork sync through its API`, as Copia has no forks either (`gh repo fork`). Against a Gitea-compatible server that serves the route it sends `{"branch", "ff_only": true}` (the branch defaults to the repository's `default_branch`), prints `Synced the "<owner>:<branch>" branch from its parent` or that it is already up to date, and reports `<owner>/<repo> is not a fork` and diverging changes (gh's message, pointing at a local `--force`); `--force` and `-s/--source` are refused with an argument, since the endpoint only fast-forwards from the parent. Differences from gh: the success line is printed also without a terminal, and gh's worktree hints on a branch checked out in another worktree are left out (git's own error is shown).

`gh repo deploy-key`: `GET` and `POST /repos/{owner}/{repo}/keys`, `DELETE /repos/{owner}/{repo}/keys/{id}` for list, add and delete.
`gh repo deploy-key`: None on Copia. Gitea serves deploy keys at `/repos/{owner}/{repo}/keys`, but a deploy key only grants access over SSH, and app.copia.io has SSH disabled: it answers `POST /user/keys` with 422 `SSH is disabled` (found by the `integration` job of #487, 2026-11-08), see `gh ssh-key`.

## issue

Expand Down Expand Up @@ -194,6 +194,22 @@ Client side, no API call. The keys are `output` (`table` or `json`, default `tab

Client side, no API call. Aliases are stored under the top-level key `aliases` of `config.yml` and expanded before the command runs when the alias is the first argument, as in gh: `$1`, `$2` and so on take the arguments after the alias, otherwise they are appended, and an expansion that starts with `!` (or was set with `--shell/-s`) runs through `sh -c` with the arguments as `$1`, `$2`. Differences from gh: an argument fills a placeholder after the expansion is split into words, so it is never split again (gh replaces the placeholders in the text and splits afterwards); an alias name may not be empty, start with `-` or contain blanks, and the expansion of an alias that is no shell alias must start with a copia-cli command (gh also accepts an extension or another alias, which copia-cli does not have or expand); a built-in command also wins over an alias of the same name that was written into the config file by hand; `alias list` and `alias set`, `delete` and `import` print their messages whether or not the output is a terminal, and `alias import` exits with an error when it refused an alias, after it imported the others (gh exits 0).

## gpg-key

| gh command | Parity | Copia CLI | Status |
|-----------|--------|-----------|--------|
| `gh gpg-key list` | Full | `copia-cli gpg-key list` | [x] |
| `gh gpg-key add` | Full | `copia-cli gpg-key add` | [x] |
| `gh gpg-key delete` | Full | `copia-cli gpg-key delete` | [ ] |

The keys are those of the authenticated Copia account (`/user/gpg_keys`).

`gh gpg-key list`: every page of `GET /user/gpg_keys`. On a terminal the columns are gh's EMAIL (the key's emails joined with `, `; Gitea lists only the emails that are verified emails of the account), KEY ID, PUBLIC KEY (cut in the middle to fit the terminal width), ADDED (the time in words) and EXPIRES (`Never` or the date); without a terminal the same columns tab-separated without a header, the times in RFC 3339 as Gitea gives them. Gitea's `public_key` is its base64 encoding of the primary key packet, not the armored key. `--json` takes `id`, `key_id`, `primary_key_id`, `emails`, `public_key`, `created_at`, `expires_at`, `verified` and `can_sign` (gh has no `--json` here), with `--jq` and `--template`. No keys prints `no GPG keys present in the Copia account` on standard error and exits 0; with `--json` it prints `[]`.

`gh gpg-key add [<key-file>]`: reads the file, or standard input with `-` or without an argument when standard input is not a terminal (on a terminal it fails with gh's `GPG key file missing`), and sends it as `armored_public_key` with `POST /user/gpg_keys`, then `GPG key added to your account`, printed on standard output also without a terminal (gh prints it on a terminal only). Only public key blocks are sent: every line holding `-----BEGIN ` must be `-----BEGIN PGP PUBLIC KEY BLOCK-----`, and one must exist. A header that names `PRIVATE` or `SECRET` (a PGP private or secret key block, an OpenSSH, PKCS#8, RSA, EC or DSA private key, also after a public block) is refused with `the key file holds a private key`, any other content with gh's hint that the key might not be ASCII-armored (`gpg --armor --export <ID> | copia-cli gpg-key add -`), both before any request; gh sends both and reads the server's 422. Gitea's 422 `A key with the same id already exists` becomes gh's `the key already exists in your account`, exit 1. gh's `-t/--title` is left out: Gitea's GPG keys have no title.

Copia adds only a key whose email is a verified email of the account. For any other key Gitea answers 404 `None of the emails attached to the GPG key could be found. It may still be added if you provide a valid signature for the token: <token>`; copia-cli shows the first sentence with the HTTP status and a hint to add and verify the key's email in the Copia settings, never the token. Gitea's other route, a detached signature over the token of `GET /user/gpg_key_token` sent as `armored_signature`, does not exist on Copia: app.copia.io answers that route with Go's plain-text `404 page not found` (the route is not registered), so copia-cli has no `--signature` flag, like gh. Gitea's other refusals are shown with the HTTP status and Gitea's words, cut to 512 bytes and read from at most 64 KiB of the response (as for every paged list); a message that holds 16 bytes in a row of the key's material, compared without white space so a re-wrapped or joined quote counts, is left out and only the HTTP status is shown.

## Other implemented commands

| Command | Status |
Expand All @@ -214,8 +230,7 @@ Client side, no API call. Aliases are stored under the top-level key `aliases` o

| gh command group | Parity | Notes |
|-----------------|--------|-------|
| `gh ssh-key` | Full | `GET/POST /user/keys` |
| `gh gpg-key` | Full | `GET/POST /user/gpg_keys` |
| `gh ssh-key` | None | app.copia.io has SSH disabled: it answers `POST /user/keys` with 422 `SSH is disabled` (found by the `integration` job of #487, 2026-11-08), so an SSH key cannot be added and would grant nothing; Copia is reached over https only |
| `gh gist` | None | No Gitea equivalent |
| `gh workflow` | Full | `/repos/{owner}/{repo}/actions/workflows`: list, view, `run` (`/{workflow_id}/dispatches`), `enable`, `disable`. Whether Copia enables Actions is unknown |
| `gh run` | Partial | `/repos/{owner}/{repo}/actions/runs`: list, view, delete, `rerun` (`/rerun`, `/rerun-failed-jobs`, `/jobs/{job_id}/rerun`), job logs (`/actions/jobs/{job_id}/logs`), `download` (`/actions/artifacts`), `watch` by polling. No `cancel`: Gitea 1.26 has no endpoint for it. Whether Copia enables Actions is unknown |
Expand All @@ -235,10 +250,10 @@ Client side, no API call. Aliases are stored under the top-level key `aliases` o

| Status | Count |
|--------|-------|
| Implemented | 76 |
| Not yet implemented (Full parity) | 4 |
| Implemented | 78 |
| Not yet implemented (Full parity) | 2 |
| Not yet implemented (Partial) | 4 |
| No equivalent | 13 |
| No equivalent | 15 |
| **Total implementable** | **84** |

Counted from the rows above: every `[x]` row, and every other row by its Parity value. The Parity values follow the Gitea 1.26 API (`release/v1.26` swagger); `TestAPI_Version` in `test/integration/api_test.go` logs what Copia's `GET /version` reports in the PR `integration` job. On 2026-11-04 that was `0.59.0`, Copia's own version number, not a Gitea release, so the API does not show which Gitea version Copia is built on; a command's integration test shows whether Copia serves its endpoint.
9 changes: 6 additions & 3 deletions docs/project-layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ graph TB
search[search: issues/repos]
org[org: list/view]
notification[notification: list/read]
gpgkey[gpg-key: list/add]
browse[browse: open repo/issue/PR URL]
status[status: dashboard across repositories]
configcmd[config: get/set/list]
Expand All @@ -55,15 +56,15 @@ graph TB
copiacmd --> build
copiacmd --> config
factory --> iostreams
copiacmd --> auth & repo & issue & pr & label & release & apicmd & search & org & notification & browse & status & configcmd & aliascmd & completion
auth & repo & issue & pr & label & release & apicmd & search & org & notification & status --> factory
copiacmd --> auth & repo & issue & pr & label & release & apicmd & search & org & notification & gpgkey & browse & status & configcmd & aliascmd & completion
auth & repo & issue & pr & label & release & apicmd & search & org & notification & gpgkey & status --> factory
browse --> factory
configcmd --> factory
aliascmd --> factory
completion --> iostreams
auth & repo & issue & pr & label & release & apicmd & search & org & notification -.-> client
client --> gitea
httpmock -.-> auth & repo & issue & pr & label & release & apicmd & search & org & notification
httpmock -.-> auth & repo & issue & pr & label & release & apicmd & search & org & notification & gpgkey
integration --> gitea
```

Expand All @@ -90,6 +91,7 @@ copia-cli/
│ │ ├── search/ # issues, repos
│ │ ├── org/ # list, view
│ │ ├── notification/ # list, read
│ │ ├── gpgkey/ # list, add (the gpg-key group)
│ │ ├── browse/ # single command: browse [<number> | <path> | <commit-sha>]
│ │ ├── status/ # single command: status (gh's dashboard)
│ │ ├── config/ # get, set, list
Expand Down Expand Up @@ -196,6 +198,7 @@ func xxxRun(opts *XxxOptions) error { ... } // unexported, testable
| `search` | issues, repos | Raw HTTP |
| `org` | list, view | Raw HTTP |
| `notification` | list, read | Raw HTTP (read: PATCH one thread, PUT with `--all`) |
| `gpg-key` | list, add | Raw HTTP: `GET` and `POST /user/gpg_keys` |
| `browse` | none (single command `browse [<number> \| <path> \| <commit-sha>]`) | URL built client-side, opened with `cmdutil.Browser`; raw HTTP only for the default branch of a path and the last commit of `--commit` |
| `status` | none (single command `status`) | Raw HTTP: the issue search and the notifications |
| `config` | get, set, list | No API call; reads and writes the settings of `config.yml`, `set` validates before it saves |
Expand Down
4 changes: 4 additions & 0 deletions docs/site/_includes/sidebar.html
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,10 @@ <h5 class="mt-3 text-mono">
<li><a href="{{ '/manual/copia-cli_config_list' | relative_url }}" class="text-mono d-block">list</a></li>
<li><a href="{{ '/manual/copia-cli_config_set' | relative_url }}" class="text-mono d-block">set</a></li>

<li><h5 class="mt-3 text-mono"><a href="{{ '/manual/copia-cli_gpg-key' | relative_url }}" class="color-fg-default" style="font-weight:normal">gpg-key</a></h5></li>
<li><a href="{{ '/manual/copia-cli_gpg-key_add' | relative_url }}" class="text-mono d-block">add</a></li>
<li><a href="{{ '/manual/copia-cli_gpg-key_list' | relative_url }}" class="text-mono d-block">list</a></li>

<li><h5 class="mt-3 text-mono"><a href="{{ '/manual/copia-cli_issue' | relative_url }}" class="color-fg-default" style="font-weight:normal">issue</a></h5></li>
<li><a href="{{ '/manual/copia-cli_issue_close' | relative_url }}" class="text-mono d-block">close</a></li>
<li><a href="{{ '/manual/copia-cli_issue_comment' | relative_url }}" class="text-mono d-block">comment</a></li>
Expand Down
2 changes: 2 additions & 0 deletions internal/copiacmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ import (
browseCmd "github.com/qubernetic/copia-cli/pkg/cmd/browse"
completionCmd "github.com/qubernetic/copia-cli/pkg/cmd/completion"
configCmd "github.com/qubernetic/copia-cli/pkg/cmd/config"
gpgkeyCmd "github.com/qubernetic/copia-cli/pkg/cmd/gpgkey"
issueCmd "github.com/qubernetic/copia-cli/pkg/cmd/issue"
labelCmd "github.com/qubernetic/copia-cli/pkg/cmd/label"
notificationCmd "github.com/qubernetic/copia-cli/pkg/cmd/notification"
Expand Down Expand Up @@ -60,6 +61,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
cmd.AddCommand(searchCmd.NewCmdSearch(f))
cmd.AddCommand(orgCmd.NewCmdOrg(f))
cmd.AddCommand(notificationCmd.NewCmdNotification(f))
cmd.AddCommand(gpgkeyCmd.NewCmdGPGKey(f))
cmd.AddCommand(browseCmd.NewCmdBrowse(f))
cmd.AddCommand(statusCmd.NewCmdStatus(f))
cmd.AddCommand(configCmd.NewCmdConfig(f))
Expand Down
2 changes: 1 addition & 1 deletion internal/copiacmd/root_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ func TestNewRootCmd_RegistersCommands(t *testing.T) {
}
for _, want := range []string{
"auth", "repo", "issue", "label", "pr", "release",
"api", "search", "org", "notification", "browse", "status", "completion", "config", "alias",
"api", "search", "org", "notification", "browse", "status", "completion", "config", "alias", "gpg-key",
} {
assert.Contains(t, names, want)
}
Expand Down
Loading
Loading