Command-Line Usage

Options

The n34 command-line tool accepts the following options:

• -s, --secret-key: Your Nostr secret key (in nsec format), used for signing events.
• -b, --bunker-url: The URL of a NIP-46 bunker service used for remote signing of events.
• -7, --nip07: Enables signing events using the browser's NIP-07 extension. Listens on 127.0.0.1:51034. You can configure the address with n34 config nip07
• -r, --relays: A relay to read from and write to. This option can be specified multiple times to connect to several relays.
• --pow: Sets the Proof of Work difficulty required when creating events.
• --config: Specifies a custom path to the configuration file (Default: $HOME/.config/n34/config.toml).
• -v, --verbose...: Increases the logging verbosity. Can be used multiple times for more detail (e.g., -v, -vv).

Note: The --secret-key and --bunker-url options are mutually exclusive. You must provide exactly one signing method.

Multiple Repositories

Commands that interact with a repository, such as submitting an issue or a patch, can accept multiple repository addresses (naddr). This feature is useful for projects with multiple maintainers who each have their own repository fork.

Important: When you provide multiple repositories, n34 does not create a separate issue or patch for each one. Instead, it creates a single event that references all of the specified repositories.

The nostr-address File

The nostr-address file is a plain text file that stores a list of project repository addresses. This allows the n34 to find and use them without requiring you to enter the addresses manually.

Format

• Each line must contain a single addressable event coordinate naddr which is the repository address.
• Lines beginning with a # are treated as comments and are ignored.
• Empty lines are also ignored.

Passing repositories

By default, n34 will look for a nostr-address file to extract repositories from it. This is why repositories are not required for commands like patch send and issue new. You can also pass repositories using the --repo option or the <NADDR-NIP05-OR-SET> argument for commands that accept them. The supported formats for manual input are:

• A NIP-19 addressable event coordinate naddr.
• A NIP-05 identifier and repository name, in the format <nip05>/<repo-name>.
• A set name that contains repository addresses.

You do not need to specify relays for these commands if your naddr or NIP-05 identifier already includes relays; n34 will automatically extract them.

Managing Repository and Relay Sets

Sets are a convenience feature for contributing to projects that do not have a nostr-address file. Instead of manually specifying the project's repositories and relays for every command, you can define them once as a named "set". You can then reference this set by its name in commands. This allows you to use the set as a shortcut for a list of relays (--relays <set_name>) or as the project's address in commands like issue and patch.

Sets are defined in your configuration file. To use a specific configuration file, pass its path using the --config option.

Create a Set

n34 sets new command

Usage:

Create a new set

Usage: n34 sets new [OPTIONS] <NAME>

Arguments:
  <NAME>  Unique name for the set

Options:
      --set-relay <RELAYS>         Optional relay to add it to the set, either as URL or set name to extract its relays. [aliases: `--sr`]
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Each set requires a unique name, provided as the final argument to the command. Use the --set-relays/--sr option to specify the relays for the new set; this can be a relay URL or the name of an existing set whose relays you wish to use. To add repositories, use the --repo option. Check passing repositories format.

Modify a Set

n34 sets update command

Usage:

Modify an existing set

Usage: n34 sets update [OPTIONS] <NAME>

Arguments:
  <NAME>  Name of the set to update

Options:
      --set-relay <RELAYS>         Add relay to the set, either as URL or set name to extract its relays. [aliases: `--sr`]
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
      --override                   Replace existing relays/repositories instead of adding to them

Use this command to update an existing set by its name. By default, providing relays via --set-relay or repositories via --repo will add them to the set's existing entries. To replace the current relays and repositories with the new values, use the --override flag.

Show a Set

n34 sets show command

Usage:

Show a single set or all the stored sets

Usage: n34 sets show [NAME]

Arguments:
  [NAME]  Name of the set to display. If not provided, lists all available sets

Prints all set names to standard output, each followed by its associated repos and relays. To view the details for a specific set, provide its name as an argument.

Remove a Set

n34 sets remove command

