Automate ngit safely

ngit has an explicit machine interface. Agents should consume that interface instead of scraping terminal prose or inventing Nostr identifiers.

Owned by ngit + ngit-docsVerified ngit 3.0.3 @ 31e48be58ee3automation contract

Install repository guidance

Maintainers can install ngit's bundled skill into a repository:

ngit skill install
ngit skill status
ngit skill upgrade

The skill teaches supported collaboration commands and adds a compact pointer to existing agent instruction files. Installation and upgrades leave managed files uncommitted so the repository's normal validation and commit workflow can run. Contributors who are not maintainers should commit the changes on a pr/ branch and push it to propose a pull request. With --json, changed_files lists the non-ignored managed paths that remain as Git changes and changes_uncommitted says whether there is anything to commit.

Stable output

Always add --json when an agent reads an ngit command:

ngit pr list --json
ngit issue view nevent1… --comments --json --offline

stdout contains exactly one JSON document after the command finishes. Relay progress and human diagnostics stay on stderr. Native git commands do not support this flag.

Add global --quiet when non-essential stderr progress and notices are not useful. It does not hide primary results, warnings, or failures, and it cannot be combined with --verbose.

Cache-aware reads

Use the network for the first ngit read in a session, then prefer --offline while the local event cache is fresh:

ngit repo --json
ngit pr list --json --offline
ngit issue list --json --offline

git fetch origin also refreshes repository state and cache data.

Select the repository explicitly

When multiple nostr:// remotes identify different repositories, pass a remote name, naddr, or Nostr URL:

ngit --repo upstream issue list --json
ngit pr --repo upstream list --json --offline

Before a signing command, check the target repository diagnostic on stderr. ngit fails rather than guessing when selection is ambiguous.

Use returned identifiers

JSON id and reply_to fields use nevent1…. Pass the complete value back to <ID|nevent> parameters. Within a Markdown body, prefix it with nostr::

ngit issue comment nevent1… \
  --body "Related to nostr:nevent1…" \
  --json

Never fabricate NIP-05 names. Use an npub1… unless a NIP-05 address was explicitly provided.

Select signers without exposing secrets

ngit --signer alice issue create \
  --subject "Bug" \
  --body "Details" \
  --json

git -c nostr.signer=alice push origin pr/fix

For CI, prefer protected ephemeral files: --nsec-file for a dedicated local key or --nbunksec-file for an established remote-signer connection. Pair and export a remote signer for CI covers the bunker:// and nostrconnect:// flows, nbunksec export, and removal of the workstation copy. Do not export an identity's nsec merely to switch between configured identities.

Machine-readable documentation

The built site publishes:

Endpoint	Purpose
/llms.txt	Curated page index with short descriptions.
/llms-full.txt	All public Markdown in one bounded, grep-friendly document.
/api/docs-manifest.json	Page URLs, raw Markdown URLs, owners, source repos, and verified versions.
/markdown/<route>.md	Raw source for an individual public page.
/api/ngit/3.0.3/cli.json	Complete stable 3.0.3 command schema.
/api/ngit-grasp/3.0.4/reference.json	Stable ngit-grasp command and configuration schema.
/api/ngit-ci/upcoming/manifest.json	Version 0.1.1 coordinator and microVM adapter artifact index.
/api/gitworkshop/4.1.0/manifest.json	Exact-tag version, changelog, and release-publication evidence for GitWorkshop v4.

Use the manifest to discover content and the raw Markdown endpoint to retrieve only the required page. The HTML site remains the canonical human experience; these outputs are deterministic views of the same source.

The guide index connects human tasks to these source-generated facts.