# GitRepublic CLI

Command-line tools for GitRepublic: git wrapper with enhanced error messages, credential helper, commit signing hook, and API access.

> **Note**: This CLI is part of the `gitrepublic-web` monorepo but can also be used and published independently. See [SYNC.md](./SYNC.md) for information about syncing to a separate repository.

## Quick Start

```bash
# Install
npm install -g gitrepublic-cli

# Set your Nostr private key
export NOSTRGIT_SECRET_KEY="nsec1..."

# Setup (configures credential helper and commit hook)
gitrep-setup

# Use gitrepublic (or gitrep) for git operations and API access
# Run 'gitrep --help' for complete documentation and all available commands

# Note: "gitrep" is a shorter alias for "gitrepublic" - both work the same way.
# We suggest using "gitrepublic-web" as the remote name instead of "origin"
# because "origin" is often already set to GitHub, GitLab, or other services.
```

## Documentation

For complete CLI documentation and all available commands, run:
```bash
gitrep --help
```
or
```bash
gitrepublic --help
```

This will show:
- Initial setup instructions
- All git commands
- All API commands
- Repository management
- Publishing Nostr events
- Environment variables
- And much more

## Uninstall

```bash
# Remove all configuration
gitrep-uninstall

# See what would be removed (dry run)
gitrep-uninstall --dry-run

# Keep environment variables
gitrep-uninstall --keep-env
```

## Features

- **Git Wrapper**: Enhanced error messages for GitRepublic operations
- **Credential Helper**: Automatic NIP-98 authentication
- **Commit Signing**: Automatically sign commits for GitRepublic repos
- **API Access**: Full command-line access to all GitRepublic APIs
- **Profile Fetching**: Fetch user profiles with payment targets (NIP-A3 kind 10133)
  - Automatically merges lightning addresses from NIP-01 (lud16) and kind 10133
  - Returns payment targets in `payto://` format

## Requirements

- Node.js 18+
- Git
- Nostr private key (nsec format or hex)

## Commit Signing

The commit hook automatically signs **all commits** by default (GitHub, GitLab, GitRepublic, etc.). The signature is just text in the commit message and doesn't interfere with git operations.

**Note:** Commit signature events do not include the commit hash tag because:
- The commit-msg hook runs **before** the commit is created, so the hash doesn't exist yet
- Nostr events are **immutable** - once created and signed, they cannot be changed
  (changing tags would change the event ID and invalidate the signature)

Verification matches events to commits by comparing the commit message in the event's `message` tag with the actual commit message. This is secure because the signature proves the message was signed by the author.

To only sign GitRepublic repositories (skip GitHub/GitLab):

```bash
export GITREPUBLIC_SIGN_ONLY_GITREPUBLIC=true
```

To cancel commits if signing fails:

```bash
export GITREPUBLIC_CANCEL_ON_SIGN_FAIL=true
```

By default, the full event JSON is stored in `nostr/commit-signatures.jsonl` (JSON Lines format) for each signed commit. Events are organized by type in the `nostr/` folder for easy searching.

To also include the full event JSON in the commit message (base64 encoded):

```bash
export GITREPUBLIC_INCLUDE_FULL_EVENT=true
```

To publish commit signature events to Nostr relays:

```bash
export GITREPUBLIC_PUBLISH_EVENT=true
export NOSTR_RELAYS="wss://relay1.com,wss://relay2.com"  # Optional, has defaults
```


## Links

- [GitRepublic Web](https://github.com/silberengel/gitrepublic-web) - Full web application
- [NIP-98 Specification](https://github.com/nostr-protocol/nips/blob/master/98.md) - HTTP Authentication
- [Git Credential Helper Documentation](https://git-scm.com/docs/gitcredentials)

## License

MIT