Usage:

Remove a set, or specific repos and relays within it

Usage: n34 sets remove [OPTIONS] <NAME>

Arguments:
  <NAME>  Set name to delete

Options:
      --set-relay <RELAYS>         Specific relay to remove it from the set, either as URL or set name to extract its relays. [aliases: `--sr`]
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Removes an entire set, or specific repositories and relays from it. Without options, this command deletes the entire set.

See the passing repositories section for more details on supported formats.

Manage Configuration

Configuration allows you to set default values for various command parameters, such as fallback relays, Proof of Work (PoW) difficulty, a default bunker URL, and your Nostr private key (keyring). This avoids the need to enter your private key, bunker URL, relays, or PoW difficulty for every command, making n34 more convenient to use.

Default PoW Difficulty

n34 config pow

Usage:

Sets the default PoW difficulty (0 if not specified)

Usage: n34 config pow <DIFFICULTY>

Arguments:
  <DIFFICULTY>  The new default PoW difficulty

This command configures the default Proof of Work (PoW) difficulty for newly created events. This setting is applied to most generated events, but it intentionally skips patch events. Because patches can be numerous, calculating PoW for each one would significantly slow down operations.

If you want to disable the PoW just make it 0.

Fallback Relays

n34 config relays command

Usage:

Sets the default fallback relays if none provided. Use this relays for read and write

Usage: n34 config relays [OPTIONS] [RELAYS]...

Arguments:
  [RELAYS]...  List of relay URLs to append to fallback relays. If empty, removes all fallback relays

Options:
      --override  Replace existing fallback relays instead of appending new ones

This command configures the default fallback relays, which n34 uses to read from and write to. To add relays, provide their URLs as arguments to append them to the current list. Use the --override flag to replace the existing list entirely. To clear all fallback relays, run the command without any arguments.

NIP-07 Browser Signer Proxy

n34 config nip07

Usage:

Manage the NIP-07 browser signer proxy by enabling or disabling it and configuring the `ip:port` address.

Usage: n34 config nip07 [OPTIONS] <--enable|--disable>

Options:
      --enable       Enable NIP-07 as the default signer
      --disable      Disable NIP-07 as the default signer
      --addr <ADDR>  Set the `ip:port` for the browser signer proxy (default: 127.0.0.1:51034)

Use NIP-07 (Browser Extension Signer) as your default signer. This is achieved by running a proxy at the specified ADDR, which defaults to 127.0.0.1:51034. The proxy forwards n34 requests to the browser signer and relays the responses back.

NIP-46 Bunker

n34 config bunker command

Usage:

Sets a URL of NIP-46 bunker server used for signing events

Usage: n34 config bunker [BUNKER_URL]

Arguments:
  [BUNKER_URL]  Nostr Connect URL for the bunker. Omit this to remove the current bunker URL

This command configures n34 to use a remote signer (NIP-46), known as a bunker, for all cryptographic operations.

When n34 communicates with the bunker, it uses a persistent, locally-generated keypair. You should add this keypair's public key to your bunker's list of authorized applications. This allows n34 to operate securely without needing direct access to your main private key.

Once configured, actions such as fetching your public key or signing events are delegated to the bunker. To remove the bunker configuration, run the command again without providing a URL.

Secret Key Keyring

n34 config keyring command

Usage:

Manages the secret key keyring, including enabling, disabling, or resetting it.

Usage: n34 config keyring <--enable|--disable|--reset>

Options:
      --enable   Enables the secret key keyring. You will be prompted for your key one last time to store it.
      --disable  Disables the secret key keyring. This removes the stored key and prevents new ones from being saved.
      --reset    Resets the keyring. This deletes the current key, allowing a new one to be stored on the next use.

To avoid entering your private key for every command, you can enable the keyring to store it securely. First, run n34 config keyring --enable. The next time you run an n34 command that requires your private key, it will be saved to your system's keyring. You will not need to enter it again for subsequent commands.

