CLI and local API

Manage the same service through an authenticated Unix socket.

Operator credentials

The CLI uses the daemon's private management socket and a private operator token file. Run it as the authorized daemon identity. Never place a token in a URL, shell argument, source checkout or browser. The fresh installer writes its initial token privately under DATA_ROOT/control/operator-token and does not print it.

Status and API calls

gitsvc --config /etc/gitsvc/config.toml status \
  --token-file /secure/operator-token

gitsvc api GET /v1/repositories \
  --token-file /secure/operator-token

Use gitsvc [--config FILE] api METHOD PATH. JSON bodies accept --json or --body-file. Versioned updates require --if-match VERSION; durable operations require a stable --idempotency-key. Follow paginated next_after values even if policy filtering leaves the current page empty.

Enroll an existing email

As a service operator, first retrieve the existing user and current version, then patch that identity:

gitsvc api GET /v1/users --token-file /secure/operator-token
gitsvc api PATCH /v1/users/USER_UUID \
  --token-file /secure/operator-token \
  --if-match VERSION --json '{"email":"person@example.com"}'

This preserves the identity and its memberships. It invalidates pending codes and browser sessions. Do not create a replacement identity to repair enrollment.

Durable operations

Create/import/export and lifecycle calls return operation IDs. Poll GET /v1/operations/ID until completed or failed. Reusing the same idempotency key with the same request returns the original result; changing the request conflicts. An accepted replay does not mean the underlying work finished.

Other commands

init, install-hooks, stage, download and recover are separate operator commands. The essentials update adds offline backup create, backup verify and backup restore; these require the maintenance and inventory procedures in backup and recovery.

Use gitsvc --help and each subcommand's --help for arguments. The complete API and bundle reference lists routes, body fields, version rules, limits and error behavior. The operator API stays on a Unix socket; do not expose it through your HTTPS proxy.