> For the complete documentation index, see [llms.txt](https://docs.githud.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.githud.net/command-interface/cli-reference.md). # CLI Reference ## CLI Reference `githud` is intentionally small. Rather than reimplementing every Git subcommand, it only handles the pieces that are genuinely DID-specific — identity generation and repo creation — and transparently forwards everything else to your system's real `git` binary. This section documents every command as implemented in `cli/src/main.rs`. > ℹ️ **Note:** As of this writing, the CLI hard-codes its API target to the hosted instance at `https://git.githud.net`. There is currently no flag or environment variable to point it at a self-hosted backend. ### Command Overview ``` githud Commands: auth Authentication commands repo Repository commands clone Clone a repository help Print this message or the help of the given subcommand(s) (any other subcommand is forwarded directly to `git`) ``` ### `githud auth new` Generates a brand-new Ed25519 keypair, derives a `did:key` from it, registers that DID with the Githood API, and persists both the DID and the private key to disk. ```bash githud auth new ``` **What it does, in order:** 1. Generates an Ed25519 keypair using the OS's secure random number generator (`OsRng`). 2. Derives the `did:key:z6Mk...` string from the public key. 3. Builds and signs the registration payload: `{timestamp}:/api/auth/register:{"did":"...","publicKey":"..."}`. 4. Sends `POST /api/auth/register` with the DID, hex-encoded public key, signature, and timestamp in the JSON body. 5. On success, writes: * `~/.githud/did.txt` — your DID, as plain text. * `~/.githud/id_ed25519.pem` — your private key, PKCS#8 PEM-encoded, with file permissions restricted to `0600` on Unix systems. **Sample output:** ``` ✓ DID generated: did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd Saved to: /home/you/.githud/did.txt ✓ Ed25519 private key generated Saved to: /home/you/.githud/id_ed25519.pem ✓ Registered with Githood API Git username: did_key_z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd ``` > ⚠️ **Warning:** Running `githud auth new` again **overwrites** your existing `~/.githud/did.txt` and `id_ed25519.pem` with a brand-new identity. There's no confirmation prompt. If you want to keep your existing identity, back up `~/.githud/` before re-running this command. ### `githud auth show` Prints your currently active DID. ```bash githud auth show # did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd ``` Reads directly from `~/.githud/did.txt`. If that file doesn't exist yet, the command fails with a reminder to run `githud auth new` first. ### `githud repo new ` Creates a new repository on Githood under your identity. ```bash githud repo new hello-world ``` **What it does, in order:** 1. Reads your DID and private key from `~/.githud/`. 2. Builds and signs the payload: `{timestamp}:/api/repos:{"name":"hello-world"}`. 3. Sends `POST /api/repos` with `x-did`, `x-timestamp`, and `x-signature` headers. 4. Prints the resulting `clone_url` on success. **Sample output:** ``` ✓ Repository created: hello-world Clone URL: http://localhost:9057/did:key:z6MkjRagNiMu91DduvCvgEsqLZDVzrJzFrwahc4tXLt9DoHd/hello-world.git ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Yes | The repository name. Gitea-side naming restrictions apply (alphanumeric, hyphens, underscores — avoid spaces and special characters). | ### `githud clone ` A thin wrapper that runs `git clone ` using your system's Git installation. ```bash githud clone "http://localhost:9057/did:key:z6Mk.../hello-world.git" ``` This exists mainly for symmetry with `repo new` and `auth new` — functionally it is identical to typing `git clone ` yourself. ### Passthrough: Any Other Git Command Any subcommand `githud` doesn't recognize is forwarded verbatim to `git`: ```bash githud status githud push githud log --oneline githud checkout -b feature/my-branch ``` Internally, this is implemented with Clap's `#[command(external_subcommand)]` attribute, capturing all unrecognized arguments and executing: ```rust Command::new("git").args(args).status() ``` The CLI's own exit code mirrors `git`'s exit code, so scripting against `githud` behaves exactly as scripting against `git` directly. > 💡 **Tip:** Because of this passthrough design, once you've cloned a repo with `githud clone` (or created one with `githud repo new` and manually run `git clone`), you can drop `githud` from your workflow entirely and just use `git` — the CLI's job is really just "get you set up," not "replace your Git client." ### Where Your Identity Lives on Disk | File | Contents | Permissions | | -------------------------- | ------------------------------------------ | --------------------------------------- | | `~/.githud/did.txt` | Your `did:key:z6Mk...` string, plain text. | Default (no special restriction). | | `~/.githud/id_ed25519.pem` | PKCS#8 PEM-encoded Ed25519 private key. | `0600` on Unix (owner read/write only). | > ⚠️ **Warning:** On Windows, the CLI does not currently set restrictive ACLs on `id_ed25519.pem` (the `0600` permission logic is gated behind `#[cfg(unix)]`). If you're on Windows, consider manually restricting access to your `~/.githud/` folder via file properties, especially on a shared machine. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.githud.net/command-interface/cli-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.