To replace the stored key with a new one, use the --reset flag. To stop using the keyring and remove the stored key, use the --disable flag.

n34 uses your operating system's native secret management system. For example, it uses keyutils on Linux and Keychain on macOS.

Manage Repositories

In n34 you can manage your repositories. This includes announcing new ones, viewing existing ones, and announcing state updates (coming soon).

Broadcast and Update a Git Repository

n34 repo announce command

Usage:

Broadcast and update a git repository

Usage: n34 repo announce [OPTIONS] --id <REPO_ID>

Options:
      --id <REPO_ID>               Unique identifier for the repository in kebab-case
  -n, --name <NAME>                A name for the repository
  -d, --description <DESCRIPTION>  A description for the repository
  -w, --web <WEB>                  Webpage URLs for the repository (if provided by the git server)
  -c, --clone <CLONE>              URLs for cloning the repository
  -m, --maintainers <MAINTAINERS>  Additional maintainers of the repository (besides yourself)
  -l, --label <LABEL>              Labels to categorize the repository. Can be specified multiple times
      --force-id                   Skip kebab-case validation for the repository ID
      --address-file               If set, creates a `nostr-address` file to enable automatic address discovery by n34

This command generates an announcement event to publish your project. It can be used to announce a new repository or update an existing one.

When updating, you must resubmit all repository fields, not just the fields you wish to change. The command uses this information to build and publish a completely new announcement event that will replace the old one.

It is recommended to use the --address-file flag. This option creates a nostr-address file that enables n34 to automatically discover the repository's address, simplifying the workflow for contributors.

View Git Repository Details

n34 repo view command

Usage:

View details of a nostr git repository

Usage: n34 repo view [NADDR-NIP05-OR-SET]...

Arguments:
  [NADDR-NIP05-OR-SET]...  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

This command prints repository details to standard output. If no arguments are provided, it looks for a nostr-address file in the current directory and displays the details for the address specified within it. See passing repositories for details on accepted formats.

Repository State Announcements

n34 repo state command

Usage:

Repository state announcements

Usage: n34 repo state [OPTIONS] <HEAD>

Arguments:
  <HEAD>  Name of the repository's primary branch, such as 'master' or 'main'

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
      --tags <TAGS>                Tags to announce a state for, in the format `<tag-name>=<commit-id>`. Separated by comma
      --branches <BRANCHES>        Branches to announce a state for, in the format `<branch-name>=<commit-id>`. Separated by comma

This command allows you to announce your repository state, which is useful for pushing to permissionless git repositories like the GRASP relay. The relay will verify your repository state and permit pushing commits only if they match the announced state.

To get the commit ID that a branch or tag points to, use git rev-parse <tag-or-branch-name>. You can automate this process by creating a script to generate the required input for this command.

Issue Management

Using n34, you can manage Git issues stored in Nostr relays, adhering to the NIP-34 standard. In Nostr, events are immutable, meaning their IDs are derived from the SHA-256 hash of their timestamp, content, author, and tags. As a result, issues cannot be edited directly. However, with n34, you can create new issues, view existing ones, or update their status—such as closing, resolving, or reopening them.

NIP-34 introduces support for drafting issues, though this feature is not currently implemented in n34 due to the lack of a clear use case for drafting issues. The inclusion of this functionality may stem from its shared use in both issues and patches, suggesting it was primarily designed for patch management.

Create an Issue

n34 issue new Command

Usage:

Create a new repository issue

Usage: n34 issue new [OPTIONS] <--content <CONTENT>|--editor>

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
  -c, --content <CONTENT>          Markdown content for the issue. Cannot be used together with the `--editor` flag
  -e, --editor                     Opens the user's default editor to write issue content. The first line will be used as the issue subject
      --subject <SUBJECT>          The issue subject. Cannot be used together with the `--editor` flag
  -l, --label <LABEL>              Labels for the issue. Can be specified as arguments (-l bug) or hashtags in content (#bug)

Use the n34 issue new command to create a new issue in a repository. This command supports the [NIP-21] (nostr: URI scheme) and hashtags within the issue content. When you mention public keys in the content, they will be included in the event tags. Additionally, using hashtags like #bug in the issue body will automatically apply them as labels.

You must choose between the --content and --editor options. With --content, you provide the issue content directly in the command. With --editor, your default $EDITOR will open, allowing you to write the issue content. The first line of the editor's output will be used as the issue subject.

View an Issue By ID

n34 issue view command

Usage:

View an issue by its ID

Usage: n34 issue view [OPTIONS] <ISSUE_ID>

Arguments:
  <ISSUE_ID>  The issue id to view it

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Simply provide the issue ID in note or nevent format to retrieve and display the issue details.

Reopen a Closed Issue

n34 issue reopen command

Usage:

Reopens a closed issue

Usage: n34 issue reopen [OPTIONS] <ISSUE_ID>

Arguments:
  <ISSUE_ID>  The ID of the closed issue to reopen

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1630 (Open status) for the specified issue. The issue have to be closed.

Closes an Open Issue

n34 issue close command

Usage:

Closes an open issue

Usage: n34 issue close [OPTIONS] <ISSUE_ID>

Arguments:
  <ISSUE_ID>  The open issue id to close it

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1632 (Close status) for the specified issue. The issue have to be open.

Resolves an Issue

n34 issue resolve command

Usage:

Resolves an issue

Usage: n34 issue resolve [OPTIONS] <ISSUE_ID>

Arguments:
  <ISSUE_ID>  The issue id to resolve it

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1631 (Resolved status) event for the specified issue.

List Repositories Issues

n34 issue list command

Usage:

List the repositories issues

Usage: n34 issue list [OPTIONS] [NADDR-NIP05-OR-SET]...

Arguments:
  [NADDR-NIP05-OR-SET]...  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Options:
      --limit <LIMIT>  Maximum number of issues to list [default: 15]

List the repositories issues. By default n34 will look for nostr-address file and extract the repositories from it.

Patch Management

In n34, patch management is designed to give you complete control. You can manually generate patch files using git-format-patch and then broadcast them to Nostr relays. This ensures that you have full authority over the content and structure of your patches, allowing for precise customization as per your requirements.

Similarly, when fetching patches, n34 provides them to you without automatically applying, merging, or checking them. This empowers you to review the patches at your own pace and decide whether to merge or apply them as needed. You retain full control over the entire process, ensuring a tailored approach to patch management.

Patch Status Management

You can assign a status to original patches, but revision patches do not have a specific status assigned to them. Instead, they inherit the status of the original patch. However, if the original patch is marked as Applied/Merged, the revision patch must be explicitly tagged to claim the same status. If not tagged, the revision patch status will be Closed.

Send Patches to a Repository

n34 patch send command

Usage:

Send one or more patches to a repository

Usage: n34 patch send [OPTIONS] <PATCH-PATH>...

Arguments:
  <PATCH-PATH>...  List of patch files to send (space separated)

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
      --original-patch <EVENT-ID>  Original patch ID if this is a revision of it

Send your generated patches to the repositories specified using the --repo option or retrieved from the nostr-address file. When submitting a revision of an existing patch, include the original patch ID to ensure it’s correctly referenced in your revision patch event.

Fetch a Patch By ID

n34 patch fetch command

Usage:

Fetches a patch by its id

Usage: n34 patch fetch [OPTIONS] <PATCH_ID>

Arguments:
  <PATCH_ID>  The patch id to fetch it

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
  -o, --output <PATH>              Output directory for the patches. Default to the current directory

Fetches patches using their original patch ID. All fetched patches will be saved to the specified output directory (current directory by default). You can then apply or merge these patches into your branch as needed.

Reopens a Closed or Drafted Patch

n34 patch reopen command

Usage:

Reopens a closed or drafted patch

Usage: n34 patch reopen [OPTIONS] <PATCH_ID>

Arguments:
  <PATCH_ID>  The closed/drafted patch id to reopen it. Must be orignal root patch

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1632 (Close status) for the specified patch. The patch have to be closed or drafted.

Closes an Open or Drafted Patch

n34 patch close command

Usage:

Closes an open or drafted patch

Usage: n34 patch close [OPTIONS] <PATCH_ID>

Arguments:
  <PATCH_ID>  The open/drafted patch id to close it. Must be orignal root patch

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1632 (Close status) for the specified patch. The patch have to be open or drafted.

Draft an Open Patch

n34 patch draft command

Usage:

Converts an open patch to draft state

Usage: n34 patch draft [OPTIONS] <PATCH_ID>

Arguments:
  <PATCH_ID>  The open patch id to draft it. Must be orignal root patch

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Issue a kind 1633 (Draft status) for the specified patch. The patch have to be open.

Apply an Open Patch

n34 patch apply command

Usage:

Set an open patch status to applied

Usage: n34 patch apply [OPTIONS] <PATCH_ID> [APPLIED_COMMITS]...

Arguments:
  <PATCH_ID>            The open patch id to apply it. Must be orignal root patch or revision root
  [APPLIED_COMMITS]...  The applied commits

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
      --patches <PATCH-EVENT-ID>   Patches that have been applied. Use this when only some patches have been applied, not all

Creates a kind 1631 event (Applied/Merged status) for the specified patch. The patch must be in open status.

You can specify either an original patch or revision patch ID, but the status event will only reference the original patch. Revision patches will be mentioned in the event.

The APPLIED_COMMITS field serves to inform clients about the status of specific commits, whether they have been applied or not. If you need to retrieve the list of commits from a specific point (such as the tip of the master branch) up to the HEAD, you can use the following Git command: git log --pretty=%H 'origin/master..HEAD'.

Merge an Open Patch

n34 patch merge command

Usage:

Set an open patch status to merged

Usage: n34 patch merge [OPTIONS] <PATCH_ID> <MERGE_COMMIT>

Arguments:
  <PATCH_ID>      The open patch id to merge it. Must be orignal root patch or revision root
  <MERGE_COMMIT>  The merge commit id

Options:
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
      --patches <PATCH-EVENT-ID>   Patches that have been merged. Use this when only some patches have been merged, not all

Creates a kind 1631 event (Applied/Merged status) for the specified patch. The patch must be in open status.

You can specify either an original patch or revision patch ID, but the status event will only reference the original patch. Revision patches will be mentioned in the event.

You can get the MERGE_COMMIT commit using git rev-parse HEAD command if the merge commit in the HEAD or use HEAD~n where the n is the number of commits the merge commit before the HEAD

List Repositories Patches

n34 patch list command

Usage:

List the repositories patches

Usage: n34 patch list [OPTIONS] [NADDR-NIP05-OR-SET]...

Arguments:
  [NADDR-NIP05-OR-SET]...  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`

Options:
      --limit <LIMIT>  Maximum number of patches to list [default: 15]

List the repositories patches. By default n34 will look for nostr-address file and extract the repositories from it.

Reply to Issues and Patches

n34 reply command

Usage:

Reply to issues and patches

Usage: n34 reply [OPTIONS] <--comment <COMMENT>|--editor> <nevent1-or-note1>

Arguments:
  <nevent1-or-note1>  The issue, patch, or comment to reply to

Options:
      --quote-to                   Quote the replied-to event in the editor
      --repo <NADDR-NIP05-OR-SET>  Repository address in `naddr` format (`naddr1...`), NIP-05 format (`4rs.nl/n34` or `_@4rs.nl/n34`), or a set name like `kernel`
  -c, --comment <COMMENT>          The comment (cannot be used with --editor)
  -e, --editor                     Open editor to write comment (cannot be used with --content)

Craft replies (NIP-22 Comment) to issues, patches, or comments with ease using the n34 reply command. You can either input your reply directly with the --comment option or open an editor for a more detailed response using --editor. Additionally, when using --editor, the --quote-to option allows you to include the original content in your editor, enabling precise and context-aware replies.